facets 2.8.4 → 2.9.0.pre.1

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

@@ -5,7 +5,8 @@ module Enumerable
   # Returns an elemental object. This allows
   # you to map a method on to every element.
   #
-  #   r = [1,2,3].every + 3  #=> [4,5,6]
+  #   r = [1,2,3].every + 3
+  #   r  #=> [4,5,6]
   #
   def every
     per(:map)
@@ -18,18 +19,22 @@ module Enumerable
     per(:map!)
   end
 
-  #def every
-  #  Functor.new do |op,*args|
-  #    map{ |a| a.send(op,*args) }
+  #--
+  # These used to be defined via Functors as follows ...
+  #
+  #  def every
+  #    Functor.new do |op,*args|
+  #      map{ |a| a.send(op,*args) }
+  #    end
   #  end
-  #end
-
-  #def every!
-  #  raise NoMethodError unless respond_to?(:map!)
-  #  Functor.new do |op,*args|
-  #    map!{ |a| a.send(op,*args) }
+  #
+  #  def every!
+  #    raise NoMethodError unless respond_to?(:map!)
+  #    Functor.new do |op,*args|
+  #      map!{ |a| a.send(op,*args) }
+  #    end
   #  end
-  #end
+  #++
 
 end
 

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

@@ -2,20 +2,20 @@ require 'facets/functor'
 
 module Enumerable
 
-  EWISE = {}
-
   # 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.
   #
-  #   [1,2].ewise + 3          #=> [4,5]
-  #   [1,2].ewise + [4,5]      #=> [5,7]
-  #   [1,2].ewise + [[4,5],3]  #=> [[5,7],[4,5]
+  #   ([1,2].ewise + 3)          #=> [4,5]
+  #
+  # Vector to vector
+  #
+  #   ([1,2].ewise + [4,5])      #=> [5,7]
   #
   # Special thanks to Martin DeMello for helping to develop this.
 
   def ewise(count=1)
-    EWISE[[self,count]] ||= Functor.new do |op,*args|
+    Functor.new do |op,*args|
       if args.empty?
         r = self
         count.times do
@@ -28,8 +28,9 @@ module Enumerable
             x = self
             count.times do
               ln = (arg.length > length ? length : arg.length )
-              x = x.slice(0...ln).zip(arg[0...ln]).collect{ |a,b| a.send(op,b) }
-              #slice(0...ln).zip(arg[0...1n]).collect{ |a,b| b ? a.send(op,b) : nil }
+              x = x.slice(0...ln)
+              x = x.zip(arg[0...ln])
+              x = x.collect{ |a,b| a.send(op,b) }  #x = x.collect{ |a,b| b ? a.send(op,b) : nil }
             end
             x
           else
@@ -49,19 +50,10 @@ module Enumerable
   # Long-term for #ewise.
   #
   #   a = [1,2]
-  #   a.elementwise + 3          #=> [4,5]
-  #   a.elementwise + [4,5]      #=> [5,7]
-  #   a.elementwise + [[4,5],3]  #=> [[5,7],[4,5]
+  #   (a.elementwise + 3)          #=> [4,5]
+  #   (a.elementwise + [4,5])      #=> [5,7]
   #
   alias_method :elementwise, :ewise
 
-  # Operator equivalent of #elementwise.
-  #
-  # This was deprecated along with it's file "op_tilde.rb".
-  #
-  #def ~@
-  #  ewise
-  #end
-
 end
 

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

@@ -1,9 +1,12 @@
 module Enumerable
 
-  unless method_defined?(:exclude?) or defined?(::ActiveSupport)  # 1.9 or ActiveSupport
+  unless method_defined?(:exclude?) # 1.9
 
     # The inverse of #include?.
     #
+    #  [:a, :b].exclude?(:c)  #=> true
+    #  [:a, :b].exclude?(:a)  #=> false
+    #
     def exclude?(object)
       !include?(object)
     end

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

@@ -0,0 +1,15 @@
+module Enumerable
+
+  # Expand all elements of an Enumerable object.
+  #
+  #   [0, 2..3, 5..7].expand  #=> [0,[2, 3],[5,6,7]]
+  #
+  # CREDIT: Trans
+  def expand
+    map do |x|
+     (Enumerable === x ? x.expand : x)
+    end
+  end
+
+end
+

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

@@ -5,14 +5,18 @@ module Enumerable
   # additional elements. The first object passed to the block is
   # the receiver of the output.
   #
-  #   (1..1_000_000_000).
-  #     filter{ |out,i| out << i if i % 2 == 0 }.  # like select
-  #     filter{ |out,i| out << i + 100 }.          # like map
-  #     take(10).each{ |i| puts i }
+  #   x = (1..10000)
+  #   x = x.filter{ |out,i| out << i if i % 2 == 0 }   # like select
+  #   x = x.filter{ |out,i| out << i + 100 }           # like map
+  #   x = x.take(3)
+  #
+  #   x  #=> [102, 104, 106]
   #
   # This is very similar to #each_with_object, but #filter handles
   # argument better by reversing their order and using the splat
