{"id":28991251,"url":"https://github.com/public-law/naturally","last_synced_at":"2025-11-11T19:28:24.409Z","repository":{"id":5849049,"uuid":"7065608","full_name":"public-law/naturally","owner":"public-law","description":"Natural sort algorithm","archived":false,"fork":false,"pushed_at":"2025-06-14T23:07:17.000Z","size":117,"stargazers_count":120,"open_issues_count":5,"forks_count":20,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-11-02T11:11:14.459Z","etag":null,"topics":["array-comparison","ruby","sort","sort-order"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/public-law.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2012-12-08T08:42:47.000Z","updated_at":"2025-09-23T21:57:43.000Z","dependencies_parsed_at":"2024-06-02T22:24:59.673Z","dependency_job_id":"f4d4f48c-96a3-4060-b350-dfea2e4ef13b","html_url":"https://github.com/public-law/naturally","commit_stats":{"total_commits":106,"total_committers":14,"mean_commits":7.571428571428571,"dds":"0.21698113207547165","last_synced_commit":"c884159e88a48bbea258d62818a21aee588adbaf"},"previous_names":["public-law/naturally","dogweather/naturally"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/public-law/naturally","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/public-law%2Fnaturally","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/public-law%2Fnaturally/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/public-law%2Fnaturally/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/public-law%2Fnaturally/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/public-law","download_url":"https://codeload.github.com/public-law/naturally/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/public-law%2Fnaturally/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":282762578,"owners_count":26723111,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-05T02:00:05.946Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["array-comparison","ruby","sort","sort-order"],"created_at":"2025-06-25T01:02:36.732Z","updated_at":"2025-11-11T19:28:24.390Z","avatar_url":"https://github.com/public-law.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"# Naturally\n[![Gem Version](https://badge.fury.io/rb/naturally.svg)](https://badge.fury.io/rb/naturally)\n\nNatural (\"version number\") sorting with support for:\n\n* **file names**,\n* **legal document numbering**,\n* **college course codes**, and\n* **Unicode**.\n\nSee Jeff Atwood's [Sorting for Humans: Natural Sort Order](https://blog.codinghorror.com/sorting-for-humans-natural-sort-order/).\n\n\n## Installation\n\n```Shell\n$ gem install naturally\n```\n\n## Usage\n\n### `#sort`\n\n```Ruby\nrequire 'naturally'\n\n# Sort version numbers\nNaturally.sort([\"13.10\", \"13.04\", \"10.10\", \"10.04.4\"])\n          # =\u003e [\"10.04.4\", \"10.10\", \"13.04\", \"13.10\"]\n\n# Sort legal section numbers\nNaturally.sort([\"336\", \"335a\", \"335\", \"335.1\"])\n          # =\u003e [\"335\", \"335.1\", \"335a\", \"336\"]\n```\n\nThe library can also sort an array of objects:\n\n```Ruby\n# Define a new simple object for storing Ubuntu versions\nUbuntuVersion = Struct.new(:name, :version)\n\n# Create an array\nreleases = [\n  UbuntuVersion.new('Saucy Salamander', '13.10'),\n  UbuntuVersion.new('Raring Ringtail',  '13.04'),\n  UbuntuVersion.new('Precise Pangolin', '12.04.4'),\n  UbuntuVersion.new('Maverick Meerkat', '10.10'),\n  UbuntuVersion.new('Quantal Quetzal',  '12.10'),\n  UbuntuVersion.new('Lucid Lynx',       '10.04.4')\n]\n\n# Sort by the version attribute\nNaturally.sort(releases, by: :version)\n\n=\u003e [#\u003cstruct UbuntuVersion name=\"Lucid Lynx\",       version=\"10.04.4\"\u003e,\n    #\u003cstruct UbuntuVersion name=\"Maverick Meerkat\", version=\"10.10\"\u003e,\n    #\u003cstruct UbuntuVersion name=\"Precise Pangolin\", version=\"12.04.4\"\u003e,\n    #\u003cstruct UbuntuVersion name=\"Quantal Quetzal\",  version=\"12.10\"\u003e,\n    #\u003cstruct UbuntuVersion name=\"Raring Ringtail\",  version=\"13.04\"\u003e,\n    #\u003cstruct UbuntuVersion name=\"Saucy Salamander\", version=\"13.10\"\u003e]\n```\n\n[More examples are in the specs](https://github.com/public-law/naturally/blob/master/spec/naturally_spec.rb).\n\n\n### `#sort_filenames`\n\nSorts filenames naturally, treating underscores and dots as separators. Useful for sorting files like images or documents that use numbers, underscores, and dots in their names.\n\n```ruby\nfiles = [\n  'abc_2.tif',\n  'abc_1_a.tif',\n  'abc_1.zzz',\n  'abc_1_xyz.abc',\n  'abc_2a.tif',\n  'abc.2.tif',\n  'abc.1_a.tif',\n  'abc_2.abc',\n  'abc_1_xyz.abc'\n]\nNaturally.sort_filenames(files)\n# =\u003e [\n#   \"abc.1_a.tif\",\n#   \"abc.2.tif\",\n#   \"abc_1.zzz\",\n#   \"abc_1_a.tif\",\n#   \"abc_1_xyz.abc\",\n#   \"abc_1_xyz.abc\",\n#   \"abc_2.abc\",\n#   \"abc_2.tif\",\n#   \"abc_2a.tif\"\n# ]\n```\n\nThis method gives higher priority to dots than underscores, so files like `abc.1_a.tif` will come before `abc.2.tif`.\n\n\n## Implementation Notes\n\nThe algorithm capitalizes on Ruby's array comparison behavior:\nSince each dotted number actually represents a hierarchical \nidentifier, [array comparison](http://ruby-doc.org/core-2.2.1/Array.html#method-i-3C-3D-3E) \nis a natural fit:\n\n\u003e Arrays are compared in an “element-wise” manner; the first element of ary is compared with the first one of other_ary using the \u003c=\u003e operator, then each of the second elements, etc… As soon as the result of any such comparison is non zero (i.e. the two corresponding elements are not equal), that result is returned for the whole array comparison.\n\n\nAnd so, when given input such as,\n\n```ruby\n['1.9', '1.9a', '1.10']\n```\n\n...this module sorts the segmented numbers \nby comparing them in their array forms:\n\n```ruby\n[['1', '9'], ['1', '9a'], ['1', '10']]\n```\n\nFinally, upon actual sort comparison, each of these strings is \nconverted to an array of typed objects. This is to determine the \nsort order between heterogenous (yet ordered) segments such as \n`'9a'` and `'9'`.\n\nThe final nested comparison structure looks like this:\n\n```ruby\n  [\n   [\n     [1], [9]\n   ],\n   [\n     [1], [9, 'a']\n   ],\n   [\n     [1], [10]\n   ]\n  ]\n```\n\n## Related Work\n\n* [ahoward/version_sorter](https://github.com/ahoward/version_sorter), the starting point for the `naturally` gem.\n* [GitHub's Version sorter](https://github.com/github/version_sorter)\n\n\n## Contributing\n\n1. Fork it\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create new Pull Request\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpublic-law%2Fnaturally","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpublic-law%2Fnaturally","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpublic-law%2Fnaturally/lists"}