facets 3.1.0 → 3.2.0

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

@@ -7,7 +7,6 @@ class Array
   #   [].average #=> nil
   #   [1, 2, 3].average #=> 2
   #   [3, 12, 57, 85, 15, 89, 33, 7, 22, 54].average #=> 37.7
-  #   [1,[2,nil,[3]],nil,4].collapse  #=> [1,2,3,4]
   #
   def average
     return nil if empty?

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/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/duplicates.rb

@@ -21,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/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/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

@@ -11,6 +11,10 @@ class Array
   #   [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?
@@ -26,4 +30,3 @@ class Array
   end
 
 end
-

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/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

@@ -12,12 +12,17 @@ class Array
   #   [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 standard_deviation
+  def stddev
     return nil if empty?
     Math.sqrt(variance)
   end
 
-  alias sd standard_deviation
+  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

@@ -15,9 +15,9 @@ class Array
   #
   # 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

data/lib/core/facets/binding/caller.rb

@@ -8,16 +8,22 @@ class Binding
     eval("caller(#{skip})")
   end
 
+  # Returns the call stack, same format as Kernel#caller_locations()
+  #
+  def caller_locations( skip=0 )
+    eval("caller_locations(#{skip})")
+  end
+
   # Return the line number on which the binding was created.
   #
   def __LINE__
-    Kernel.eval("__LINE__", self)
+    self.source_location[1]
   end
 
   # Returns file name in which the binding was created.
   #
   def __FILE__
-    Kernel.eval("__FILE__", self)
+    self.source_location[0]
   end
 
   # Return the directory of the file in which the binding was created.

data/lib/core/facets/binding/op_get.rb

@@ -1,25 +1,21 @@
 class Binding
 
-  # Returns the value of some variable.
+  # Returns the value of a local variable.
   #
   #   a = 2
-  #   binding["a"]  #=> 2
+  #   binding[:a]  #=> 2
   #
-  def []( x )
-    eval( x.to_s )
+  def [](name)
+    local_variable_get(name.to_sym)
   end
 
   # Set the value of a local variable.
   #
-  #   binding["a"] = 4
+  #   binding[:a] = 4
   #   a  #=> 4
   #
-  # @deprecated No longer wortks in Ruby 1.9+.
-  #
-  # @see Binding#with for an alternative.
-  def []=( l, v )
-    eval( "lambda {|v| #{l} = v}").call( v )
+  def []=(name, value)
+    local_variable_set(name.to_sym, value)
   end
 
 end
-

data/lib/core/facets/binding/self.rb

@@ -1,15 +1,9 @@
 class Binding
 
-  # This is already defined by Rubinius:
-  #   Kernel.eval('Rubinius::VariableScope.current.self', self)
-  unless method_defined?(:self)
-
-    # Returns self of the binding's context.
-    def self
-      eval('self')
-    end
-
+  # @deprecated Use Binding#receiver instead (built-in since Ruby 2.6).
+  def self
+    warn "Binding#self is deprecated. Use Binding#receiver instead.", uplevel: 1
+    receiver
   end
 
 end
-

data/lib/core/facets/boolean.rb

@@ -86,7 +86,7 @@ class String
   #
   # All other strings return false.
   #
-  # Here are some exmamples.
+  # Here are some examples.
   #
   #   "true".to_b   #=> true
   #   "yes".to_b    #=> true

data/lib/core/facets/class/descendants.rb

@@ -1,5 +1,3 @@
-require 'facets/class/subclasses'
-
 class Class
 
   # List all descedents of this class.

data/lib/core/facets/class.rb

@@ -3,7 +3,7 @@ require_relative 'class/descendants.rb'
 require_relative 'class/methodize.rb'
 require_relative 'class/pathize.rb'
 #require_relative 'class/preallocate.rb'  # uncommon
-#require_relative 'class/singleton.rb'    # uncommon
-require_relative 'class/subclasses.rb'
+#require_relative 'class/singleton.rb'    # removed, use Ruby's singleton_class
+#require_relative 'class/subclasses.rb'   # removed, use Ruby's subclasses
 require_relative 'class/to_proc.rb'
 

data/lib/core/facets/comparable/bound.rb

@@ -1 +1,13 @@
-require 'facets/comparable/clip'
+module Comparable
+
+  # Alias for Comparable#clamp. Reads more naturally in some contexts.
+  #
+  #   4.bound(2, 7)  #=> 4
+  #   9.bound(2, 7)  #=> 7
+  #   1.bound(2, 7)  #=> 2
+  #
+  def bound(lower, upper=nil)
+    upper ? clamp(lower, upper) : clamp(lower..)
+  end
+
+end

data/lib/core/facets/comparable/clip.rb

@@ -1,38 +1,9 @@
 module Comparable
 
-  # Returns self if above the given lower bound, or
-  # within the given lower and upper bounds,
-  # otherwise returns the the bound of which the
-  # value falls outside.
-  #
-  #   4.clip(3)    #=> 4
-  #   4.clip(5)    #=> 5
-  #   4.clip(2,7)  #=> 4
-  #   9.clip(2,7)  #=> 7
-  #   1.clip(2,7)  #=> 2
-  #
-  # CREDIT Florian Gross, Trans
-
+  # @deprecated Use Comparable#clamp instead (built-in since Ruby 2.4).
   def clip(lower, upper=nil)
-    return lower if self < lower
-    return self unless upper
-    return upper if self > upper
-    return self
+    warn "Comparable#clip is deprecated. Use Comparable#clamp instead.", uplevel: 1
+    upper ? clamp(lower, upper) : clamp(lower..)
   end
 
-  # Returns self if above the given lower bound, or
-  # within the given lower and upper bounds,
-  # otherwise returns the the bound of which the
-  # value falls outside.
-  #
-  #   4.bound(3)    #=> 4
-  #   4.bound(5)    #=> 5
-  #   4.bound(2,7)  #=> 4
-  #   9.bound(2,7)  #=> 7
-  #   1.bound(2,7)  #=> 2
-  #
-  # CREDIT: Florian Gross
-
-  alias_method :bound, :clip
-
 end

data/lib/core/facets/denumerable.rb

@@ -1,6 +1,3 @@
-require 'facets/enumerator'
-#require 'facets/enumerable/take'
-
 # Classes which include Denumerable will get versions of map,
 # select, and so on, which return a Denumerator, so that they
 # work horizontally without creating intermediate arrays.

data/lib/core/facets/dir/find.rb

@@ -0,0 +1,20 @@
+require 'find'
+
+class Dir
+
+  # Recursively traverse a directory, yielding each file and directory path.
+  # Supports Find.prune to skip subtrees.
+  #
+  #   Dir.find('.') do |path|
+  #     puts path
+  #   end
+  #
+  # Returns an enumerator if no block is given.
+  #
+  # This is a convenience wrapper around Ruby's Find.find.
+
+  def self.find(*paths, ignore_error: true, &block)
+    Find.find(*paths, ignore_error: ignore_error, &block)
+  end
+
+end