naturally 1.0.2 → 1.0.3

data/README.md

@@ -4,6 +4,11 @@ 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.
 
+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.
+
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -18,9 +23,36 @@ Or install it yourself as:
 
     $ gem install naturally
 
+
 ## Usage
 
-See the spec for examples.
+```Ruby
+# Sort a simple array of strings
+Naturally.sort(["1.1", "1.10", "1.2"])  # => ["1.1", "1.2", "1.10"]
+
+# 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')
+  ]
+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">]
+```
+
+See [the spec for more examples](https://github.com/dogweather/naturally/blob/master/spec/naturally_spec.rb).
+
 
 ## Contributing
 

data/lib/naturally/version.rb

@@ -1,3 +1,3 @@
 module Naturally
-  VERSION = "1.0.2"
+  VERSION = "1.0.3"
 end

data/lib/naturally.rb

@@ -3,14 +3,19 @@ require "naturally/version"
 module Naturally
   
   # Perform a natural sort.
-  # @param [Array<String>] a list of numbers to sort.
+  # @param [Array<String>] an_array the list of numbers to sort.
   # @return [Array<String>] the numbers sorted naturally.
   def self.sort(an_array)
     return an_array.sort_by{ |x| normalize(x) }
   end  
 
-  def self.normalize(version)
-    version.to_s.scan(%r/[0-9a-zA-Z]+/o).map{|i| NumberElement.new(i)}
+  # Convert the given number into and object that can be sorted
+  # naturally. 
+  # @param [String] number the number in complex form such as 1.2a.3.
+  # @return [Array<NumberElement>] an array of NumberElements which are
+  #         able to be sorted naturally via a normal 'sort'.
+  def self.normalize(number)
+    number.to_s.scan(%r/[0-9a-zA-Z]+/o).map{|i| NumberElement.new(i)}
   end
 
 

data/spec/naturally_spec.rb

@@ -32,4 +32,29 @@ describe Naturally do
       Naturally.sort(a).should == b
     end
   end
+  
+  describe '#normalize' do
+    it 'enables sorting objects by one particular attribute' do
+      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')
+        ]
+      sorted = objects.sort_by{ |o| Naturally.normalize(o.number) }
+      sorted.map{|o| o.name}.should == %w[
+        color
+        opacity
+        lightness
+        size
+        shape
+        hardness
+        weight
+        ]
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: naturally
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-08 00:00:00.000000000 Z
+date: 2012-12-15 00:00:00.000000000 Z
 dependencies: []
 description: Natural Sorting with support for legal numbering
 email: