facets 3.0.0 → 3.2.0

data/lib/core/facets/array/arrange.rb

@@ -1,42 +1 @@
-class Array
-
-  # The `arrange` method produces appropriate ranges from the objects in the array.
-  #
-  # Examples
-  #
-  #     [1,2,3,6,7,8].arrange  #=> [1..3, 6..8]
-  #
-  #     [10..15, 16..20, 21, 22].arrange  #=> [10..22]
-  #
-  # Assumes inclusive ranges (ie. 1..4) and range.first <= range.last.
-  #
-  # Works with integers, dates and strings. However, all the objects in the array must
-  # be of the same class.
-  #
-  # CREDIT: monocle
-
-  def arrange
-		array = uniq.sort_by { |e| Range === e ? e.first : e }
-		array.inject([]) do |c, value|
-			unless c.empty?
-				last = c.last
-				last_value    = (Range === last  ? last.last   : last)
-				current_value = (Range === value ? value.first : value)
-				if (last_value.succ <=> current_value) == -1
-					c << value
-				else
-					first  = (Range === last ? last.first : last)
-					second = [Range === last ? last.last : last, Range === value ? value.last : value].max
-					c[-1] = [first..second]
-					c.flatten!
-				end
-			else
-				c << value
-			end
-		end
-	end
-
-  alias rangify arrange
-
-end
-
+require 'facets/array/to_ranges'

data/lib/core/facets/array/average.rb

@@ -0,0 +1,15 @@
+class Array
+
+  # Calculate the average of an array of numbers
+  #
+  # Examples
+  #
+  #   [].average #=> nil
+  #   [1, 2, 3].average #=> 2
+  #   [3, 12, 57, 85, 15, 89, 33, 7, 22, 54].average #=> 37.7
+  #
+  def average
+    return nil if empty?
+    self.reduce(:+)/length.to_f
+  end
+end

data/lib/core/facets/array/before.rb

@@ -19,7 +19,7 @@ class Array
     self[(index(value).to_i - 1) % length]
   end
 
-  # Returns the value after the given value. The value before the last
+  # Returns the value next to the given value. The value next to the last
   # is the first. Returns nil if the given value is not in the array.
   #
   # Examples

data/lib/core/facets/array/collapse.rb

@@ -10,5 +10,9 @@ class Array
     flatten.compact
   end
 
+  def collapse!
+    flatten!.compact!
+  end
+
 end
 

data/lib/core/facets/array/delete_first.rb

@@ -0,0 +1,21 @@
+class Array
+  # Deletes first item from +self+ that is equal to +obj+.
+  #
+  # Returns the deleted item, or +nil+ if no matching item is found.
+  #
+  # If the optional code block is given, the result of the block is returned if
+  # the item is not found.
+  #
+  #    a = [ "a", "b", "b", "b", "c" ]
+  #    a.delete_first("b")                   #=> "b"
+  #    a                               #=> ["a", "c"]
+  #    a.delete("z")                   #=> nil
+  #    a.delete("z") {"not found"}     #=> "not found"
+  def delete_first(el)
+    i = index(el)
+    if i
+      delete_at(i)
+    end
+  end
+end
+

data/lib/core/facets/array/delete_values_at.rb

@@ -0,0 +1 @@
+require 'facets/array/delete_values'

data/lib/core/facets/array/divide.rb

@@ -5,10 +5,17 @@ class Array
   #   ['a1','b1','a2','b2'].divide(/^a/)
   #   #=> [['a1','b1'],['a2','b2']]
   #
+  #   ['a1','b1','a2','b2'].divide(/^b/)
+  #   #=> [['a1',['b1','a2'],[]'b2']]
+  #
+  #   ['a1','b1','a2','b2'].divide(/^c/)
+  #   #=> [['a1','b1','a2','b2']]
+  #
   # CREDIT: Trans
 
   def divide(pattern)
     memo = []