-  # operator.
+  # operator. (This was also once known as #injecting.)
+  #
+  # CREDIT: David Black, Louis J Scoras
 
   def filter(output=[]) #:yeild:
     if block_given?
@@ -25,11 +29,5 @@ module Enumerable
     end
   end
 
-  # OLD NAME
-  # CREDIT: David Black, Louis J Scoras
-  #def injecting(k)
-  #  each{ |i| yield(k, i) }; k
-  #end
-
 end
 

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

@@ -4,15 +4,20 @@ module Enumerable
   # of the block when that result evaluates as true,
   # terminating early like #detect and #find.
   # 
-  #   obj1.foo? #=> false
-  #   obj2.foo? #=> true
-  #   obj2.foo  #=> "value"
+  #   obj1 = Object.new
+  #   obj2 = Object.new
   #
-  #   [obj1, obj2].find_yield{ |obj| obj.foo if obj.foo? }     #=> "value"
+  #   def obj1.foo?; false; end
+  #   def obj2.foo?; true ; end
   #
-  # Another example:
+  #   def obj1.foo ; "foo1"; end
+  #   def obj2.foo ; "foo2"; end
   #
-  #   [1,2,3,4,5].find_yield{ |i| j = i+1; j if j % 4 == 0 }   #=> "5"
+  #   [obj1, obj2].find_yield{ |obj| obj.foo if obj.foo? }  #=> "foo2"
+  #
+  # Another example.
+  #
+  #   [1,2,3,4,5].find_yield{ |i| j = i+1; j if j % 4 == 0 }  #=> 4
   #
   # If the block is never true, return the object given in the first parameter,
   # or nil if none specified.
@@ -28,10 +33,10 @@ module Enumerable
     fallback
   end
 
+  # Alias for #find_yield.
+  #
   # DEPRECATE: This has been renamed to #find_yield.
-  def map_detect(fallback=nil)
-    find_yield(fallback)
-  end
+  alias_method :map_detect, :find_yield
 
 end
 

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

@@ -3,15 +3,21 @@ module Enumerable
   # Generates a hash mapping each unique symbol in the array
   # to the absolute frequency it appears.
   #
+  #   [:a,:a,:b,:c,:c,:c].frequency  #=> {:a=>2,:b=>1,:c=>3}
+  #
   # CREDIT: Brian Schröder
+  #
+  #--
+  # NOTE: So why not use #inject here? e.g. ...
+  #
+  #   inject(Hash.new(0)){|p,v| p[v]+=1; p}
+  #
+  # Because it is a fair bit slower than the traditional definition.
+  #++
 
   def frequency
-    #probs = Hash.new(0)
-    #each do |e|
-    #  probs[e] += 1
-    #end
-    #probs
-    inject(Hash.new(0)){|h,v| h[v]+=1; h}
+    p = Hash.new(0); each{ |v| p[v] += 1 }; p
+
   end
 
 end

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

@@ -1,7 +1,7 @@
 module Enumerable
 
-  # Like <tt>#map</tt>/<tt>#collect</tt>, but generates a Hash. The block
-  # is expected to return two values: the key and the value for the new hash.
+  # 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.graph{ |n| [n, n*n] }   # { 1=>1, 2=>4, 3=>9 }

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

@@ -1,21 +1,27 @@
 module Enumerable
 
-  unless method_defined?(:group_by) or defined?(::ActiveSupport)  # 1.9 or ActiveSupport
+  unless method_defined?(:group_by) # 1.9
 
-    # #group_by is used to group items in a collection by something they
-    # have in common.  The common factor is the key in the resulting hash, the
-    # array of like elements is the value.
+    # Enumerable#group_by is used to group items in a collection by something
+    # they have in common.  The common factor is the key in the resulting hash,
+    # the array of like elements is the value.
     #
     #   (1..5).group_by { |n| n % 3 }
-    #        #=> { 0 => [3], 1 => [1, 4], 2 => [2,5] }
+    #   #=> { 0 => [3], 1 => [1, 4], 2 => [2,5] }
+    #
+    # Applied to an array.
     #
     #   ["I had", 1, "dollar and", 50, "cents"].group_by { |e| e.class }
-    #        #=> { String => ["I had","dollar and","cents"], Fixnum => [1,50] }
+    #   #=> { String => ["I had","dollar and","cents"], Fixnum => [1,50] }
+    #
+    # Applied to a hash:
+    #
+    #   {:a=>1, :b=>2, :c=>1}.group_by{ |k,v| v }
+    #   #=> { 1=>[[:c,1], [:a,1]], 2=>[[:b,2]] }
     #
     # CREDIT: Erik Veenstra
 
     def group_by #:yield:
