naturally 1.3.2 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 11b862eddf78c3c623300fc93d643a1b0081f815
-  data.tar.gz: 576b16fec163a92e756c98c1df4f3b1af8ebab31
+  metadata.gz: a5b55ef725bab4abf9e87b176f86ab6c94d1ea4d
+  data.tar.gz: 2ca443c6027ed127aa570dceb2bdf63aeb060457
 SHA512:
-  metadata.gz: 08f910f8cd088cb92969c6f1d257cc53a2178e54894639bac1b361651c986f312e90c6cd42eacb202b89fc664dbf1108d76b474578a40e0a35462bb6ab4f23fe
-  data.tar.gz: 1f389ebe3746dc8d2f5c80cd35eb0dcdf4e408fd5f9116945e3355bdf2e037ecff46a60ca458bb3e02df5a701b3847460c184d4ba29012248aae2a09b32e26c9
+  metadata.gz: 85d8b14a18c0415b1360ce03a0eabad8e0cdfa07656648d71d251ac9556194aa705ff547b7cf5c6143762e876f425c4c05369047bef7368bdadaff24ce6d3705
+  data.tar.gz: df7f7705855241de8b0b1f4b26a4996398b90bfc5631088e5bcc9a141d2f98bc149a6192e9a19360b825839106ec06b3c12f586c327736b378eccb3f5c96694a

data/Gemfile

@@ -1,8 +1,8 @@
 source 'https://rubygems.org'
 
 group :test do
-  gem 'rspec', '~> 3.0'
-  gem 'rake', '~> 10.0'
+  gem 'rspec', '~> 3'
+  gem 'rake', '~> 10'
 end
 
 # Specify your gem's dependencies in naturally.gemspec

data/README.md

@@ -4,6 +4,11 @@
 Natural (version number) sorting with support for **legal document numbering**, **college course codes**, and **Unicode**.
 See Jeff Atwood's [Sorting for Humans: Natural Sort Order](http://www.codinghorror.com/blog/2007/12/sorting-for-humans-natural-sort-order.html) and the WebLaws.org post [Counting to 10 in Californian](http://www.weblaws.org/blog/2012/08/counting-from-1-to-10-in-californian/).
 
+##Installation
+
+```Shell
+$ gem install naturally
+```
 
 ## Usage
 
@@ -11,7 +16,7 @@ See Jeff Atwood's [Sorting for Humans: Natural Sort Order](http://www.codinghorr
 require 'naturally'
 
 # Sort a simple array of strings
-Naturally.sort(["1.1", "1.10", "1.2"])  # => ["1.1", "1.2", "1.10"]
+Naturally.sort(["336", "335a", "335", "335.1"])  # => ["335", "335.1", "335a", "336"]
 ```
 
 Usually the library is used to sort an array of objects:
@@ -45,7 +50,52 @@ expect(sorted.map(&:name)).to eq [
 ]
 ```
 
