https://github.com/public-law/naturally

Natural sort algorithm
https://github.com/public-law/naturally

Keywords

array-comparison ruby sort sort-order

Keywords from Contributors

activejob activerecord mvc

Last synced: about 9 hours ago
JSON representation

Repository metadata

Natural sort algorithm

Host: GitHub
URL: https://github.com/public-law/naturally
Owner: public-law
License: mit
Created: 2012-12-08T08:42:47.000Z (about 13 years ago)
Default Branch: master
Last Pushed: 2025-06-14T23:07:17.000Z (9 months ago)
Last Synced: 2026-01-21T09:59:51.807Z (about 1 month ago)
Topics: array-comparison, ruby, sort, sort-order
Language: Ruby
Homepage:
Size: 114 KB
Stars: 120
Watchers: 4
Forks: 20
Open Issues: 5
Releases: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt

Naturally

Natural ("version number") sorting with support for:

file names,
legal document numbering,
college course codes, and
Unicode.

See Jeff Atwood's Sorting for Humans: Natural Sort Order.

Installation

$ gem install naturally

Usage

`#sort`

require 'naturally'

# Sort version numbers
Naturally.sort(["13.10", "13.04", "10.10", "10.04.4"])
          # => ["10.04.4", "10.10", "13.04", "13.10"]

# Sort legal section numbers
Naturally.sort(["336", "335a", "335", "335.1"])
          # => ["335", "335.1", "335a", "336"]

The library can also sort an array of objects:

# Define a new simple object for storing Ubuntu versions
UbuntuVersion = Struct.new(:name, :version)

# Create an array
releases = [
  UbuntuVersion.new('Saucy Salamander', '13.10'),
  UbuntuVersion.new('Raring Ringtail',  '13.04'),
  UbuntuVersion.new('Precise Pangolin', '12.04.4'),
  UbuntuVersion.new('Maverick Meerkat', '10.10'),
  UbuntuVersion.new('Quantal Quetzal',  '12.10'),
  UbuntuVersion.new('Lucid Lynx',       '10.04.4')
]

# Sort by the version attribute
Naturally.sort(releases, by: :version)

