facets 2.9.1 → 2.9.2

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

@@ -0,0 +1,12 @@
+class Array
+
+  # Simplify an array by flattening it then compacting it.
+  #
+  #   [1,[2,nil,[3]],nil,4].collapse  #=> [1,2,3,4]
+  #
+  def collapse
+    flatten.compact
+  end
+
+end
+

data/src/core/facets/array/collisions.rb

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

data/src/core/facets/array/combination.rb

@@ -0,0 +1,43 @@
+class Array
+
+  unless method_defined?(:combination) # 1.8.7+
+
+    require 'facets/enumerator'
+
+    # Yields the block to each unique combination of _n_ elements.
+    #
+    #   a = %w|a b c d|
+    #   a.combination(3)
+    #
+    # produces
+    #
+    #   [["a", "b", "c"],
+    #    ["a", "b", "d"],
+    #    ["a", "c", "d"],
+    #    ["b", "c", "d"]]
+    #
+    # CREDIT: Florian Gross
+
+    def combination(k=2)
+      if block_given?
+        s = to_a
+        n = s.size
+        return unless (1..n) === k
+        idx = (0...k).to_a
+        loop do
+          yield s.values_at(*idx)
+          i = k - 1
+          i -= 1 while idx[i] == n - k + i
+          break if i < 0
+          idx[i] += 1
+          (i + 1 ... k).each {|j| idx[j] = idx[i] + j - i}
+        end
+      else
+        to_enum(:combination, k)
+      end
+    end
+
+  end
+
+end
+

data/src/core/facets/array/commonality.rb

@@ -0,0 +1,37 @@
+class Array
+
+  # Returns all items that are equal in terms of the supplied block.
+  # If no block is given objects are considered to be equal if they
+  # return the same value for Object#hash and if obj1 == obj2.
+  #
+  #   [1, 2, 2, 3, 4, 4].commonality  #=> { 2 => [2, 2], 4 => [4, 4] }
+  #
+  #   ["foo", "bar", "a"].commonality { |str| str.length }
+  #   #=> { 3 => ["foo", "bar"] }
+  #
+  # This can be useful, for instance, in determining all persons that share
+  # their last name with another person ...
+  #
+  #   persons.collisions { |person| person.last_name }
+  #
+  # CREDIT: Florian Gross
+
+  def commonality(&block)
+    had_no_block = !block
+    block ||= lambda { |item| item }
+    result = Hash.new { |hash, key| hash[key] = Array.new }
+    each do |item|
+      key = block.call(item)
+      result[key] << item
+    end
+    result.reject! do |key, values|
+      values.size <= 1
+    end
+    # -- return had_no_block ? result.values.flatten : result
+    return result
+  end
+
+  alias_method :collisions, :commonality
+
+end
+

data/src/core/facets/array/conjoin.rb

