enumerable_fu 0.1.0 → 0.1.1

data/README.markdown

@@ -1,50 +1,84 @@
 EnumerableFu
 ============
 
-"EnumerableFu" extends `Enumerable` with "lazy" versions of various operations, 
-allowing streamed processing of large (or even infinite) collections.
+Lazy "filtering" and transforming
+---------------------------------
 
-It also provides some interesting ways of combining Enumerables.
+EnumerableFu extends Enumerable with "lazy" versions of various common operations:
 
-Filters
--------
+* `#selecting` selects elements that pass a test block (like `Enumerable#select`)
+* `#rejecting` selects elements that fail a test block (like `Enumerable#reject`)
+* `#collecting` applies a transforming block to each element (like `Enumerable#collect`)
+* `#uniqing` discards duplicates (like `Enumerable#uniq`)
 
-`selecting` (cf. `select`, or `find_all`) returns each element for which the given block is true
+We say the "...ing" variants are "lazy", because they defer per-element processing until the result is used.  They return Enumerable "result proxy" objects, rather than Arrays, and only perform the actual filtering (or transformation) as the result proxy is enumerated.
 
-    (1..6).selecting { |x| x.even? }        # generates: 2, 4, 6
+Perhaps an example would help.  Consider the following snippet:
 
-`rejecting` (cf. `reject`) returns each element for which the given block is false:
+    >> (1..10).collect { |x| puts "#{x}^2 = #{x*x}"; x*x }.take_while { |x| x < 20 }
+    1^2 = 1
+    2^2 = 4
+    3^2 = 9
+    4^2 = 16
+    5^2 = 25
+    6^2 = 36
+    7^2 = 49
+    8^2 = 64
+    9^2 = 81
+    10^2 = 100
+    => [1, 4, 9, 16]
+    
+Here we use plain old `#collect` to square a bunch of numbers, and then grab the ones less than 20. We can do the same thing using `#collecting`, rather than `#collect`:
 
-    (1..6).rejecting { |x| x.even? }        # generates: 1, 3, 5
+    >> (1..10).collecting { |x| puts "#{x}^2 = #{x*x}"; x*x }.take_while { |x| x < 20 }
+    1^2 = 1
+    2^2 = 4
+    3^2 = 9
+    4^2 = 16
+    5^2 = 25
+    => [1, 4, 9, 16]
 
-`collecting` (cf. `collect`, or `map`) applies a block to each element:
+Same result, but notice how only the first five inputs were ever squared; just enough to find the first result above 20.
 
-    [1,2,3].collecting { |x| x*2 }          # generates: 2, 4, 6
+Lazy pipelines
+--------------
 
-`uniqing` (cf. `uniq`) returns unique elements:
+By combining two or more of the lazy operations provided by EnumerableFu, you can create an efficient "pipeline", e.g.
 
-    [2,1,2,3,2,1].uniqing                   # generates: 2, 1, 3
+    # enumerate all users
+    users = User.to_enum(:find_each)
 
-Unlike the original methods, the "...ing" variants each return an immutable Enumerable object, rather than an Array.  The actual processing is deferred until the result Enumerable is enumerated (e.g. with `each`), and elements are produced "just in time".
+    # where first and last names start with the same letter
+    users = users.selecting { |u| u.first_name[0] == u.last_name[0] }
 
-Mixers
-------
+    # grab their company (weeding out duplicates)
+    companies = users.collecting(&:company).uniqing
 
-`Enumerable.zipping` pulls elements from a number of Enumerables in parallel, yielding each group.
+    # resolve
+    companies.to_a              #=> ["Disney"]
+
+Because each processing step proceeds in parallel, without creation of intermediate collections (Arrays), you can efficiently operate on large (or even infinite) Enumerable collections.
+
+Lazy combination of Enumerables
+-------------------------------
+
+EnumerableFu also provides some interesting ways to combine several Enumerable collections to create a new collection.  Again, these operate "lazily".
+
+`EnumerableFu.zipping` pulls elements from a number of collections in parallel, yielding each group.
 
     array1 = [1,3,6]
     array2 = [2,4,7]
-    Enumerable.zipping(array1, array2)      # generates: [1,2], [3,4], [6,7]
+    EnumerableFu.zipping(array1, array2)    # generates: [1,2], [3,4], [6,7]
 
