facets 2.9.3 → 3.0.0

data/lib/core/facets/enumerable/accumulate.rb

@@ -2,45 +2,47 @@ require 'facets/functor'
 
 module Enumerable
 
+  # TODO: Should Enumerable#accumuate be moved to a functor gem?"
+
   # Accumulate a set of a set. For example, in an ORM design
   # where `Group has_many User` we might have something
   # equivalent to the following.
   #
-  #   Group = Struct.new(:users)
-  #   User  = Struct.new(:name, :friends)
+  #     Group = Struct.new(:users)
+  #     User  = Struct.new(:name, :friends)
   #
-  #   user1 = User.new('John', [])
-  #   user2 = User.new('Jane', ['Jill'])
-  #   user3 = User.new('Joe' , ['Jack', 'Jim'])
+  #     user1 = User.new('John', [])
+  #     user2 = User.new('Jane', ['Jill'])
+  #     user3 = User.new('Joe' , ['Jack', 'Jim'])
   #
-  #   group1 = Group.new([user1, user2])
-  #   group2 = Group.new([user2, user3])
+  #     group1 = Group.new([user1, user2])
+  #     group2 = Group.new([user2, user3])
   #
-  #   groups = [group1, group2]
+  #     groups = [group1, group2]
   #
   # Now we can *accumulate* the users of all groups.
   #
-  #   groups.accumulate.users  #=> [user1, user2, user3]
+  #     groups.accumulate.users  #=> [user1, user2, user3]
   #
   # You may pass an argument to perform chains, e.g. the following
   # returns the names of users from all groups.
   #
-  #   groups.accumulate(2).users.name  #=> ['John','Jane','Joe']
+  #     groups.accumulate(2).users.name  #=> ['John','Jane','Joe']
   #
   # Or we can gather all the friends of all users in groups.
   #
-  #   groups.accumulate(2).users.friends  #=> ['Jill','Jack','Jim']
+  #     groups.accumulate(2).users.friends  #=> ['Jill','Jack','Jim']
   # 
   # This is more convenient then the equivalent.
   #
-  #   groups.accumulate.users.accumulate.friends  #=> ['Jill','Jack','Jim']
+  #     groups.accumulate.users.accumulate.friends  #=> ['Jill','Jack','Jim']
   #
-  # CREDIT: George Moshchovitis, Daniel Emirikol
+  # CREDIT: George Moshchovitis, Daniel Emirikol, Robert Dober
 
   def accumulate(iterations=1)
     return self if iterations == 0
+
     Functor.new do |op, *args|
-      #result = inject([]) { |a, x| a << x.send(op, *args) }.flatten.uniq
       result = []
       each { |x| result << x.send(op, *args) }
       result.flatten.uniq.accumulate(iterations - 1)
@@ -49,12 +51,12 @@ module Enumerable
 
   # Same as #accumulate, but does not apply #uniq to final result.
   #
-  #   groups.accumulate_all(2).users.friends  #=> ['Jill', 'Jill','Jack','Jim']
+  #     groups.accumulate_all(2).users.friends  #=> ['Jill', 'Jill','Jack','Jim']
   #
   def accumulate_all(iterations=1)
     return self if iterations == 0
+
     Functor.new do |op, *args|
-      #result = inject([]) { |a, x| a << x.send(op, *args) }.flatten
       result = []
       each { |x| result << x.send(op, *args) }
       result.flatten.accumulate_all(iterations - 1)

data/lib/core/facets/enumerable/apply.rb

@@ -0,0 +1,20 @@
+#require 'facets/functor'
+require 'facets/enumerable/per'
+
+module Enumerable
+
+  # Returns an elemental object. This allows
+  # you to map a method on to every element.
+  #
+  #   r = [1,2,3].apply.+ 
+  #   r  #=> 6
+  #
+  def apply
+    #Functor.new do |sym, *args, &blk|
+    #  inject{ |r, e| r.__send__(sym, e, *args, &blk) }
+    #end
+    per(:inject)
+  end
+
+end
+

