module Naturally

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:

1. sort(objects) # Simple arrays

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

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