+    memo.push [] unless pattern === first
     each do |obj|
       memo.push [] if pattern === obj
       memo.last << obj

data/lib/core/facets/array/duplicates.rb

@@ -8,6 +8,8 @@ class Array
   #
   #   [1,1,2,3].duplicates #=> [1]
   #
+  #   [1,1,2,3,2,4,5,4,2].duplicates(3) #=> [2]
+  #
   # CREDIT: Rebort Dober (current implementation)
   # CREDIT: Thibaut Barrère
 
@@ -19,4 +21,17 @@ class Array
     h.delete_if{|_,v| v < min}.keys
   end
 
+  # In-place version of #duplicates. Replaces the array with
+  # only its duplicate elements.
+  #
+  # Examples:
+  #
+  #   a = [1,1,2,3,2]
+  #   a.duplicates!  #=> [1,2]
+  #   a              #=> [1,2]
+  #
+  def duplicates!(min=2)
+    replace(duplicates(min))
+  end
+
 end

data/lib/core/facets/array/each_pair.rb

@@ -4,10 +4,7 @@ class Array
   # method is to provide polymorphism with Hash.
   #
   def each_pair #:yield:
-    i = -1
-    each_value do |x|
-      yield(i+=1, x)
-    end
+    each_with_index {|e, i| yield(i,e) }
   end
 
 end

data/lib/core/facets/array/first.rb

@@ -0,0 +1 @@
+require 'facets/array/indexable'

data/lib/core/facets/array/from.rb

@@ -1,32 +1,27 @@
 class Array
 
-  # Returns last _n_ elements.
+  # Returns elements from `index` until the end.
   #
-  #   %w{W o r l d}.from(3)  #=> %w{l d}
+  #   %w{W o r l d}.from(3)  #=> ["l", "d"]
+  #   %w{W o r l d}.from(9)  #=> []
   #
-  def from(i)
-    return self if i >= size
-    self[i, size - i]
+  def from(index)
+    return [] if index >= size
+    self[index..-1]
   end unless method_defined?(:from)
 
   # Fetch values from a start index thru an end index.
   #
-  #   [1,2,3,4,5].thru(0,2)  #=> [1,2,3]
-  #   [1,2,3,4,5].thru(2,4)  #=> [3,4,5]
-  #
   #   [1,2,3,4,5].thru(2)  #=> [1,2,3]
   #   [1,2,3,4,5].thru(4)  #=> [1,2,3,4,5]
   #
+  #   [1,2,3,4,5].thru(0,2)  #=> [1,2,3]
+  #   [1,2,3,4,5].thru(2,4)  #=> [3,4,5]
+  #
   def thru(from, to=nil)
     from, to = 0, from unless to
-    to = size - 1 if to >= size
-    a = []
-    i = from
-    while i <= to
-      a << self[i]
-      i += 1
-    end
-    a
+    return [] if from >= size
+    self[from..to]
   end unless method_defined?(:thru)
 
 end

data/lib/core/facets/array/indexes.rb

