enumerable-lazy 0.0.1

data/README.mkd

@@ -0,0 +1,209 @@
+enumerable-lazy
+===============
+
+This is a sample implementation of Enumerable#lazy
+(see #4890 - http://redmine.ruby-lang.org/issues/4890 ).
+
+Enumerable#lazy returns an instance of Enumerable::Lazy,
+which is like Enumerator but has 'lazy' version of .map,
+.select, etc.
+
+'lazy' version of map and select never returns an array.
+Instead, they yields the transformed/filtered elements one by one.
+So you can use them for - 
+
+* huge data which cannot be processed at a time, 
+* data stream which you want to process in real-time,
+* or infinit list, which has no end.
+
+Looking form another view, Enumerable#lazy (and its lazy
+version of map and select) provides a way to transform or filter
+
+
+Requirements
+------------
+
+Ruby 1.9.x (for now; it should not be so hard to support 1.8)
+
+Example
+-------
+
+This code prints the first 100 primes which is of the form n^2 + 1.
+
+   require 'prime'
+   INFINITY = 1.0 / 0
+
+   p (1..INFINITY).lazy.map{|n| n**2+1}.
+                        select{|m| m.prime?}.
+                        take(100)
+
+see examples/ for more.
+
+When do I need Enumerable#lazy?
+-------------------------------
+
+### maping/selecting huge files
+
+Suppose you want to print the first 10 words of a text file:
+
+  File.open(ARGV[0]){|f|
+    puts f.lines.flat_map{|l| l.split}.take(10)
+  }
+
+Thanks to flat_map, this task is done by really simple code.  But this example
+has a problem; when the files is extremely large, flat_map reads the entire
+file, where only a few lines are really needed.
+
+Adding '.lazy' resolves this problem:
+
+  require 'enumerable/lazy'
+  
+  File.open(ARGV[0]){|f|
+    puts f.lines.lazy.flat_map{|l| l.split}.take(10)
+    #            ~~~~
+  }
+
+The 'lazy' version of flat_map yields the result one by one, instead of 
+creating the entire array at first.
+
+Enumerable#lazy is also useful when all the lines are important.
+The following code counts the number of words of a (possible big) file.
+
+  File.open(ARGV[0]){|f|
+    p f.lines.lazy.flat_map{|l| l.split}.count
+  }
+
+Without '.lazy', flat_map loads the entire file into memory.
+
+This example prints the length of the longest line of the file.
+With '.lazy', it consumes far less memory than using normal map.
+
+  File.open(ARGV[0]){|f|
+    p f.lines.lazy.map{|l| l.size}.max
+  }
+
+### maping//selecting infinite list
+
+Another fun of lazy evaluation is to manipulate infinit lists.
+With Enumerable#lazy, you can apply map(=transform) or select(=filter) to them.
+
+This is the exmaple shown above. Without '.lazy', map tries to
+create an array with infinit length.
+
+    require 'prime'
+    INFINITY = 1.0 / 0
+
+    p (1..INFINITY)
+      .lazy
+      .map{|n| n**2+1}.
+      select{|m| m.prime?}.
+      take(100)
+
+Another example is finding first ten 'Fridays the 13th'
+with infinit list of dates starts from 1 Jan 2011.
+
+    require 'date'
+    
+    puts (Date.new(2011)..Date.new(9999))
+      .lazy
+      .select{|d| d.day == 13 and d.friday?}
+      .take(10)
+
+This program otherwise written with each and a counter variable:
+
+    require 'date'
+    
+    n = 0
+    (Date.new(2011)..Date.new(9999)).each do |d|
+      if d.day == 13 and d.friday?
+        puts d
+        n += 1
+        exit if n >= 10
+      end
+    end
+
+mapping/selecting infinit lists provide another (and often simpler
+and cleaner) algorithm to solve the same problem.
+
+### maping/selecting for stream
+
+lazy map and lazy select are considered as transformation and
+filterling for streams.
+
+So Enumerable#lazy can be used to transform/filter data stream, like
+data coming from network.
+
+Methods
+-------
+
+Enumerable::Lazy is a subclass of Enumerator. It overrides
+the following methods as 'lazy' version.
+
+* Methods which transform the element:
+  * map(collect)
+  * flat_map(collect_concat)
+  * zip
+* Methods which filters the element:
+  * select(find_all)
+  * grep
+  * take_while
+  * reject
+  * drop
+  * drop_while
+
+These lazy methods returns an instance of Enumerable::Lazy,
+where the 'normal' version returns an Array (and goes into infinite loop).
+It means that calling these methods does not generate any result.
+Actual values are generated when you call the methods like these
+on Enumerable::Lazy.
+
+* take
+* first
+* find(detect)
+
+Example:
+
+  irb> ary = (1..100).to_a
+  irb> _.lazy
+   => #<Enumerable::Lazy: #<Enumerator::Generator:0x000001010f3988>:each>
+  irb> _.map{|n| n*n}
+   => #<Enumerable::Lazy: #<Enumerator::Generator:0x000001010b5b38>:each>
+  irb> _.select{|n| n.to_s[-1] == "9"}
+   => #<Enumerable::Lazy: #<Enumerator::Generator:0x000001010848f8>:each>
+  irb> _.take(3)
+   => [9, 49, 169] 
+
+### Methods not redefined
+
+(FYI) Enumerable::Lazy does not override these methods:
+
+* chunk cycle slice_before each_(cons|entry|slice|with_index|with_object)
+  * They return an Enumerator. In other words, they are already lazy.
+
+* any? include? take detect find_index first
+  * They never cause an infinit loop, because they need only finite number of elements
+
+* inject count all? none? one? max(_by) min(_by) minmax(_by)
+  * They need all elements to define the return value, and they are smart enough not to store all the element on the memory.
+
+* entries group_by partition sort(_by)
+  * Size of their return value is linear to the input size.
+
+* reverse_each
+  * It needs the last element first.
+
+Implementation note
+===================
+
+* Current implementation is not built for speed.
+
+* zip does not need to be lazy if one of the array is finite
+  (because zip terminates execution when an end is found),
+  but it must be lazy for the case all the arrays are infinite. 
+
+Contact
+=======
+
+http://github.com/yhara/enumerable-lazy
+
+http://twitter.com/yhara_en