=> [#<struct UbuntuVersion name="Lucid Lynx",       version="10.04.4">,
    #<struct UbuntuVersion name="Maverick Meerkat", version="10.10">,
    #<struct UbuntuVersion name="Precise Pangolin", version="12.04.4">,
    #<struct UbuntuVersion name="Quantal Quetzal",  version="12.10">,
    #<struct UbuntuVersion name="Raring Ringtail",  version="13.04">,
    #<struct UbuntuVersion name="Saucy Salamander", version="13.10">]

More examples are in the specs.

`#sort_filenames`

Sorts 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.

files = [
  'abc_2.tif',
  'abc_1_a.tif',
  'abc_1.zzz',
  'abc_1_xyz.abc',
  'abc_2a.tif',
  'abc.2.tif',
  'abc.1_a.tif',
  'abc_2.abc',
  'abc_1_xyz.abc'
]
Naturally.sort_filenames(files)
# => [
#   "abc.1_a.tif",
#   "abc.2.tif",
#   "abc_1.zzz",
#   "abc_1_a.tif",
#   "abc_1_xyz.abc",
#   "abc_1_xyz.abc",
#   "abc_2.abc",
#   "abc_2.tif",
#   "abc_2a.tif"
# ]

This method gives higher priority to dots than underscores, so files like abc.1_a.tif will come before abc.2.tif.

Implementation Notes

The algorithm capitalizes on Ruby's array comparison behavior:
Since each dotted number actually represents a hierarchical
identifier, array comparison
is a natural fit:

Arrays are compared in an “element-wise” manner; the first element of ary is compared with the first one of other_ary using the <=> 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.

And so, when given input such as,

['1.9', '1.9a', '1.10']

...this module sorts the segmented numbers
by comparing them in their array forms:

[['1', '9'], ['1', '9a'], ['1', '10']]

Finally, upon actual sort comparison, each of these strings is
converted to an array of typed objects. This is to determine the
sort order between heterogenous (yet ordered) segments such as
'9a' and '9'.

The final nested comparison structure looks like this:

  [
   [
     [1], [9]
   ],
   [
     [1], [9, 'a']
   ],
   [
     [1], [10]
   ]
  ]

Related Work

ahoward/version_sorter, the starting point for the naturally gem.
GitHub's Version sorter

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

Owner metadata

Name: Public.Law
Login: public-law
Email: hello@public.law
Kind: organization
Description: Law is code; open-source it
Website: https://public.law
Location: Denver, CO
Twitter: law_is_code
Company:
Icon url: https://avatars.githubusercontent.com/u/32751043?v=4
Repositories: 26
Last ynced at: 2025-10-14T14:44:47.464Z
Profile URL: https://github.com/public-law

GitHub Events

Total

Issues event: 2
Watch event: 16
Delete event: 2
Issue comment event: 2
Push event: 14
Pull request event: 7
Create event: 4

Last Year

Issues event: 2
Watch event: 16
Delete event: 2
Issue comment event: 2
Push event: 14
Pull request event: 7
Create event: 4

Committers metadata

Last synced: 3 days ago

Total Commits: 123
Total Committers: 13
Avg Commits per committer: 9.462
Development Distribution Score (DDS): 0.325

Commits in past year: 13
Committers in past year: 1
Avg Commits per committer in past year: 13.0
Development Distribution Score (DDS) in past year: 0.0

Name	Email	Commits
Robb Shecter	r**b@w**g	83
Robb Shecter	r**b@p**w	27
Penn Taylor	r**3@g**m	2
Anton Rieder	1****r	2
Theodor Tonum	t**r@t**o	1
Santiago Castro	s**0@h**m	1
Pierre Yager	p**e@l**t	1
KD	k**r@y**n	1
Joshua Huber	j**r@b**m	1
Joan Roig	r**u@g**m	1
Jake Heimark	j**k@m**m	1
Ivan	l**r@g**m	1
Jeff Olfert	j**t@f**m	1

Committer domains:

Issue and Pull Request metadata

Last synced: 4 months ago

Total issues: 9
Total pull requests: 28
Average time to close issues: over 1 year
Average time to close pull requests: 3 months
Total issue authors: 8
Total pull request authors: 13
Average comments per issue: 2.22
Average comments per pull request: 1.11
Merged pull request: 22
Bot issues: 0
Bot pull requests: 0

Past year issues: 1
Past year pull requests: 4
Past year average time to close issues: 10 minutes
Past year average time to close pull requests: 3 minutes
Past year issue authors: 1
Past year pull request authors: 1
Past year average comments per issue: 0.0
Past year average comments per pull request: 0.0
Past year merged pull request: 4
Past year bot issues: 0
Past year bot pull requests: 0

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/public-law/naturally

Top Issue Authors

schlick (2)
jeropaul (1)
bibendi (1)
evanlemke (1)
Kris-LIBIS (1)
dogweather (1)
zedalaye (1)
gucki (1)

Top Pull Request Authors

dogweather (17)
aried3r (5)
theodorton (1)
evanlemke (1)
kuldeepaggarwal (1)
bryant1410 (1)
uberjay (1)
Loriowar (1)
Fonsan (1)
hmk (1)
penntaylor (1)
zedalaye (1)
novito (1)

Top Issue Labels

enhancement (2)

Top Pull Request Labels

Package metadata

Total packages: 2
Total downloads:
- rubygems: 229,827,224 total
Total docker downloads: 84,875,766
Total dependent packages: 18 (may contain duplicates)
Total dependent repositories: 20,145 (may contain duplicates)
Total versions: 44
Total maintainers: 1

gem.coop: naturally

Natural Sorting with support for legal numbering, course numbers, and other number/letter mixes.

Homepage: http://github.com/public-law/naturally
Documentation: http://www.rubydoc.info/gems/naturally/
Licenses: MIT
Latest release: 2.3.0 (published 9 months ago)
Last Synced: 2026-02-27T07:02:13.892Z (4 days ago)
Versions: 22
Dependent Packages: 0
Dependent Repositories: 0
Downloads: 115,000,651 Total
Docker Downloads: 42,437,883
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 0.217%
- Downloads: 0.234%
- Docker downloads count: 0.633%
Maintainers (1)
- dogweather

rubygems.org: naturally