@@ -0,0 +1,113 @@
+class Array
+  # Returns an array of _indexes_ of all objects in receiver such that the object is == to obj.
+  #
+  # If a block is given instead of an argument, returns the _indexes_ of all objects for which the
+  # block returns true.
+  #
+  # If neither a block nor argument is given, an Enumerator for _all_ indexes (each_index) is returned.
+  #
+  # Returns [] if no match is found.
+  #
+  #  a = [ "a", "b", "c" ]
+  #  a.indexes("b").to_a              #=> [1]
+  #  a.indexes("z").to_a              #=> []
+  #  a.indexes { |x| x == "b" }.to_a  #=> [1]
+  #
+  # Like Array#index/rindex and Enumerable#find_index but returns _all_ indexes instead of just the
+  # first/last.
+  #
+  # See also: proposal to add Array#indexes to Ruby language: https://bugs.ruby-lang.org/issues/6596
+  #
+  # @author Tyler Rick
+  def indexes(*args)
+    case args.length
+    when 0
+      if block_given?
+        each_index.select {|i| yield(self[i]) }
+      else
+        each_index
+      end
+    when 1
+      other = args.first
+      each_index.select {|i| self[i] == other }
+    else
+      raise ArgumentError, "wrong number of arguments (given #{args.length}, expected 0..1)"
+    end
+  end
+  alias_method :index_all, :indexes
+end
+
+module Enumerable
+  # Returns an enumerator of _indexes_ of all objects in receiver such that the object is == to obj.
+  #
+  # If a block is given instead of an argument, returns the _indexes_ of all objects for which the
+  # block returns true.
+  #
+  # If neither a block nor argument is given, an Enumerator for _all_ indexes is returned.
+  #
+  # Returns [] if no match is found.
+  #
+  #  a = ("a".."c")
+  #  a.indexes("b").to_a              #=> [1]
+  #  a.indexes("z").to_a              #=> []
+  #  a.indexes { |x| x == "b" }.to_a  #=> [1]
+  #
+  # Like Array#index/rindex and Enumerable#find_index but returns _all_ indexes instead of just the
+  # first/last.
+  #
+  # See also: proposal to add Array#indexes to Ruby language: https://bugs.ruby-lang.org/issues/6596
+  #
+  # @author Tyler Rick
+  #
+  def indexes(*args)
+    # Enumerable doesn't have each_index like Array has, so this uses each_with_index instead.
+    case args.length
+    when 0
+      if block_given?
+        each_with_index.select {|el, i| yield(el)     }.map {|el, i| i }
+      else
+        each_with_index.                                map {|el, i| i }.to_enum
+      end
+    when 1
+      other = args.first
+      each_with_index.  select {|el, i| el == other   }.map {|el, i| i }
+    else
+      raise ArgumentError, "wrong number of arguments (given #{args.length}, expected 0..1)"
+    end
+  end
+  alias_method :index_all, :indexes
+end
+
+class Enumerator::Lazy
+  # Returns an enumerator of _indexes_ of all object in receiver such that the object is == to obj.
+  #
+  # If a block is given instead of an argument, returns the _indexes_ of all objects for which the
+  # block returns true.
+  #
+  # If neither a block nor argument is given, an Enumerator for _all_ indexes is returned.
+  #
+  #   enum = (42 .. Float::INFINITY).lazy.indexes
+  #   #=> #<Enumerator::Lazy: ...>
+  #   enum.next #=> 0
+  #   enum.next #=> 1
+  #   enum.first(5)  #=> [0, 1, 2, 3, 4]
+  #
+  # @author Tyler Rick
+  #
+  def indexes(*args)
+    case args.length
+    when 0
+      if block_given?
+        each_with_index.lazy.select {|el, i| yield(el)   }.map {|el, i| i }
+      else
+        each_with_index.lazy.                              map {|el, i| i }.to_enum
+      end
+    when 1
+      other = args.first
+      each_with_index.lazy.  select {|el, i| el == other }.map {|el, i| i }
+    else
+      raise ArgumentError, "wrong number of arguments (given #{args.length}, expected 0..1)"
+    end
+  end
+  alias_method :index_all, :indexes
+end

data/lib/core/facets/array/last.rb

@@ -0,0 +1 @@
+require 'facets/array/indexable'

data/lib/core/facets/array/mode.rb

@@ -1,8 +1,8 @@
 class Array
 
-  # In Statistics mode is the value that occurs most frequently
+  # In Statistics. mode is the value that occurs most frequently
   # in a given set of data. This method returns an array in case
-  # their is a tie.
+  # there is a tie.
   #
   #   [:a, :b, :c, :b, :d].mode  #=> [:b]
   #   [:a, :b, :c, :b, :a].mode  #=> [:a, :b]

data/lib/core/facets/array/nonuniq.rb

@@ -1,3 +1,5 @@
+require 'facets/array/duplicates'
+
 class Array
 
   # Returns a list of non-unique elements.
