README.md in naturally-1.0.3 vs README.md in naturally-1.0.4
- old
+ new
@@ -1,10 +1,11 @@
# Naturally
+[](https://travis-ci.org/dogweather/naturally)
-Natural sorting with support for legal document numbering.
-See [Counting to 10 in Californian](http://www.weblaws.org/blog/2012/08/counting-from-1-to-10-in-californian/)
-for the motivations to make this library.
+Natural sorting with added support for legal document numbering.
+See [Sorting for Humans : Natural Sort Order](http://www.codinghorror.com/blog/2007/12/sorting-for-humans-natural-sort-order.html) and [Counting to 10 in Californian](http://www.weblaws.org/blog/2012/08/counting-from-1-to-10-in-californian/)
+for the motivations to make this library. This is also the kind of ordering you want if you're sorting version numbers.
The core of the search is [from here](https://github.com/ahoward/version_sorter). I then made
several changes to handle the particular types of numbers that come up in statutes, such
as *335.1, 336, 336a*, etc.
@@ -17,39 +18,52 @@
And then execute:
$ bundle
-Or install it yourself as:
+Or install it outside of bundler with:
$ gem install naturally
## Usage
```Ruby
+require 'naturally'
+
# Sort a simple array of strings
Naturally.sort(["1.1", "1.10", "1.2"]) # => ["1.1", "1.2", "1.10"]
+```
+Usually, however, the library is used to sort an array of some kind of
+object:
+
+
+```Ruby
# Sort an array of objects by one attribute
Thing = Struct.new(:number, :name)
objects = [
- Thing.new('1.1', 'color'),
- Thing.new('1.2', 'size'),
- Thing.new('1.1.1', 'opacity'),
- Thing.new('1.1.2', 'lightness'),
- Thing.new('1.10', 'hardness'),
- Thing.new('2.1', 'weight'),
- Thing.new('1.3', 'shape')
+ Thing.new('1', 'USA'),
+ Thing.new('2', 'Canada'),
+ Thing.new('1.1', 'Oregon'),
+ Thing.new('1.2', 'Washington'),
+ Thing.new('1.1.1', 'Portland'),
+ Thing.new('1.10', 'Texas'),
+ Thing.new('2.1', 'British Columbia'),
+ Thing.new('1.3', 'California'),
+ Thing.new('1.1.2', 'Eugene')
]
objects.sort_by{ |o| Naturally.normalize(o.number) }
-# => [#<struct Thing number="1.1", name="color">,
- #<struct Thing number="1.1.1", name="opacity">,
- #<struct Thing number="1.1.2", name="lightness">,
- #<struct Thing number="1.2", name="size">,
- #<struct Thing number="1.3", name="shape">,
- #<struct Thing number="1.10", name="hardness">,
- #<struct Thing number="2.1", name="weight">]
+
+# Results in:
+[<struct Thing number="1.1", name="Oregon">,
+ <struct Thing number="1.1.1", name="Portland">,
+ <struct Thing number="1.1.2", name="Eugene">,
+ <struct Thing number="1.2", name="Washington">,
+ <struct Thing number="1.3", name="California">,
+ <struct Thing number="1.10", name="Texas">,
+ <struct Thing number="2", name="Canada">,
+ <struct Thing number="2.1", name="British Columbia">]
```
See [the spec for more examples](https://github.com/dogweather/naturally/blob/master/spec/naturally_spec.rb).