-      #h = k = e = nil
       r = Hash.new
       each{ |e| (r[yield(e)] ||= []) << e }
       r

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_send.rb

@@ -2,23 +2,25 @@ 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
 
-  # Send a message to each element and collect the result.
-  #
-  # CREDIT: Sean O'Halpin
+  #--
+  # 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
+  #   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/modulate.rb

@@ -2,7 +2,7 @@ module Enumerable
 
   # Modulate. Divide an array into groups by modulo of the index.
   #
-  # [2,4,6,8].modulate(2)  #=> [[2,6],[4,8]]
+  #   [2,4,6,8].modulate(2)  #=> [[2,6],[4,8]]
   #
   # CREDIT: Trans
   #

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

@@ -10,11 +10,11 @@ module Enumerable
     # if and only if _none_ of the elements have a true value
     # (i.e. not +nil+ or +false+).
     #
-    #   [].none?                      # true
-    #   [nil].none?                   # true
-    #   [5,8,9].none?                 # false
-    #   (1...10).none? { |n| n < 0 }  # true
-    #   (1...10).none? { |n| n > 0 }  # false
+    #   [].none?                      # => true
+    #   [nil].none?                   # => true
+    #   [5,8,9].none?                 # => false
+    #   (1...10).none? { |n| n < 0 }  # => true
+    #   (1...10).none? { |n| n > 0 }  # => false
     #
     # CREDIT: Gavin Sinclair
 

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

@@ -3,15 +3,17 @@ module Enumerable
   # Returns an array of elements for the elements that occur n times.
   # Or according to the results of a given block.
   #
-  #   [1,1,2,3,3,4,5,5].occur(1)             #=> [2,4]
-  #   [1,1,2,3,3,4,5,5].occur(2)             #=> [1,3,5]
-  #   [1,1,2,3,3,4,5,5].occur(3)             #=> []
+  #   a = [1,1,2,3,3,4,5,5]
   #
-  #   [1,2,2,3,3,3].occur(1..1)              #=> [1]
-  #   [1,2,2,3,3,3].occur(2..3)              #=> [2,3]
+  #   a.occur(1).sort               #=> [2,4]
+  #   a.occur(2).sort               #=> [1,3,5]
+  #   a.occur(3).sort               #=> []
   #
-  #   [1,1,2,3,3,4,5,5].occur { |n| n == 1 } #=> [2,4]
-  #   [1,1,2,3,3,4,5,5].occur { |n| n > 1 }  #=> [1,3,5]
+  #   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 }

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

@@ -9,12 +9,12 @@ module Enumerable
     # and only if <em>exactly one</em> element has a true value
     # (i.e. not +nil+ or +false+).
     #
-    #   [].one?                      # false
-    #   [nil].one?                   # false
-    #   [5].one?                     # true
-    #   [5,8,9].one?                 # false
-    #   (1...10).one? { |n| n == 5 } # true
-    #   (1...10).one? { |n| n < 5 }  # false
+    #   [].one?                      # => false
+    #   [nil].one?                   # => false
+    #   [5].one?                     # => true
+    #   [5,8,9].one?                 # => false
+    #   (1...10).one? { |n| n == 5 } # => true
+    #   (1...10).one? { |n| n < 5 }  # => false
     #
     # CREDIT: Gavin Sinclair
 

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

@@ -8,25 +8,20 @@ module Enumerable
 
   # Per element meta-functor.
   #
-  #   [1,2,3].per + 3             #=> [4,5,6]
-  #   [1,2,3].per(:map) + 3       #=> [4,5,6]
-  #   [1,2,3].per(:select) > 1    #=> [2,3]
+  #   ([1,2,3].per(:map) + 3)     #=> [4,5,6]
+  #   ([1,2,3].per(:select) > 1)  #=> [2,3]
   #
-  #   [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
       Permeator.new(self, enum_method, *enum_args)
-      #Functor.new do |op, *args|
-      #  __send__(enum_method, *enum_args){ |x| x.__send__(op, *args) } #, &blk) }
-      #end
     else
-      Functor.new do |enum_method, *enum_args|
-        Permeator.new(self, enum_method, *enum_args)
-        #Functor.new do |op, *args|
-        #  __send__(enum_method, *enum_args){ |x| x.__send__(op, *args) } #, &blk) }
-        #end
+      Functor.new do |enumr_method, *enumr_args|
+        Permeator.new(self, enumr_method, *enumr_args)
       end
     end
   end
@@ -59,5 +54,32 @@ module Enumerable
     end
   end
 
+## TODO: Use this when 1.8.6 support is not longer needed.
+=begin
+    # 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, *enum_args){ |x| x.__send__(op, *args, &blk) }
+        end
+      else
+        Functor.new do |enumr_method, *enumr_args|
+          Functor.new do |op, *args, &blk|
+            __send__(enumr_method, *enumr_args){ |x| x.__send__(op, *args, &blk) }
+          end
+        end
+      end
+    end
+=end
+
 end