@@ -9,19 +11,15 @@ class Array
   # CREDIT: Martin DeMello
 
   def nonuniq
-    h1 = {}
-    h2 = {}
-    each {|i|
-      h2[i] = true if h1[i]
-      h1[i] = true
-    }
-    h2.keys
+    warn "Array#nonuniq is deprecated. Use Array#duplicates instead.", uplevel: 1
+    duplicates
   end
 
   # Same as `#nonuniq` but acts in place.
 
   def nonuniq!
-    self.replace(self.nonuniq)
+    warn "Array#nonuniq! is deprecated. Use Array#duplicates instead.", uplevel: 1
+    self.replace(duplicates)
   end
 
 end

data/lib/core/facets/array/occurrence.rb

@@ -1,15 +1,20 @@
 class Array
 
-  # Create a hart of counts of duplicate elements.
+  # Create a hash of each uniq element of the array
+  # and how many time each appears.
   #
   # Examples
   #
   #   [:a,:a,:b,:c,:c,:c].occurrence
-  #   #=> { :a => 2, :b => 1, :c => 3 } 
+  #   #=> { :a => 2, :b => 1, :c => 3 }
   #
-  #   [2,2,3,4,4,4].occurence{|i| i % 2} 
+  #   [2,2,3,4,4,4].occurrence{|i| i % 2}
   #   #=> { 0 => 5, 1 => 1 }
   #
+  # Without a block, this is equivalent to Ruby's #tally.
+  # With a block, the block transforms the key before counting,
+  # which #tally does not support.
+  #
   def occurrence
     h = Hash.new(0)
     if block_given?
@@ -25,4 +30,3 @@ class Array
   end
 
 end
-

data/lib/core/facets/array/probability.rb

@@ -1,7 +1,7 @@
 class Array
 
   # Generates a hash mapping each unique element in the array to the
-  # relative frequency, i.e. the probablity, of it appearence.
+  # relative frequency, i.e. the probability, of it appearance.
   #
   #   [:a, :b, :c, :c].probability  #=> {:a=> 0.25, :b=>0.25, :c=>0.5}
   #

data/lib/core/facets/array/recursively.rb

@@ -6,11 +6,11 @@ class Array
   # Apply a method to array, and recursively apply that method
   # to each sub-array or given +types+.
   #
-  # By default the sub-types are passed thru uneffected. Passing
+  # By default the sub-types are passed through unaffected. Passing
   # a block to #recursively can be used to change this.
   #
   # types - List of class types to recurse. [Array<Class>]
-  # block - Optional filter procedure to apply on each recursion. 
+  # block - Optional filter procedure to apply on each recursion.
   #
   # Examples
   #

data/lib/core/facets/array/remove.rb

@@ -0,0 +1,39 @@
+class Array
+  # Returns a new array that is a copy of the original array, removing the first occurrence of any
+  # item that also appears in +other_ary+. The order is preserved from the original array.
+  #
+  # If there are multiple occurrences of an item in +other_ary+, this removes that many occurrences
+  # from self.
+  #
+  # This is similar to `Array#-` and `Array#difference`, except that instead of removing _all_
+  # matches, it only removes as many occurrences as there are in the +other_ary+:
+  #
+  #    > [1, 1, 2].remove [1]
+  #   => [1, 2]
+  #
+  #    > [1, 1, 2].remove [1, 1, 1]
+  #   => [2]
+  #
+  #    > [1, 1, 2] - [1]
+  #   => [2]
+  #
+  #    > [1, 1, 2].difference [1]
+  #   => [2]
+  #
+  def remove(other_ary)
+    dup.remove!(other_ary)
+  end
+
+  # For each element of `other_ary`, deletes the _first_ element from self that is equal to that element
+  # (using `delete_at`, not `delete`).
+  #
+  # This is the in-place version of remove.
+  #
+  def remove!(other_ary)
+    other_ary.each do |el|
+      i = index(el)
+      delete_at(i) if i
+    end
+    self
+  end
+end