data/lib/core/facets/enumerable/associate.rb

@@ -0,0 +1,6 @@
+require 'facets/enumerable/pair'
+
+module Enumerable
+  # Alias for #pair.
+  alias :associate :pair
+end

data/lib/core/facets/enumerable/cluster.rb

@@ -0,0 +1,24 @@
+module Enumerable
+
+  # Clusters together adjacent elements into a list of 
+  # sub-arrays.
+  #
+  # >> [2,2,2,3,3,4,2,2,1].cluster{ |x| x }
+  # => [[2, 2, 2], [3, 3], [4], [2, 2], [1]]
+  #
+  # @author Oleg K
+
+  def cluster
+    cluster = []
+    each do |element|
+      if cluster.last && yield(cluster.last.last) == yield(element)
+        cluster.last << element
+      else
+        cluster << [element]
+      end
+    end
+    cluster
+  end
+
+end
+

data/lib/core/facets/enumerable/every.rb

@@ -20,7 +20,7 @@ module Enumerable
   end
 
   #--
-  # These used to be defined via Functors as follows ...
+  # These used to be defined via H.O.M. as follows ...
   #
   #  def every
   #    Functor.new do |op,*args|

data/lib/core/facets/enumerable/ewise.rb

@@ -2,6 +2,8 @@ require 'facets/functor'
 
 module Enumerable
 
+  # TODO: Should Enumerable#ewise be moved to functor gem?"
+
   # Returns an elementwise Functor designed to make R-like
   # elementwise operations possible. This is very much like
   # the #every method, but it treats array argument specially.

data/lib/core/facets/enumerable/graph.rb

@@ -30,8 +30,5 @@ module Enumerable
     end
   end
 
-  # Alias for #graph, which stands for "map hash".
-  alias_method :mash, :graph
-
 end
 

data/lib/core/facets/enumerable/hashify.rb

@@ -1,31 +1,234 @@
+#require 'facets/enumerator'
+require 'facets/hash/dearray_values'
+require 'facets/enumerable/value_by'
+
 module Enumerable
-  # Create a hash whose keys are the enumerable's elements, with specified
-  # values.
+
+  # The hashify methods is a higher-order message used to 
+  # convert an enumerable object into a hash. Converting an
+  # enumerable object into a hash is not a one-to-one conversion,
+  # for this reason #hashify is used to provide variant approches
+  # for the conversion most suited to the use case at hand.
+  # Here are some (but not a complete set of) examples.
+  # 
+  # If the enumerable is a collection of perfect pairs, like that
+  # which Hash#to_a generates, then #assoc can be used.
+  #
+  #   a = [ [:a,1], [:b,2] ]
+  #   a.hashify.assoc  #=> { :a=>1, :b=>2 }
   #
-  # If no block is given, the given parameter (default true) is used for
-  # all values, e.g.:
+  # If it it contains only arrays, but are not perfect pairs,
+  # then #concat can be used.
   #
-  #     [1,2,3,4].hashify               #=> {1=>true, 2=>true, 3=>true, 4=>true}
-  #     [1,2,3,4].hashify("a")          #=> {1=>"a", 2=>"a", 3=>"a", 4=>"a"}
+  #   a = [ [:a,1,2], [:b,2], [:c], [:d] ]
+  #   a.hashify.concat  #=> { :a=>[1,2], :b=>[2], :c=>[], :d=>[] }
   #
-  # If a block is given, each key's value is the result of running the
-  # block for that key, e.g.:
+  # If the array contians objects other then arrays then
+  # the #splat method might do the trick.
   #
