module Naturally
A module which performs natural sorting on a variety of number formats. (See the specs for examples.)
Constants
- VERSION
Gem version
Public Class Methods
Convert the given number to an array of {Segment}s. This enables it to be sorted against other arrays by the built-in sort method.
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.
@return [Array<Segment>] an array of Segments which
can be sorted naturally via a standard #sort.
# File lib/naturally.rb, line 47 def self.normalize(complex_number) tokens = complex_number.to_s.gsub(/\_/,'').scan(/\p{Word}+/) tokens.map { |t| Segment.new(t) } end
Perform a natural sort. Supports two syntaxes:
-
sort(objects) # Simple arrays
-
sort(objects, by: some_attribute) # Complex objects
@param [Array<String>] an_array the list of numbers to sort. @param [by] (optional) an attribute of the array by which to sort. @return [Array<String>] the numbers sorted naturally.
# File lib/naturally.rb, line 14 def self.sort(an_array, by:nil) if by.nil? an_array.sort_by { |x| normalize(x) } else self.sort_by(an_array, by) end end
Sort an array of objects “naturally” by a given attribute. If block is given, attribute is ignored and each object is yielded to the block to obtain the sort key.
@param [Array<Object>] an_array the list of objects to sort. @param [Symbol] an_attribute the attribute by which to sort. @param [Block] &block a block that should evaluate to the
sort key for the yielded object
@return [Array<Object>] the objects in natural sort order.
# File lib/naturally.rb, line 31 def self.sort_by(an_array, an_attribute=nil, &block) return sort_by_block(an_array, &block) if block_given? an_array.sort_by { |obj| normalize(obj.send(an_attribute)) } end
Private Class Methods
Sort an array of objects “naturally”, yielding each object to the block to obtain the sort key.
@param [Array<Object>] an_array the list of objects to sort. @param [Block] &block a block that should evaluate to the
sort key for the yielded object
@return [Array<Object>] the objects in natural sort order.
# File lib/naturally.rb, line 60 def self.sort_by_block(an_array, &block) an_array.sort_by { |obj| normalize(yield(obj)) } end