data/lib/core/facets/array/span.rb

@@ -0,0 +1,29 @@
+class Array
+  # Public: Split an array in two using a predicate
+  #
+  # Yields each element of the array.
+  #
+  # Examples
+  #
+  #   %w(The quick brown fox).span { |word| word.length < 4 }
+  #   #=> [['The'], ['quick', 'brown', 'fox']]
+  #
+  #   [1, 1, 2, 3, 5, 8, 13, 21, 34].span(&:odd?)
+  #   #=> [[1, 1], [2, 3, 5, 8, 13, 21, 34]]
+  #
+  # Returns a 2-tuple of arrays, the first element being the longest prefix for
+  # which the block evaluates to true, the second element being the rest of the
+  # array.
+  #
+  # TODO: This is based on Haskell's `span`, but the name is not intuitive
+  # for Ruby. Consider a more descriptive name (e.g. `split_while`).
+  # Also consider adding the inverse (Haskell's `break`), which splits
+  # where the predicate first becomes true.
+  def span
+    # This implementation is another way of saying
+    # `[take_while(&:block), drop_while(&:block)]`
+    index = find_index { |e| !yield e }
+    return [dup, []] if index.nil?
+    [take(index), drop(index)]
+  end
+end

data/lib/core/facets/array/splice.rb

@@ -2,7 +2,7 @@ require 'facets/array/store'
 
 class Array
 
-  # Splice acts a combination of #slice! and #store.
+  # Splice acts as a combination of #slice! and #store.
   # If two arguments are given it calls #store.
   # If a single argument is given it calls slice!.
   #

data/lib/core/facets/array/split_at.rb

@@ -0,0 +1,25 @@
+class Array
+
+  # Split on matching pattern. Breaks the array into [before, middle, after]
+  # segments. Uses Array#index to find the middle element.
+  #
+  # Examples
+  #
+  #   ['a1','a2','b1','a3','b2','a4'].split('b1')
+  #   #=> [['a1','a2'],b1,['a3','b2','a4']]
+  #
+  #   ['a1','a2','b1','a3','b2','a4'].split('foo')
+  #   #=> [[],nil,[]]
+  #
+  # Returns list of split-up arrays. [Tuple<Array,Object,Array>]
+
+  def split_at(*args, &block)
+    if middle = index(*args, &block)
+      [self[0...middle], self[middle], self[middle+1..-1]]
+    else
+      [[], nil, []]
+    end
+  end
+
+end
+

data/lib/core/facets/array/standard_deviation.rb

@@ -0,0 +1,28 @@
+require 'facets/array/variance'
+
+class Array
+
+  # Calculate the standard_deviation of an array of numbers
+  #
+  # Examples
+  #
+  #   [].standard_deviation #=> nil
+  #   [1, 2, 3].standard_deviation #=> 0.816496580927726
+  #   [96, 35, 72, 30, 75, 33, 68, 13, 49, 71].standard_deviation #=> 24.69331893448104
+  #   [36, -67, -17, 85, -46, -64, -23, -13, 89, -47].standard_deviation #=> 54.67183918618432
+  #   [60.7829, 31.2622, 20.626, 78.8907, 61.5328].standard_deviation #=> 21.428815505053002
+  #
+  def stddev
+    return nil if empty?
+    Math.sqrt(variance)
+  end
+
+  alias sd stddev
+
+  def standard_deviation
+    warn "Array#standard_deviation is deprecated. Use Array#stddev or Array#sd instead.", uplevel: 1
+    stddev
+  end
+end
+
+

data/lib/core/facets/array/step.rb

@@ -2,30 +2,28 @@ class Array
 
   # Iterate over every nth element of an array.
   #