-  #     [1,2,3,4].hashify{|n| "a" * n}  #=> {1=>"a", 2=>"aa", 3=>"aaa", 4=>"aaaa"}
+  #   a = [ [:a,1,2], 2, :b, [:c,3], 9 ]
+  #   a.hashify.splat  #=> { [:a,1,2]=>2, :b=>[:c,3], 9=>nil } 
   #
-  # @author Ronen Barzel
+  # Also, the particular dispatch can be left up the Hashify 
+  # using the #auto method. See Hashify#auto for details on this.
   #
-  # @uncommon
-  #   require 'facets/enumerable/hashify'
+  # TODO: This method takes arguments only for the sake of the old
+  # method which has been deprecated. These will be removed eventually.
   #
-  def hashify(val=true)
-    h = {}
-    if block_given?
-      each { |item| h[item] = yield(item) }
-    else
-      each { |item| h[item] = val }
+  # CREDIT: Robert Klemme, Sandor Szücs, Trans
+
+  def hashify(val=nil, &block)
+    if val
+      warn "The old Enumerable#hashify method has been be deprecated. Use #value_by instead."
+      value_by{ val }
+    end
+
+    if block
+      warn "The old Enumerable#hashify method has been be deprecated. Use #value_by instead."
+      value_by(&block)
     end
-    h
+
+    Hashifier.new(self)
+  end
+
+  #
+  class Hashifier
+
+    def initialize(enum)
+      @enum = enum
+    end
+
+    # This is equivalent to Hash[*array], but it will pad
+    # the array with a +nil+ object if there are not an even number
+    # of elements.
+    #
+    #   a = [:a,1,:b,2,:c]
+    #   a.to_h_splat  #=> { :a=>1, :b=>2, :c=>nil }
+    #
+    # TODO: Can this be done without #size?
+    def splat
+      a = @enum.dup
+      a << nil if a.size % 2 == 1
+      Hash[*a]
+    end
+
+    # This is equivalent to Hash[*array.flatten], but it will pad
+    # the array with a +nil+ object if there are not an even number
+    # of elements.
+    #
+    #   a = [:a,1,[:b,2,:c]]
+    #   a.to_h_flat  #=> { :a=>1, :b=>2, :c=>nil }
+    #
+    # TODO: Need to do this without #size.
+    def flat
+      a = @enum.flatten
+      a << nil if a.size % 2 == 1
+      Hash[*a]
+    end
+
+    # When a mixed or multi-element accociative array
+    # is used, the result is as follows:
+    #
+    #   a = [ [:a,1,2], [:b,2], [:c], :d ]
+    #   a.hashify.assoc  #=> { :a=>[1,2], :b=>[2], :c=>[], :d=>[] }
+    #
+    # If the first entry of any subelements are the same, then
+    # the value will be set to the last occuring value.
+    #
+    #   a = [ :x, [:x], [:x,1,2], [:x,3], [:x,4] ]
+    #   a.hashify.assoc  #=> { :x=>[4] }
+    #
+    def associate
+      h = {}
+      each do |k,*v| 
+        h[k] = v
+      end
+      h
+    end
+
+    # Alias for #associate.
+    alias :assoc, :associate
+
+    # Like associate but does force values into an array.
+    #
+    def merge
+      h = {}
+      each do |k,v| 
+        h[k] = v
+      end
+      h
+    end
+
+    # When a mixed or multi-element accociative array
+    # is used, the result is as follows:
+    #
+    #   a = [ [:a,1,2], [:b,2], [:c], :d ]
+    #   a.hashify.concat  #=> { :a=>[1,2], :b=>[2], :c=>[], :d=>[] }
+    #
+    # If the first entry of the subelements is the same, then
+    # the values will be merged using #concat.
+    #
+    #   a = [ [:a,1,2], [:a,3], [:a,4], [:a], :a ]
+    #   a.hasify.concat  #=> { :a=>[1,2,3,4] }
+    #
+    def concat
+      h = {}
+      each do |k,*v| 
+        h[k] ||= []
+        h[k].concat(v)
+      end
+      h
+    end
+
+    # Older name for #concat.
+    alias :multi, :concat
+
+    # Convert enumerable object to Hash using index as keys.
+    #
+    #   [:a, :b, :c].hashify.by_index  #=> {1=>:a, 2=>:b, 3=>:c}
+    #
+    def by_index
+      h = {}
+      each_with_index do |v, i|
+        h[i] = v
+      end
+      h
+    end
+
+    # Converts enumerable object into a hash. Converting an array
+    # into a hash is not a one-to-one conversion, for this
+    # reason #auto examines the enumerable being converted
+    # and then dispatches the conversion to the most sutiable
+    # specialized function. There are three possiblities for this.
+    #
+    # If the enumerable is a collection of perfect pairs, like that
+    # which Hash#to_a generates, then conversion is handled by 
+    # #flat.
+    #
+    #   a = [ [:a,1], [:b,2] ]
+    #   a.hashify.auto  #=> { :a=>1, :b=>2 }
+    #
+    # If it contains only arrays, but are not perfect pairs,
+    # then #multi is called.
+    #
+    #   a = [ [:a,1,2], [:b,2], [:c], [:d] ]
+    #   a.hashify.auto  #=> { :a=>[1,2], :b=>[2], :c=>[], :d=>[] }
+    #
+    # If it contians objects other then arrays then the #splat method
+    # is called.
+    #
+    #   a = [ [:a,1,2], 2, :b, [:c,3], 9 ]
+    #   a.hashify.auto  #=> { [:a,1,2]=>2, :b=>[:c,3], 9=>nil } 
+    #
+    # Be aware this is not as efficient as using the underlying methods
+    # directly becuase it must perform an initial iteration over the
+    # enumerable to determine its contents.
+
+    def auto(&block)
+      pairs, mixed = true, false
+
+      each do |e|
+        case e
+        when Array
+          pairs = false if e.size > 2
+        else
+          mixed = true
+        end
+      end
+
+      if mixed
+        splat(&block)
+      elsif pairs
+        flat(&block)
+      else
+        multi(&block)
+      end
+    end
+
+    # Alias for `#auto`.
+    alias :automatic, :auto
+
+  private
+
+    #
+    def each(&b)
+      @enum.each(&b) 
+    end
+
+    #
+    def each_with_index(&b)
+      @enum.each_with_index(&b) 
+    end
+
   end
 
 end
