facets-glimmer 3.2.0

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

@@ -0,0 +1,230 @@
+#require 'facets/enumerator'
+require 'facets/hash/dearray_values'
+require 'facets/enumerable/value_by'
+
+module Enumerable
+
+  # 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 it it contains only arrays, but are not perfect pairs,
+  # then #concat can be used.
+  #
+  #   a = [ [:a,1,2], [:b,2], [:c], [:d] ]
+  #   a.hashify.concat  #=> { :a=>[1,2], :b=>[2], :c=>[], :d=>[] }
+  #
+  # If the array contains objects other then arrays then
+  # the #splat method might do the trick.
+  #
+  #   a = [ [:a,1,2], 2, :b, [:c,3], 9 ]
+  #   a.hashify.splat  #=> { [:a,1,2]=>2, :b=>[:c,3], 9=>nil }
+  #
+  # Also, the particular dispatch can be left up the Hashify
+  # using the #auto method. See Hashify#auto for details on this.
+  #
+  # TODO: This method takes arguments only for the sake of the old
+  # method which has been deprecated. These will be removed eventually.
+  #
+  # 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
+
+    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 }
+    def splat
+      a = @enum.to_a
+      a << nil if a.size.odd?
+      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 }
+    def flat
+      a = @enum.to_a.flatten
+      a << nil if a.size.odd?
+      Hash[*a]
+    end
+
+    # When a mixed or multi-element associative 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 occurring 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 associative 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.hashify.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 suitable
+    # specialized function. There are three possibilities 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 contains 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 because 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/incase.rb

@@ -0,0 +1,19 @@
+module Enumerable
+  
+  # The same as #include? but tested using #=== instead of #==.
+  # 
+  #   [1, 2, "a"].incase?(2)       #=> true
+  #   [1, 2, "a"].incase?(String)  #=> true
+  #   [1, 2, "a"].incase?(3)       #=> false
+  #
+  # Why the name `incase`? Because the method uses case-equality.
+  # Along with the alliteration for "in case" and the similarity
+  # with "include?", it seemed like the perfect fit.
+  #
+  # @author Lavir the Whiolet
+  #
+  def incase?(what)
+    any? { |x| what === x }
+  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

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

@@ -0,0 +1,35 @@
+module Enumerable
+
+  # Like #group_by, but maps the second value returned from the block.
+  #
+  #   a = [1,2,3,4,5]
+  #   a.map_by{ |e| [e % 2, e + 1] }
+  #   #=> { 0=>[3,5], 1=>[2,4,6] }
+  #
+  # Works well with a hash too.
+  #
+  #   h = {"A"=>1, "B"=>1, "C"=>1, "D"=>2, "E"=>2}
+  #   h.map_by{ |k,v| [v, k.downcase] }
+  #   #=> {1=>["a", "b", "c"], 2=>["d", "e"]}
+  #
+  # If a second value is not returned, #map_by acts like #group_by.
+  #
+  #   h = {"A"=>1, "B"=>1, "C"=>1, "D"=>2, "E"=>2}
+  #   h.map_by{ |k,v| v }
+  #   #=> {1=>[["A",1], ["B",1], ["C",1]], 2=>[["D",2], ["E",2]]}
+  #
+  def map_by #:yield:
+    res = {}
+    each do |a|
+      k,v = yield(*a)
+      if v
+        (res[k] ||= []) << v
+      else
+        (res[k] ||= []) << a
+      end
+    end
+    res
+  end
+
+end
+

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

@@ -0,0 +1 @@
+require 'facets/enumerable/find_yield'

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

@@ -0,0 +1,26 @@
+module Enumerable
+
+  # Send a message to each element and collect the result.
+  #
+  #   [1,2,3].map_send(:+, 3)  #=> [4,5,6]
+  #
+  # CREDIT: Sean O'Halpin
+
+  def map_send(meth, *args, &block)
+    map{|e| e.send(meth, *args, &block)}
+  end
+
+  #--
+  # Old defintion confused me ...
+  #
+  #   def map_send(meth, *args) #:yield:
+  #     if block_given?
+  #       map{|e| yield(e.send(meth, *args))}
+  #     else
+  #       map{|e| e.send(meth, *args)}
+  #     end
+  #   end
+  #++
+
+end
+

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

@@ -0,0 +1,13 @@
+module Enumerable
+
+  # Map each element into another class via class constructor.
+  #
+  # @param [#new] to_class
+  #   Generally a class, but any object that repsonds to #new.
+  #
+  def map_to(to_class)
+    map{ |e| to_class.new(e) }
+  end
+
+end
+

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