+  # An optional offset can be given to start from a
+  # specific index (default is 0).
+  #
+  #   [:a, :b, :c, :d, :e, :f].step(2).to_a    #=> [:a, :c, :e]
+  #   [:a, :b, :c, :d, :e, :f].step(2, 1).to_a  #=> [:b, :d, :f]
+  #   [:a, :b, :c, :d, :e, :f].step(3).to_a    #=> [:a, :d]
+  #
   #   r = []
   #   [:a, :b, :c, :d].step(2) { |x| r << x }
-  #   r   #=> [:b, :d]
-  #   
-  # Without a block it returns an Enumerator.
-  #
-  #   [:a, :b, :c, :d].step(1).to_a   #=> [:a, :b, :c, :d]
-  #   [:a, :b, :c, :d].step(2).to_a   #=> [:b, :d]
-  #   [:a, :b, :c, :d].step(3).to_a   #=> [:c]
-  #   [:a, :b, :c, :d].step(5).to_a   #=> []
+  #   r   #=> [:a, :c]
   #
   # CREDIT: Ryan Duryea
 
-  def step(n) #:yield:
+  def step(n, offset=0) #:yield:
     if block_given?
-      ((n - 1)...size).step(n).each do |i|
+      (offset...size).step(n).each do |i|
         yield(fetch(i))
       end
     else
-      Enumerator.new(size / n) do |y|
-        ((n - 1)...self.size).step(n).each { |i| y << fetch(i) }  
+      Enumerator.new do |y|
+        (offset...size).step(n).each { |i| y << fetch(i) }
       end
     end
   end
 end
-
-

data/lib/core/facets/array/to_ranges.rb

@@ -0,0 +1,48 @@
+class Array
+
+  # Produces an array of ranges from the values in the array.
+  # Contiguous values and overlapping ranges are merged.
+  # Single values are returned as single-element ranges (e.g. 1..1).
+  #
+  # Examples
+  #
+  #     [1,2,3,6,7,8].to_ranges  #=> [1..3, 6..8]
+  #
+  #     [3,4,5,1,6,9,8].to_ranges  #=> [1..1, 3..6, 8..9]
+  #
+  #     [10..15, 16..20, 21, 22].to_ranges  #=> [10..22]
+  #
+  # Assumes inclusive ranges (i.e. 1..4) and range.first <= range.last.
+  #
+  # Works with integers, dates and strings. However, all the objects
+  # in the array must be of the same class.
+  #
+  # CREDIT: monocle, Ryan Duryea
+
+  def to_ranges
+    array = compact.uniq.sort_by { |e| Range === e ? e.first : e }
+    result = array.inject([]) do |c, value|
+      unless c.empty?
+        last = c.last
+        last_value    = (Range === last  ? last.last   : last)
+        current_value = (Range === value ? value.first : value)
+        if (last_value.succ <=> current_value) == -1
+          c << value
+        else
+          first  = (Range === last ? last.first : last)
+          second = [Range === last ? last.last : last, Range === value ? value.last : value].max
+          c[-1] = [first..second]
+          c.flatten!
+        end
+      else
+        c << value
+      end
+    end
+    # Ensure all elements are ranges
+    result.map { |e| Range === e ? e : e..e }
+  end
+
+  alias arrange to_ranges
+  alias rangify to_ranges
+
+end

data/lib/core/facets/array/uniq_by.rb

@@ -9,11 +9,15 @@ class Array
   #   a.uniq_by!{ |i| i*i }
   #   a #=> [-5, -4, -3, -2, -1, 0]
   #
+  #   a = (-5..5).to_a.reverse
+  #   a.uniq_by!{ |i| i*i }
+  #   a #=> [5, 4, 3, 2, 1, 0]
+  #
   # Returns [Array] of unique elements.
   #
-  def uniq_by! #:yield:
-    h = {}
-    replace( inject([]){|a,x| h[yield(x)] ||= a << x} )
+  def uniq_by!(&block) #:yield:
+    warn "Array#uniq_by! is deprecated. Use Array#uniq!(&block) instead.", uplevel: 1
+    uniq!(&block)
   end
 
 end