@@ -0,0 +1,89 @@
+class Array
+
+  # This is more advanced form of #join. It allows for fine control
+  # of separators.
+  #
+  # NOTE: The old version used to default its separator to ", " and
+  # default the terminating separator to " and ". This is no longer
+  # the case. You must specifically provide these parameters.
+  #
+  # If no paramters are given, it acts like #join but will a space
+  # separator.
+  #
+  #   [1,2,3].conjoin
+  #   #=> "1 2 3"
+  #
+  # Use comma+space and 'and' on tail.
+  #
+  #   [1,2,3].conjoin(', ', ' and ')
+  #   #=> "1, 2 and 3"
+  #
+  # Use comma+space and 'or' on tail using :last option.
+  #
+  #   [1,2,3].conjoin(', ', :last => ' or ')
+  #   #=> "1, 2 or 3"
+  #
+  # Use semicolon+space and ampersand on tail using index.
+  #
+  #   [1,2,3].conjoin('; ', -1 => ' & ')
+  #   #=> "1; 2 & 3"
+  #
+  # Can take a block to determine separator.
+  #
+  #   [1,2,3,4].conjoin{ |i, a, b| i % 2 == 0 ? '.' : '-' }
+  #   #=> "1.2-3.4"
+  #
+  # This makes very esoteric transformation possible.
+  #
+  #   [1,1,2,2].conjoin{ |i, a, b| a == b ? '=' : ' != ' }
+  #   #=> "1=1 != 2=2"
+  #
+  #   [1,2,3,4].conjoin{ |i, x, y| "<#{i} #{x} #{y}>" }
+  #   #=> "1<0 1 2>2<1 2 3>3<2 3 4>4"
+  #
+  # There are also spacing options. Providing the :space option
+  # pads the separators.
+  #
+  #   [1,2,3].conjoin(',', '&', :space=>2)
+  #   #=> "1  ,  2  &  3"
+  #
+  # And the :spacer option can set an alternate spacing string.
+  #
+  #   [1,2,3].conjoin('|', '>', :space=>2, :spacer=>'-')
+  #   #=> "1--|--2-->--3"
+  #
+  # CREDIT: Trans
+
+  def conjoin(*args, &block)
+    return first.to_s if size < 2
+
+    options = (Hash===args.last) ? args.pop : {}
+
+    spacing = options.delete(:space)  || 0
+    spacer  = options.delete(:spacer) || " "
+    space   = spacer * spacing.to_i
+
+    sep = []
+
+    if block_given?
+      (size - 1).times do |i|
+        sep << space + yield(i, *slice(i,2)) + space
+      end
+    else
+      separator   = args.shift || " "
+      options[-1] = args.shift if args.first
+
+      options[0]  = options.delete(:first) if options.key?(:first)
+      options[-1] = options.delete(:last)  if options.key?(:last)
+
+      separator = space + separator + space
+
+      sep = [separator] * (size - 1)
+
+      options.each{|i, s| sep[i] = space + s + space}
+    end
+    zip(sep).join
+  end
+
+end
+

data/src/core/facets/array/contains.rb

@@ -0,0 +1,7 @@
+class Array
+
+  # Alias for #include?.
+  alias_method :contains?, :include?
+
+end
+

data/src/core/facets/array/delete.rb

@@ -0,0 +1,4 @@
+# Here for backward compatability. To be deprecated.
+require 'facets/array/delete_unless'
+require 'facets/array/delete_values'
+

data/src/core/facets/array/delete_unless.rb

@@ -0,0 +1,15 @@
+class Array
+
+  # Inverse of #delete_if.
+  #
+  #   [1,2,3].delete_unless{ |x| x < 2 }
+  #   #=> [1]
+  #
+  # CREDIT: Daniel Schierbeck
+
+  def delete_unless(&block)
+    delete_if { |element| not block.call(element) }
+  end
+
+end
+

data/src/core/facets/array/delete_values.rb

@@ -0,0 +1,50 @@
+class Array
+
+  # Delete multiple values from array.
+  #
+  #   a = [1,2,3,4]
+  #   a.delete_values(1,2)   #=> [1,2]
+  #   a                      #=> [3,4]
+  #
+  # CREDIT: Trans
+
+  def delete_values(*values)
+    d = []
+    values.each{ |v| d << delete(v) }
+    d
+  end
+
+  # Delete multiple values from array given
+  # indexes or index range.
+  #
+  #   a = [1,2,3,4]
+  #   a.delete_values_at(1,2)   #=> [2,3]
+  #   a                         #=> [1,4]
+  #   a = [1,2,3,4]
+  #   a.delete_values_at(0..2)  #=> [1,2,3]
+  #   a                         #=> [4]
+  #
+  # NOTE: It would be nice to see #delete_at incorporate this
+  # funcitonaility.
+  #
+  # CREDIT: Trans
+
+  def delete_values_at(*selectors)
+    idx = []
+    selectors.each{ |i|
+      case i
+      when Range
+        idx.concat( i.to_a )
+      else
+        idx << i.to_i
+      end
+    }
+    idx.uniq!
+    dvals = values_at(*idx)
+    idx = (0...size).to_a - idx
+    self.replace( values_at(*idx) )
+    return dvals
+  end
+
+end
+

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

@@ -0,0 +1,20 @@
+class Array
+
+  # Divide on matching pattern.
+  #
+  #   ['a1','b1','a2','b2'].divide(/^a/)
+  #   #=> [['a1','b1'],['a2','b2']]
+  #
+  # CREDIT: Trans
+
+  def divide(pattern)
+    memo = []
+    each do |obj|
+      memo.push [] if pattern === obj
+      memo.last << obj
+    end
+    memo
+  end
+
+end
+

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

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