@@ -0,0 +1,21 @@
+module Enumerable
+
+  # Combines #zip and #map in a single efficient operation.
+  #
+  #   h = {}
+  #   [1,2,3].map_with [:x,:y,:z] do |n,k|
+  #     h[k] = n
+  #   end
+  #   h  #=> {:x=>1, :y=>2, :z=>3}
+  #
+  # @return [Hash]
+  #
+  # @author Michael Kohl
+  def map_with(*arrays, &block)
+    enum_for(:zip, *arrays).map(&block)
+  end
+
+  #
+  alias_method :zip_map, :map_with
+
+end

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

@@ -0,0 +1,23 @@
+module Enumerable
+
+  # Same as #collect but with an iteration counter.
+  #
+  #   a = [1,2,3].collect_with_index { |e,i| e*i }
+  #   a  #=> [0,2,6]
+  #
+  # CREDIT: Gavin Sinclair
+
+  def map_with_index
+    r = []
+    each_with_index do |e, i|
+      r << yield(e, i)
+    end
+    r
+  end
+
+  # Alias for map_with_index.
+
+  alias_method :collect_with_index, :map_with_index
+
+end
+

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

@@ -0,0 +1,34 @@
+module Enumerable
+
+  # Like `#map`/`#collect`, but generates a Hash. The block is expected
+  # to return two values: the key and the value for the new hash.
+  #
+  #   numbers  = (1..3)
+  #   squares  = numbers.mash{ |n| [n, n*n] }   # { 1=>1, 2=>4, 3=>9 }
+  #   sq_roots = numbers.mash{ |n| [n*n, n] }   # { 1=>1, 4=>2, 9=>3 }
+  #
+  # CREDIT: Andrew Dudzik (adudzik), Trans
+
+  def mash(&yld)
+    if yld
+      h = {}
+      each do |*kv|
+        r = yld[*kv]
+        case r
+        when Hash
+          nk, nv = *r.to_a[0]
+        when Range
+          nk, nv = r.first, r.last
+        else
+          nk, nv = *r
+        end
+        h[nk] = nv
+      end
+      h
+    else
+      Enumerator.new(self,:graph)
+    end
+  end
+
+end
+

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

@@ -0,0 +1,22 @@
+module Enumerable
+
+  # Divide an array into groups by modulo of the index.
+  #
+  #   [2,4,6,8].modulate(2)  #=> [[2,6],[4,8]]
+  #
+  # CREDIT: Trans
+  #
+  # NOTE: Would the better name for this be 'collate'?
+
+  def modulate(modulo)
+    return to_a if modulo == 1
+    raise ArgumentError, 'bad modulo' if size % modulo != 0
+    r = Array.new(modulo, [])
+    (0...size).each do |i|
+      r[i % modulo] += [self[i]]
+    end
+    r
+  end
+
+end
+

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

@@ -0,0 +1,41 @@
+module Enumerable
+
+  # Returns an array of elements for the elements that occur n times.
+  # Or according to the results of a given block.
+  #
+  #     a = [1,1,2,3,3,4,5,5]
+  #
+  #     a.occur(1).sort               #=> [2,4]
+  #     a.occur(2).sort               #=> [1,3,5]
+  #     a.occur(3).sort               #=> []
+  #
+  #     a.occur(1..1).sort            #=> [2,4]
+  #     a.occur(2..3).sort            #=> [1,3,5]
+  #
+  #     a.occur { |n| n == 1 }.sort   #=> [2,4]
+  #     a.occur { |n| n > 1 }.sort    #=> [1,3,5]
+  #
+  def occur(n=nil) #:yield:
+    result = Hash.new { |hash, key| hash[key] = Array.new }
+
+    each do |item|
+      key = item
+      result[key] << item
+    end
+
+    if block_given?
+      result.reject! { |key, values| ! yield(values.size) }
+    else
+      raise ArgumentError unless n
+      if Range === n
+        result.reject! { |key, values| ! n.include?(values.size) }
+      else
+        result.reject! { |key, values| values.size != n }
+      end
+    end
+
+    return result.values.flatten.uniq
+  end
+
+end
+

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