data/Rakefile

@@ -0,0 +1,2 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks

data/enumerable-lazy.gemspec

@@ -0,0 +1,18 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+
+Gem::Specification.new do |s|
+  s.name        = "enumerable-lazy"
+  s.version     = "0.0.1"
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Yutaka HARA"]
+  s.email       = ["yutaka.hara.gmail.com"]
+  s.homepage    = "https://github.com/yhara/enumerable-lazy"
+  s.summary     = %q{provides `lazy' version of map, select, etc. by `.lazy.map'}
+  s.description = s.summary
+
+  s.files         = `git ls-files`.split("\n")
+  #s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  #s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/examples/13_friday.rb

@@ -0,0 +1,11 @@
+#
+# 13_friday.rb - prints first ten 'Friday the 13th' from 2011
+#
+require_relative '../lib/enumerable/lazy'
+
+require 'date'
+
+puts (Date.new(2011)..Date.new(9999))
+  .lazy
+  .select{|d| d.day == 13 and d.friday?}
+  .first(10)

data/examples/fizzbuzz.rb

@@ -0,0 +1,8 @@
+require_relative '../lib/enumerable/lazy'
+
+puts (1..Float::INFINITY)
+  .lazy
+  .map{|n| if n % 15 == 0 then "FizzBuzz" else n end}
+  .map{|n| if n %  5 == 0 then "Buzz" else n end}
+  .map{|n| if n %  3 == 0 then "Fizz" else n end}
+  .first(100)

data/lib/enumerable/lazy.rb

@@ -0,0 +1,187 @@
+# = Enumerable#lazy example implementation
+#
+# Enumerable#lazy returns an instance of Enumerable::Lazy.
+# You can use it just like as normal Enumerable object,
+# except these methods act as 'lazy':
+#
+#   - map       collect
+#   - select    find_all
+#   - reject
+#   - grep
+#   - drop
+#   - drop_while
+#   - take_while
+#   - flat_map  collect_concat
+#   - zip
+#
+# == Example
+#
+# This code prints the first 100 primes.
+#
+#   require 'prime'
+#   INFINITY = 1.0 / 0
+#   p (1..INFINITY).lazy.select{|m| m.prime?}.take(100)
+#
+# == Acknowledgements
+#
+#   Inspired by https://github.com/antimon2/enumerable_lz
+#   http://jp.rubyist.net/magazine/?0034-Enumerable_lz (ja)
+
+module Enumerable
+  def lazy
+    Lazy.new(self)
+  end
+
+  class Lazy < Enumerator
+    def initialize(obj, &block)
+      super(){|yielder|
+        begin
+          obj.each{|x|
+            if block
+              block.call(yielder, x)
+            else
+              yielder << x
+            end
+          }
+        rescue StopIteration
+        end
+      }
+    end
+
+    def map(&block)
+      Lazy.new(self){|yielder, val|
+        yielder << block.call(val)
+      }
+    end
+    alias collect map
+
+    def select(&block)
+      Lazy.new(self){|yielder, val|
+        if block.call(val)
+          yielder << val
+        end
+      }
+    end
+    alias find_all select
+
+    def reject(&block)
+      Lazy.new(self){|yielder, val|
+        if not block.call(val)
+          yielder << val
+        end
+      }
+    end
+
+    def grep(pattern)
+      Lazy.new(self){|yielder, val|
+        if pattern === val
+          yielder << val
+        end
+      }
+    end
+
+    def drop(n)
+      dropped = 0
+      Lazy.new(self){|yielder, val|
+        if dropped < n
+          dropped += 1
+        else
+          yielder << val
+        end
+      }
+    end
+
+    def drop_while(&block)
+      dropping = true
+      Lazy.new(self){|yielder, val|
+        if dropping
+          if not block.call(val)
+            yielder << val
+            dropping = false
+          end
+        else
+          yielder << val
+        end
+      }
+    end
+    
+    def take(n)
+      taken = 0
+      Lazy.new(self){|yielder, val|
+        if taken < n
+          yielder << val
+          taken += 1
+        else
+          raise StopIteration
+        end
+      }
+    end
+
+    def take_while(&block)
+      Lazy.new(self){|yielder, val|
+        if block.call(val)
+          yielder << val
+        else
+          raise StopIteration
+        end
+      }
+    end
+
+    def flat_map(&block)
+      Lazy.new(self){|yielder, val|
+        ary = block.call(val)
+        # TODO: check ary is an Array
+        ary.each{|x|
+          yielder << x
+        }
+      }
+    end
+    alias collect_concat flat_map
+
+    def zip(*args, &block)
+      enums = [self] + args
+      Lazy.new(self){|yielder, val|
+        ary = enums.map{|e| e.next}
+        if block
+          yielder << block.call(ary)
+        else
+          yielder << ary
+        end
+      }
+    end
+
+    # def chunk
+    # def slice_before
+    #
+    # There methods are already implemented with Enumerator.
+
+  end
+end
+
+# Example
+
+# -- Print the first 100 primes
+#require 'prime'
+#p (1..1.0/0).lazy.select{|m|m.prime?}.first(100)
+
+#p (1..1.0/0).lazy.find{|n| n*n*Math::PI>10000}
+
+# -- Print the first 10 word from a text file
+#File.open("english.txt"){|f|
+#  p f.lines.lazy.flat_map{|line| line.split}.take(10)
+#}
+
+# -- Example of cycle and zip
+#e1 = [1, 2, 3].cycle
+#e2 = [:a, :b].cycle
+#p e1.lazy.zip(e2).take(10)
+
+# -- Example of chunk and take_while
+#p Enumerator.new{|y|
+#  loop do
+#    y << rand(100)
+#  end
+#}.chunk{|n| n.even?}.
+#  lazy.map{|even, ns| ns}.
+#  take_while{|ns| ns.length <= 5}.to_a
+

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: enumerable-lazy
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Yutaka HARA
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-07-03 00:00:00.000000000 +09:00
+default_executable: 
+dependencies: []
+description: provides `lazy' version of map, select, etc. by `.lazy.map'
+email:
+- yutaka.hara.gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.mkd
+- Rakefile
+- enumerable-lazy.gemspec
+- examples/13_friday.rb
+- examples/fizzbuzz.rb
+- lib/enumerable/lazy.rb
+has_rdoc: true
+homepage: https://github.com/yhara/enumerable-lazy
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: provides `lazy' version of map, select, etc. by `.lazy.map'
+test_files: []