data/src/core/facets/array/entropy.rb

@@ -0,0 +1,39 @@
+require 'facets/array/probability'
+
+class Array
+
+  # Shannon's entropy for an array - returns the average
+  # bits per symbol required to encode the array.
+  # Lower values mean less "entropy" - i.e. less unique
+  # information in the array.
+  #
+  #   e = %w{ a b c d e e e }.entropy
+  #
+  #   ("%.3f" % e)  #=> "2.128"
+  #
+  # CREDIT: Derek
+
+  def entropy
+    arr = self
+    probHash = arr.probability
+    # -- h is the Shannon entropy of the array
+    h = -1.to_f * probHash.keys.inject(0.to_f) do |sum, i|
+      sum + (probHash[i] * (Math.log(probHash[i])/Math.log(2.to_f)))
+    end
+    h
+  end
+
+  # Returns the maximum possible Shannon entropy of the array
+  # with given size assuming that it is an "order-0" source
+  # (each element is selected independently of the next).
+  #
+  # CREDIT: Derek
+
+  def ideal_entropy
+    arr = self
+    unitProb = 1.0.to_f / arr.size.to_f
+    (-1.to_f * arr.size.to_f * unitProb * Math.log(unitProb)/Math.log(2.to_f))
+  end
+
+end
+

data/src/core/facets/array/extract_options.rb

@@ -0,0 +1,31 @@
+class Hash
+  # By default, only instances of Hash itself are extractable.
+  # Subclasses of Hash may implement this method and return
+  # true to declare themselves as extractable. If a Hash
+  # is extractable, Array#extract_options! pops it from
+  # the Array when it is the last element of the Array.
+  def extractable_options?
+    instance_of?(Hash)
+  end
+end
+
+class Array
+  # Extracts options from a set of arguments. Removes and returns the last
+  # element in the array if it's a hash, otherwise returns a blank hash.
+  #
+  #   def options(*args)
+  #     args.extract_options!
+  #   end
+  #
+  #   options(1, 2)           # => {}
+  #   options(1, 2, :a => :b) # => {:a=>:b}
+  #
+  def extract_options!
+    if Hash === last && last.extractable_options?
+      pop
+    else
+      {}
+    end
+  end
+end
+

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

@@ -0,0 +1,33 @@
+class Array
+
+  # Returns last _n_ elements.
+  #
+  #   %w{W o r l d}.from(3)  #=> %w{l d}
+  #
+  def from(i)
+    return self if i >= size
+    self[i, size - i]
+  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]
+  #
+  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
+  end unless method_defined?(:thru)
+
+end
+

data/src/core/facets/array/index.rb

@@ -0,0 +1,23 @@
+class Array
+
+  if RUBY_VERSION < '1.8.7'
+
+    alias_method :_facets_index, :index
+
+    # Allows #index to accept a block.
+    #
+    #   ['a', 'b', 'c'].index{ |x| x.upcase == 'C' } #=> 2
+    #
+    # IMPORTANT: This is one of the few core overrides in Facets.
+    def index(obj=nil, &block)
+      if block_given?
+        _facets_index(find(&block))
+      else
+        _facets_index(obj)
+      end
+    end
+
+  end
+
+end
+

data/src/core/facets/array/indexable.rb

@@ -0,0 +1,31 @@
+require 'facets/indexable'
+require 'facets/array/splice'
+
+class Array
+
+  include Indexable
+
+  # Alias for shift, which removes and returns
+  # the first element in an array.
+  #
+  #   a = ["a","y","z"]
+  #   a.first!      #=> "a"
+  #   a             #=> ["y","z"]
+  #
+  # CREDIT: Trans
+
+  alias_method :first!, :shift
+
+  # Alias for pop, which removes and returns
+  # the last element in an array.
+  #
+  #   a = [1,2,3]
+  #   a.last!       #=> 3
+  #   a             #=> [1,2]
+  #
+  # CREDIT: Trans
+
+  alias_method :last!, :pop
+
+end
+