@@ -0,0 +1,56 @@
+module Enumerable
+  
+  # Returns the _only_ element in the enumerable. Raises an IndexError if
+  # the enumreable has more then one element.
+  #
+  #   [5].only      # => 5
+  #
+  #   expect IndexError do
+  #     [1,2,3].only
+  #   end
+  #
+  #   expect IndexError do
+  #     [].only
+  #   end
+  #
+  # CREDIT: Lavir the Whiolet, Gavin Sinclair, Noah Gibbs
+  #
+  def only
+    first = false
+    first_item = nil
+
+    each do |item|
+      if first
+        raise IndexError, "not the only element of enumerable"
+      else
+        first = true
+        first_item = item
+      end
+    end
+ 
+    if first
+      return first_item
+    else
+      raise IndexError, "not the only element of enumerable"
+    end
+  end
+
+  # Does this Enumerable have the only element?
+  # 
+  # It differs from Enumerable#one? in that it does not check the items
+  # themselves. It checks the quantity only.
+  # 
+  # CREDIT: Lavir the Whiolet
+  #
+  def only?
+    first = false
+
+    each do |item|
+      return false if first
+      first = true
+    end
+
+    return first
+  end
+
+end

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

@@ -0,0 +1,19 @@
+module Enumerable
+
+  # Similar to #group_by but returns an array of the groups.
+  # Returned elements are sorted by block.
+  #
+  #    %w{this is a test}.organize_by {|x| x[0]}
+  #    #=> [ ['a'], ['is'], ['this', 'test'] ]
+  #
+  # CREDIT: Erik Veenstra
+
+  def organize_by(&b)
+    group_by(&b).sort.transpose.pop || []   # group_by(&b).values ?
+  end
+
+  # DEPRECATED: Name changed to avoid confusion with #cluster.
+  alias cluster_by organize_by
+
+end
+

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

@@ -0,0 +1,20 @@
+module Enumerable
+
+  # Like `each_slice(2)` but ensures the last 
+  # element has a pair if odd sized.
+  #
+  #   [:a,1,:b,2,:c,3].pair.to_a  #=> [[:a,1],[:b,2],[:c,3]]
+  #
+  def pair(missing=nil)
+    return to_enum(:pair) unless block_given?
+
+    each_slice(2) do |kv|
+      if kv.size == 1
+        yield kv.first, missing
+      else
+        yield kv.first, kv.last
+      end
+    end
+  end
+
+end

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

@@ -0,0 +1,77 @@
+require 'facets/functor'
+
+module Enumerable
+
+  # TODO: Consider Enumerator methods.
+
+  # TODO: Should Enumerable#pre be moved to functor gem?
+
+  # TODO: Does the `*y` argument make sense?
+
+  # Per element meta-functor.
+  #
+  #     ([1,2,3].per(:map) + 3)     #=> [4,5,6]
+  #     ([1,2,3].per(:select) > 1)  #=> [2,3]
+  #
+  # Using fluid notation.
+  #
+  #     ([1,2,3].per.map + 3)       #=> [4,5,6]
+  #     ([1,2,3].per.select > 1)    #=> [2,3]
+  #
+  def per(enum_method=nil, *enum_args)
+    if enum_method
+      Functor.new do |op, *args, &blk|
+        __send__(enum_method || :map, *enum_args){ |x, *y| x.__send__(op, *y, *args, &blk) }
+      end
+    else
+      Functor.new do |enumr_method, *enumr_args|
+        Functor.new do |op, *args, &blk|
+          __send__(enumr_method, *enumr_args){ |x, *y| x.__send__(op, *y, *args, &blk) }
+        end
+      end
+    end
+  end
+
+=begin
+  def per(enum_method=nil, *enum_args)
+    if enum_method
+      Permeator.new(self, enum_method, *enum_args)
+    else
+      Functor.new do |enumr_method, *enumr_args|
+        Permeator.new(self, enumr_method, *enumr_args)
+      end
+    end
+  end
+
+  # Permeator is a Functor for operating over each element of an Enumearble.
+  # (Note: This used to be called an Elementor.)
+  #
+  # TODO: With Ruby 1.9+ this would not be required, as it can be replaced
+  # by a generic Functor, becuase then lambda definitions can pass blocks.
+  #
+  class Permeator #:nodoc:
+    private(*instance_methods.select{|x| x !~ /^__/ })
+
+    def initialize(enum_object, enum_method=nil, *enum_args)
+      @enum_object = enum_object
+      @enum_method = enum_method || :map
+      @enum_args   = enum_args
+    end
+
+    def instance_delegate
+      @enum_object
+    end
+
+    def instance_operator
+      @enum_method
+    end
+
+    def method_missing(sym, *args, &blk)
+      #@enum_object.__send__(@enum_method){ |x| x.__send__(sym, *args, &blk) }
+      @enum_object.__send__(@enum_method){ |x, *y| x.__send__(sym, *y, *args, &blk) }
+    end
+  end
+=end
+
+end
+