-`Enumerable.merging` merges multiple Enumerables, preserving sort-order.  The inputs are assumed to be sorted already.
+`EnumerableFu.merging` merges multiple collections, preserving sort-order.  The inputs are assumed to be sorted already.
 
     array1 = [1,4,5]
     array2 = [2,3,6]
-    Enumerable.merging(array1, array2)      # generates: 1, 2, 3, 4, 5, 6
+    EnumerableFu.merging(array1, array2)    # generates: 1, 2, 3, 4, 5, 6
 
-Variant `Enumerable.merging_by` uses a block to determine sort-order.
+Variant `EnumerableFu.merging_by` uses a block to determine sort-order.
 
     array1 = %w(a dd cccc)
     array2 = %w(eee bbbbb)
-    Enumerable.merging_by(array1, array2) { |x| x.length }
+    EnumerableFu.merging_by(array1, array2) { |x| x.length }
                                             # generates: %w(a dd eee cccc bbbbb)

data/lib/enumerable_fu/merging.rb

@@ -57,7 +57,7 @@ module EnumerableFu
 
 end
 
-class << Enumerable
+class << EnumerableFu
   
   def merging(*enumerables)
     EnumerableFu::Merger.new(enumerables)

data/lib/enumerable_fu/version.rb

@@ -1,3 +1,3 @@
 module EnumerableFu
-  VERSION = "0.1.0".freeze
+  VERSION = "0.1.1".freeze
 end

data/lib/enumerable_fu/zipping.rb

@@ -27,7 +27,7 @@ module EnumerableFu
 
 end
 
-class << Enumerable
+class << EnumerableFu
 
   def zipping(*enumerables)
     EnumerableFu::Zipper.new(enumerables)

data/spec/enumerable_fu/merging_spec.rb

@@ -1,6 +1,6 @@
 require "spec_helper"
 
-describe Enumerable, :needs_enumerators => true do
+describe EnumerableFu, :needs_enumerators => true do
 
   describe ".merging" do
 
@@ -8,14 +8,14 @@ describe Enumerable, :needs_enumerators => true do
       @array1 = [1,3,6]
       @array2 = [2,4,7]
       @array3 = [5,8]
-      @merge = Enumerable.merging(@array1, @array2, @array3)
+      @merge = EnumerableFu.merging(@array1, @array2, @array3)
       @merge.to_a.should == [1,2,3,4,5,6,7,8]
     end
 
     it "is lazy" do
       @enum1 = [1,3]
       @enum2 = [2,4].with_time_bomb
-      @merge = Enumerable.merging(@enum1, @enum2)
+      @merge = EnumerableFu.merging(@enum1, @enum2)
       @merge.take(4).should == [1,2,3,4]
     end
 
@@ -26,7 +26,7 @@ describe Enumerable, :needs_enumerators => true do
     it "uses the block to determine order" do
       @array1 = %w(cccc dd a)
       @array2 = %w(eeeee bbb)
-      @merge = Enumerable.merging_by(@array1, @array2) { |s| -s.length }
+      @merge = EnumerableFu.merging_by(@array1, @array2) { |s| -s.length }
       @merge.to_a.should == %w(eeeee cccc bbb dd a)
     end
 

data/spec/enumerable_fu/zipping_spec.rb

@@ -1,6 +1,6 @@
 require "spec_helper"
 
-describe Enumerable, :needs_enumerators => true do
+describe EnumerableFu, :needs_enumerators => true do
 
   describe "#zipping" do
 
@@ -8,12 +8,12 @@ describe Enumerable, :needs_enumerators => true do
       @array1 = [1,3,6]
       @array2 = [2,4,7]
       @array3 = [5,8]
-      @zip = Enumerable.zipping(@array1, @array2, @array3)
+      @zip = EnumerableFu.zipping(@array1, @array2, @array3)
       @zip.to_a.should == [[1,2,5], [3,4,8], [6,7,nil]]
     end
 
     it "is lazy" do
-      @zip = Enumerable.zipping(%w(a b c), [1,2].with_time_bomb)
+      @zip = EnumerableFu.zipping(%w(a b c), [1,2].with_time_bomb)
       @zip.take(2).should == [["a", 1], ["b", 2]]
     end
 

metadata

@@ -2,7 +2,7 @@
 name: enumerable_fu
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors: 
 - Mike Williams
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-04-14 00:00:00 +10:00
+date: 2011-04-24 00:00:00 +10:00
 default_executable: 
 dependencies: []