facets 3.1.0 → 3.2.1

data/README.md

@@ -1,8 +1,7 @@
 # Ruby Facets
 
-[![Gem Version](https://badge.fury.io/rb/facets.png)](http://badge.fury.io/rb/facets)
-[![Build Status](https://secure.travis-ci.org/rubyworks/facets.png)](http://travis-ci.org/rubyworks/facets)    
-[![Flattr Me](http://api.flattr.com/button/flattr-badge-large.png)](http://flattr.com/thing/324911/Rubyworks-Ruby-Development-Fund)
+[![Gem Version](https://badge.fury.io/rb/facets.svg)](https://rubygems.org/gems/facets)
+[![CI](https://github.com/rubyworks/facets/actions/workflows/ci.yml/badge.svg)](https://github.com/rubyworks/facets/actions/workflows/ci.yml)
 
 
 *"ALL YOUR BASE ARE BELONG TO RUBY"*
@@ -10,7 +9,7 @@
 
 ## Introduction
 
-Ruby Facets is the premiere collection of general purpose method
+Ruby Facets is the premier collection of general purpose method
 extensions and standard additions for the Ruby programming language.
 
 Facets houses the largest single collection of methods available for
@@ -28,11 +27,10 @@ to a wide variety of usecases.
 
 ## Resources
 
-* Homepage: http://rubyworks.github.com/facets
-* Report Bugs: http://github.com/rubyworks/facets/issues
-* Mailing List: http://groups.google.com/group/facets-universal/topics
-* Wiki Pages: http://wiki.github.com/rubyworks/facets
-* Source Code: http://github.com/rubyworks/facets
+* Homepage: https://rubyworks.github.io/facets
+* Report Bugs: https://github.com/rubyworks/facets/issues
+* Wiki Pages: https://github.com/rubyworks/facets/wiki
+* Source Code: https://github.com/rubyworks/facets
 
 
 ## Documentation
@@ -45,7 +43,7 @@ it is important to remain aware of the source location of particular
 methods.
 
 For better organized online documentation, generated to separate core
-extensions from standard libraries, see the [Learn Facets](http://rubyworks.github.com/facets/learn.html) page on the website for links to available documentation.
+extensions from standard libraries, see the [Learn Facets](https://rubyworks.github.io/facets/learn.html) page on the website for links to available documentation.
 
 
 ## Installation
@@ -64,16 +62,9 @@ The easiest way to install is via RubyGems.
 
     $ gem install facets
 
-### Setup.rb
+### Requirements
 
-Facets can be installed the old-fashioned way using [Setup.rb](http://rubyworks.github.com/setup).
-Download and unpack the .tar.gz package and run setup.rb, like so:
-
-    $ tar -xvzf facets-2.x.x.tar.gz
-    $ cd facets-2.x.x
-    $ sudo setup.rb
-
-Facets 2.8+ requires Ruby 1.8.7 or higher. Facets 3.0+ requires Ruby 2.0.0 or higher.
+Facets 3.2+ requires Ruby 3.1 or higher.
 
 
 ## Mission
@@ -197,21 +188,20 @@ This project thrives on contribution!
 
 If you have any extension methods, classes or modules that you think have
 very general applicability and would like to see them included in
-this project, don't hesitiate to submit. Also, if you have better versions
+this project, don't hesitate to submit. Also, if you have better versions
 of any thing already included or simply have a patch, they are more than
 welcome. We want Ruby Facets to be of the highest quality.
 
 
 ## Development
 
-Facets uses the [Lemon](http://rubyworks.github.com/lemon) testing framework
-to handle unit testing, while [QED](http://rubyworks.github.com/qed) specifications
-provide tested documentation.
+Facets uses the [Lemon](https://rubyworks.github.io/lemon) testing framework
+to handle unit testing, while [QED](https://rubyworks.github.io/qed) specifications
+provide tested documentation. Run the test suite with [Rake](https://ruby.github.io/rake/):
+
+    $ rake test
 
-Facets uses [Detroit](http://detroit.github.com) and [Rulebow](http://rubyworks.github.com/rulebow)
-build tools. Detroit is a life-cycle tool and Rulebow is continuous integrations tool. The build
-scripts (`Assembly` and `Rulebook` respectively), sometimes use other tools such as
-[Mast](http://rubyworks.github.com/mast) and [Indexer](http://rubyworks.github.com/indexer).
+Continuous integration runs on GitHub Actions (see `.github/workflows/ci.yml`).
 
 
 ## Authors
@@ -220,15 +210,18 @@ Much of this collection was written and/or inspired by a variety of great Ruby
 developers. Fortunately nearly all utilized works were copyrighted under the same
 open licenses, the Ruby License or the more liberal BSD and MIT licenses. In the
 one or two exceptions the copyright notice has been included with the source code.
-Any code file not specifically labeled othewise shall fall under the current Ruby
-License (which is BSD 2-clause).
+We have since received permission from the various authors to normalize the licensing
+to a single license. For this purpose we have chosen the BSD 2 Clause License.
+This is the license Ruby itself now uses, so it seemed the most appropriate choice.
+It is also almost identical to the MIT license. Any code file not specifically labeled
+otherwise shall fall under the this license (which is BSD 2-clause).
 
 In all cases, every effort has been made to give credit where credit is due.
 You will find these acknowledgments embedded in the source code. You can see
 them in "CREDIT:" and/or "@author" lines. 
-Also see the [Contibutors page](https://github.com/rubyworks/facets/wiki/Contributors)
+Also see the [Contributors page](https://github.com/rubyworks/facets/wiki/Contributors)
 on the Wiki for a list of all contributing Rubyists. If anyone is missing from
-the list, please let us know so we can correct right away. Thanks.
+the list, please let us know so we can correct. Thanks.
 
 This collection was put together by, and much of it written by [trans](https://github.com/trans).
 If need be, he can be reached via email at transfire at gmail.com.
@@ -239,22 +232,22 @@ If need be, he can be reached via email at transfire at gmail.com.
 The collection PER COLLECTION is licensed as follows:
 
     Ruby Facets
-    Copyright (c) 2004,2010 Rubyworks
+    Copyright (c) 2005 Rubyworks
 
-    Distributed under the terms of the Ruby license.
+    Distributed under the terms of the BSD-2 License (same as Ruby license).
 
-The Ruby license is a dual license that also provides for use of the GPL.
-Complete texts of both licenses accompany this document (see LICENSE).
+The BSD 2 Clause License is a simple open source license. The complete text of the
+license accompany this document (see the enclosed LICENSE file).
 
 Acknowledgments and Copyrights for particular snippets of borrowed code
-are given in their respective source. All licenses are either compatible
-with the Ruby license or the original author has given permission for
-inclusion of their code under such license.
+are given in their respective source. At this point, all licensing has been normalized
+for all included code. Original authors have given permission for inclusion of their
+code under such license, with appropriate credit citations.
 
 
-"ALL YOUR BASE ARE BELONG TO RUBY!"
+## "ALL YOUR BASE ARE BELONG TO RUBY!"
 
-Ruby Facets, Copyright (c)2005,2011 Rubyworks
+Ruby Facets, Copyright (c) 2005 Rubyworks
 
-Do you Ruby? (http://ruby-lang.org)
+Do you Ruby? (https://ruby-lang.org)
 

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

@@ -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/array.rb

@@ -43,7 +43,7 @@ require_relative 'array/split.rb'
 require_relative 'array/squeeze.rb'
 require_relative 'array/store.rb'
 require_relative 'array/thru.rb'
-require_relative 'array/to_h.rb'
+#require_relative 'array/to_h.rb'  # removed: now provided by Ruby
 require_relative 'array/traverse.rb'
 require_relative 'array/uniq_by.rb'
 

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.