+
+
+#class Enumerator
+#  # See `Enumerable#hashify`.
+#  def hashify
+#    Hashifier.new(self)
+#  end
+#end
+

data/lib/core/facets/enumerable/hinge.rb

@@ -0,0 +1,18 @@
+module Enumerable
+
+  # Apply each element of an enumerable ot a hash
+  # by iterating over each element and yielding
+  # the hash and element.
+  #
+  #   [1,2,3].hinge{|h,e| h[e] = e+1 }
+  #   #=> {1=>2, 2=>3, 3=>4}
+  #
+  # TODO: Enumerable#hinge will get a new name.
+  #
+  def hinge(init={})
+    h = init
+    each{ |v| yield(h,v) }
+    h
+  end
+
+end

data/lib/core/facets/enumerable/key_by.rb

@@ -0,0 +1,27 @@
+module Enumerable
+
+  # Convert enumerable into a Hash, iterating over each member
+  # where the provided block must return the key to by used
+  # to map to the value.
+  #
+  # Examples:
+  #
+  #   [:a,:b,:c].key_by{ |v| v.to_s }
+  #   #=> {'a'=>:a, 'b'=>:b, 'c'=>:c}
+  #
+  # TODO: How should this method behave with a Hash?
+  #
+  # Returns: Hash
+
+  def key_by
+    return to_enum(:key_by) unless block_given?
+
+    h = {}
+    each do |v|
+      h[yield(v)] = v
+    end
+
+    return h
+  end
+
+end