b-lazy 0.0.4 → 0.1.0

data/lib/b-lazy.rb

@@ -5,6 +5,8 @@
 # few convenient methods that can simplify looping constructs.
 class Enumerator
 
+  # If the Enumerator is empty, then return false.  Otherwise,
+  # return true.
   def has_next?
     peek
     true
@@ -12,6 +14,9 @@ class Enumerator
     false
   end
   
+  
+  # If the Enumerator is empty, then return true.  Otherwise,
+  # return false.
   def empty?
     peek
     false
@@ -20,6 +25,8 @@ class Enumerator
   end
 
 
+  # This is similar to the #take method, except that it
+  # actually moves the Enumerator ahead n after each call.
   def grab(n)
     retval = []
     begin
@@ -46,10 +53,14 @@ module Enumerable
   end
   
   
-  # This is similar to the tap method.  It allows you
-  # to examine each item as it passes through the
-  # Enumeration pipeline.  It is also handy if you want
-  # to modify an element's state as it passes through.
+  # This is similar to the tap method, but it operates on
+  # each element of the Enumerator as it passes through.
+  # This is useful for many things, such as:
+  #
+  # 1. Examining the state of the element
+  # 2. Logging
+  # 3. Modifying the element's state
+  # 4. Recording interim values
   def touch(&blk)
     Enumerator.new do |out|
       self.each do |x|
@@ -60,6 +71,8 @@ module Enumerable
   end
   
   
+  # This is the same as the #select method except that it
+  # operates lazily.
   def lselect(&blk)
     Enumerator.new do |out|
       self.each do |i|
@@ -68,6 +81,9 @@ module Enumerable
     end
   end
   
+  
+  # This is the same as the #reject method except that it
+  # operates lazily.
   def lreject(&blk)
     Enumerator.new do |out|
       self.each do |i|
@@ -75,12 +91,9 @@ module Enumerable
       end
     end
   end
-  
-  
 
 
-
-  # Start as soon as the condition becomes true
+  # Begins yielding values as soon as the condition becomes true.
   def start_when(&blk)
     Enumerator.new do |out|
       s = self.ensure_enum
@@ -149,6 +162,8 @@ module Enumerable
   end
 
 
+  # Skips the specified number of elements.  Note that this
+  # method does not complain if the Enumerator is empty.
   def skip(n = 1)
     Enumerator.new do |out|
       s = self.ensure_enum
@@ -163,6 +178,12 @@ module Enumerable
   end
 
 
+  # In Java-speak, we would say this method operates on
+  # Enumerable<Enumerable<?>> .  It concatenates the values
+  # of each nested Enumerable and produces one Enumerable that
+  # contains all of the values.  For example:
+  #
+  # [[1, 2, 3], [4, 5]].cons.to_a -> [1, 2, 3, 4, 5]
   def cons()
     Enumerator.new do |out|
       s  = self.ensure_enum
@@ -176,12 +197,11 @@ module Enumerable
   end
   
   
-  # NOTE: This method should only be called on Enumerators
-  #       of Enumerators!  This is similar to cons, but it
-  #       instead takes the first item from each enumerator,
-  #       then the second item, etc.  This can be handy when
-  #       you have a finite number of enumerators, but each
-  #       one may hold an infinite number of items
+  # This is similar to cons, but it
+  # instead takes the first item from each enumerator,
+  # then the second item, etc.  This can be handy when
+  # you have a finite number of enumerators, but each
+  # one may hold an infinite number of items
   def weave()
     Enumerator.new do |out|
       enums = self.ensure_enum.lmap(&:ensure_enum)
@@ -195,6 +215,10 @@ module Enumerable
   end
 
 
+  # If you have an infinite number of Enumerators, and each of these
+  # have an infinite number of elements, then you should iterate over
+  # them using Cantor's diagonalization technique.  As t -> infinity,
+  # you will examine all elements from all Enumerators.
   def diagonalize()
     Enumerator.new do |out|
       s = self.ensure_enum
@@ -210,7 +234,27 @@ module Enumerable
   end
   
   
-  
+  # Randomizes the order in which the elements are yielded.  Since
+  # this is done in a lazy fashion, it is not as random as actually
+  # shuffling the entire list.
+  def randomly(n = 8)
+    Enumerator.new do |out|
+      s = self.ensure_enum
+      pool = s.grab(n)
+      while s.has_next?
+        index = rand(n)
+        out.yield pool[index]
+        pool[index] = s.next
+      end
+      pool.sort_by{rand}.each{|x| out.yield x}
+    end
+  end
+
+
+  # This is similar to Array's transpose method, but it can operate
+  # on any Enumerable.  Additionally, it stops as soon as the first
+  # Enumerable is exhausted (rather than setting the missing values
+  # equal to nil).
   def ltranspose()
     Enumerator.new do |out|
       catch(:nothing_to_do) do
@@ -227,15 +271,39 @@ module Enumerable
   end
 
 
-  def groups_of(n)
+
+  # Keeps repeating the same elements indefinitely.
+  def cycle()
     Enumerator.new do |out|
-      s = self.ensure_enum
-      while s.has_next?
-        out.yield s.grab(n)
+      values = self.touch{|x| out.yield x}.to_a
+      unless values.empty?
+        loop do
+          values.each{|x| out.yield x}
+        end
+      end
+    end
+  end
+  
+  
+  # This is a lazy version of the #product method.  It returns
+  # all combinations of values from the provided Enumerators.
+  #
+  # Ex: [[1, 2], [3, 4]].lproduct.to_a -> [[1, 3], [1, 4], [2, 3], [2, 4]]
+  #def lproduct()
+  #  
+  #end
+  
+  
+  # Repeats the same sequence of elements n times.
+  def repeat(n)
+    n = n.to_i
+    Enumerator.new do |out|
+      if n >= 1
+        values = self.touch{|x| out.yield x}.to_a
+        (n - 1).times{ values.each{|x| out.yield x} }
       end
     end
   end
-
 
 
   # When #to_enum is called on an Enumerator, it creates a copy

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
+  - 1
   - 0
-  - 4
-  version: 0.0.4
+  version: 0.1.0
 platform: ruby
 authors: 
 - Brian Lauber