-See [the spec for more examples](https://github.com/dogweather/naturally/blob/master/spec/naturally_spec.rb) of what Naturally can sort.
+[More examples are in the specs](https://github.com/dogweather/naturally/blob/master/spec/naturally_spec.rb).
+
+
+## Implementation Notes
+
+The algorithm capitalizes on Ruby's array comparison behavior:
+Since each dotted number actually represents a hierarchical 
+identifier, [array comparison](http://ruby-doc.org/core-2.2.1/Array.html#method-i-3C-3D-3E) 
+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,
+
+```ruby
+['1.9', '1.9a', '1.10']
+```
+
+...this module sorts the segmented numbers 
+by comparing them in their array forms:
+
+```ruby
+[['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:
+
+```ruby
+  [
+   [
+     [1], [9]
+   ],
+   [
+     [1], [9, 'a']
+   ],
+   [
+     [1], [10]
+   ]
+  ]
+```
 
 ## Related Work
 

data/lib/naturally.rb

@@ -2,11 +2,6 @@ require 'naturally/segment'
 
 # A module which performs natural sorting on a variety of number
 # formats. (See the specs for examples.)
-#
-# It achieves this by capitalizing on Ruby's behavior when
-# comparing arrays: The module sorts arrays of segmented numbers such as
-# ['1.9', '1.9a', '1.10'] by comparing them in their array forms.
-# I.e., approximately [['1', '9'], ['1, '9a'], ['1', '10']]
 module Naturally
   # Perform a natural sort.
   #
@@ -29,8 +24,8 @@ module Naturally
   # This enables it to be sorted against other arrays
   # by the standard #sort method.
   #
-  # For example:
-  # '1.2a.3' becomes [Segment<'1'>, Segment<'2a'>, Segment<'3'>]
+  # For example, '1.2a.3' becomes
+  # [Segment<'1'>, Segment<'2a'>, Segment<'3'>]
   #
   # @param [String] complex_number the number in a hierarchical form
   #                 such as 1.2a.3.

data/lib/naturally/segment.rb

@@ -13,15 +13,30 @@ module Naturally
       to_array <=> other.to_array
     end
 
+    # @return [Array] a representation of myself in array form
+    #                 which enables me to be compared against
+    #                 another instance for sorting.
+    #                 The array is prepended with a symbol so
+    #                 two arrays are always comparable.
+    #
+    # @example a simple number
+    #   Segment.new('10').to_array #=> [:int, 10]
+    #
+    # @example a college course code
+    #   Segment.new('MATH101').to_array #=> [:str, "MATH", 101]
+    #
+    # @example Section 633a of the ADEA
+    #   Segment.new('633a').to_array #=> [:int, 633, "a"]
     def to_array
+      # TODO: Refactor, probably via polymorphism
       if @val =~ /^(\p{Digit}+)(\p{Alpha}+)$/
-        [$1.to_i, $2]
+        [:int, $1.to_i, $2]
       elsif @val =~ /^(\p{Alpha}+)(\p{Digit}+)$/
-        [$1, $2.to_i]
+        [:str, $1, $2.to_i]
       elsif @val =~ /^\p{Digit}+$/
-        [@val.to_i]
+        [:int, @val.to_i]
       else
-        [@val]
+        [:str, @val]
       end
     end
   end

data/lib/naturally/version.rb

@@ -1,3 +1,4 @@
 module Naturally
-  VERSION = '1.3.2'
+  # Gem version
+  VERSION = '1.4.0'
 end

data/naturally.gemspec

@@ -1,4 +1,3 @@
-# -*- encoding: utf-8 -*-
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'naturally/version'
@@ -12,6 +11,7 @@ Gem::Specification.new do |gem|
   gem.summary       = %q{Sorts numbers according to the way people are used to seeing them.}
   gem.description   = %q{Natural Sorting with support for legal numbering, course numbers, and other number/letter mixes.}
   gem.homepage      = "http://github.com/dogweather/naturally"
+  gem.required_ruby_version = '>= 2.1'
 
   gem.files         = `git ls-files`.split($/)
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }

data/spec/naturally_spec.rb

@@ -1,4 +1,3 @@
-# encoding: utf-8
 require 'naturally'
 
 describe Naturally do
@@ -63,6 +62,34 @@ describe Naturally do
         to_this: %w(2 3 4 5 10 11 12 12а 12б 12в 13а 13б)
       )
     end
+
+    it 'sorts letters with digits correctly' do
+      it_sorts(
+        this: %w(1 a 2 b 3 c),
+        to_this: %w(1 2 3 a b c)
+      )
+    end
+
+    it 'sorts complex numbers with digits correctly' do
+      it_sorts(
+        this: %w(1 a 2 b 3 c 1.1 a.1 1.2 a.2 1.3 a.3 b.1 ),
+        to_this: %w(1 1.1 1.2 1.3 2 3 a a.1 a.2 a.3 b b.1 c)
+      )
+    end
+
+    it 'sorts complex mixes of numbers and digits correctly' do
+      it_sorts(
+        this: %w( 1.a.1 1.1 ),
+        to_this: %w( 1.1 1.a.1 )
+      )
+    end
+
+    it 'sorts complex mixes of numbers and digits correctly' do
+      it_sorts(
+        this: %w( 1a1 1aa aaa ),
+        to_this: %w( 1aa 1a1 aaa )
+      )
+    end
   end
 
   describe '#sort_naturally_by' do
@@ -109,5 +136,18 @@ describe Naturally do
         Париж
       )
     end
+
+    it 'sorts by an attribute which contains product names' do
+      Product = Struct.new(:name)
+      objects = [
+          Product.new('2 awesome decks'),
+          Product.new('Awesome deck')
+      ]
+      actual = Naturally.sort_by(objects, :name)
+      expect(actual.map(&:name)).to eq [
+        '2 awesome decks',
+        'Awesome deck'
+      ]
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: naturally
 version: !ruby/object:Gem::Version
-  version: 1.3.2
+  version: 1.4.0
 platform: ruby
 authors:
 - Robb Shecter
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-03-11 00:00:00.000000000 Z
+date: 2015-08-04 00:00:00.000000000 Z
 dependencies: []
 description: Natural Sorting with support for legal numbering, course numbers, and
   other number/letter mixes.
@@ -41,7 +41,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -49,7 +49,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.6
+rubygems_version: 2.4.8
 signing_key: 
 specification_version: 4
 summary: Sorts numbers according to the way people are used to seeing them.