enumerable_fu 0.1.0

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,9 @@
+source :rubygems
+
+gemspec
+
+gem "rake"
+gem "rspec", ">= 2"
+
+gem "lazing"
+gem "facets"

data/README.markdown

@@ -0,0 +1,50 @@
+EnumerableFu
+============
+
+"EnumerableFu" extends `Enumerable` with "lazy" versions of various operations, 
+allowing streamed processing of large (or even infinite) collections.
+
+It also provides some interesting ways of combining Enumerables.
+
+Filters
+-------
+
+`selecting` (cf. `select`, or `find_all`) returns each element for which the given block is true
+
+    (1..6).selecting { |x| x.even? }        # generates: 2, 4, 6
+
+`rejecting` (cf. `reject`) returns each element for which the given block is false:
+
+    (1..6).rejecting { |x| x.even? }        # generates: 1, 3, 5
+
+`collecting` (cf. `collect`, or `map`) applies a block to each element:
+
+    [1,2,3].collecting { |x| x*2 }          # generates: 2, 4, 6
+
+`uniqing` (cf. `uniq`) returns unique elements:
+
+    [2,1,2,3,2,1].uniqing                   # generates: 2, 1, 3
+
+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".
+
+Mixers
+------
+
+`Enumerable.zipping` pulls elements from a number of Enumerables in parallel, yielding each group.
+
+    array1 = [1,3,6]
+    array2 = [2,4,7]
+    Enumerable.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.
+
+    array1 = [1,4,5]
+    array2 = [2,3,6]
+    Enumerable.merging(array1, array2)      # generates: 1, 2, 3, 4, 5, 6
+
+Variant `Enumerable.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 }
+                                            # generates: %w(a dd eee cccc bbbbb)

data/Rakefile

@@ -0,0 +1,13 @@
+require "rake"
+
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new do |t|
+  t.pattern = 'spec/**/*_spec.rb'
+  t.rspec_opts = ["--colour", "--format", "nested"]
+end
+
+task "default" => "spec"

data/benchmarks/pipeline_bench.rb

@@ -0,0 +1,71 @@
+require 'benchmark'
+
+$: << File.expand_path("../../lib", __FILE__)
+
+RUBY19 = RUBY_VERSION =~ /^1\.9/
+
+if RUBY19
+  require "lazing"
+  module Enumerable
+    alias :lazing_select :selecting
+    alias :lazing_collect :collecting
+  end
+end
+
+require "enumerable_fu"
+
+require 'facets'
+
+array = (1..100000).to_a
+
+# Test scenario:
+#  - filter out even numbers
+#  - square them
+#  - grab the first thousand
+
+printf "%-30s", "IMPLEMENTATION"
+printf "%12s", "take(10)"
+printf "%12s", "take(100)"
+printf "%12s", "take(1000)"
+printf "%12s", "to_a"
+puts ""
+
+def measure(&block)
+  begin
+    printf "%12.5f", Benchmark.realtime(&block)
+  rescue
+    printf "%12s", "n/a"
+  end
+end
+
+def benchmark(description, control_result = nil)
+  result = nil
+  printf "%-30s", description
+  measure { yield.take(10).to_a }
+  measure { yield.take(100).to_a }
+  measure { result = yield.take(1000).to_a }
+  measure { yield.to_a }
+  puts ""
+  unless control_result.nil? || result == control_result
+    raise "unexpected result from '#{description}'"
+  end
+  result
+end
+
+@control = benchmark "conventional" do
+  array.select { |x| x.even? }.collect { |x| x*x }
+end
+
+benchmark "enumerable_fu", @control do 
+  array.selecting { |x| x.even? }.collecting { |x| x*x }
+end
+
+if RUBY19
+  benchmark "lazing", @control do
+    array.lazing_select { |x| x.even? }.lazing_collect { |x| x*x }
+  end
+end
+
+benchmark "facets Enumerable#defer", @control do
+  array.defer.select { |x| x.even? }.collect { |x| x*x }
+end

data/enumerable_fu.gemspec

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "enumerable_fu/version"
+
+Gem::Specification.new do |s|
+
+  s.name          = "enumerable_fu"
+  s.version       = EnumerableFu::VERSION.dup
+  s.platform      = Gem::Platform::RUBY
+  s.authors       = ["Mike Williams"]
+  s.email         = "mdub@dogbiscuit.org"
+  s.homepage      = "http://github.com/mdub/enumerable_fu"
+
+  s.summary       = %{Lazy extensions to Enumerable}
+  s.description   = %{EnumerableFu extends Enumerable with "lazy" versions of various operations, allowing streamed processing of large (or even infinite) collections.}
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.require_paths = ["lib"]
+
+end

data/lib/enumerable_fu/filtering.rb

@@ -0,0 +1,68 @@
+require 'set'
+
+module EnumerableFu
+
+  class Filter
+
+    include Enumerable
+
+    def initialize(&generator)
+      @generator = generator
+    end
+
+    def each
+      return to_enum unless block_given?
+      yielder = proc { |x| yield x }
+      @generator.call(yielder)
+    end
+
+  end
+
+end
+
+module Enumerable
+  
+  def collecting
+    EnumerableFu::Filter.new do |output|
+      each do |element|
+        output.call yield(element)
+      end
+    end
+  end
+  
+  def selecting
+    EnumerableFu::Filter.new do |output|
+      each do |element|
+        output.call(element) if yield(element)
+      end
+    end
+  end
+  
+  def rejecting
+    EnumerableFu::Filter.new do |output|
+      each do |element|
+        output.call(element) unless yield(element)
+      end
+    end
+  end
+  
+  def uniqing
+    EnumerableFu::Filter.new do |output|
+      seen = Set.new
+      each do |element|
+        output.call(element) if seen.add?(element)
+      end
+    end
+  end
+
+  def uniqing_by
+    EnumerableFu::Filter.new do |output|
+      seen = Set.new
+      each do |element|
+        output.call(element) if seen.add?(yield element)
+      end
+    end
+  end
+  
+end
+

data/lib/enumerable_fu/merging.rb

@@ -0,0 +1,70 @@
+module EnumerableFu
+
+  class Merger
+
+    include Enumerable
+
+    def initialize(enumerables, &transformer)
+      @enumerables = enumerables
+      @transformer = transformer
+    end
+
+    def each(&block)
+      return to_enum unless block_given?
+      Generator.new(@enumerables.map(&:to_enum), @transformer).each(&block)
+    end
+
+    class Generator
+
+      def initialize(enumerators, transformer)
+        @enumerators = enumerators
+        @transformer = transformer
+      end
+
+      def each
+        while true do
+          discard_empty_enumerators
+          break if @enumerators.empty?
+          yield next_enumerator.next
+        end
+      end
+
+      private
+
+      def discard_empty_enumerators
+        @enumerators.delete_if do |e|
+          begin
+            e.peek
+            false
+          rescue StopIteration
+            true
+          end
+        end
+      end
+
+      def next_enumerator
+        @enumerators.min_by { |enumerator| transform(enumerator.peek) }
+      end
+
+      def transform(item)
+        return item unless @transformer
+        @transformer.call(item)
+      end
+
+    end
+
+  end
+
+end
+
+class << Enumerable
+  
+  def merging(*enumerables)
+    EnumerableFu::Merger.new(enumerables)
+  end
+
+  def merging_by(*enumerables, &block)
+    EnumerableFu::Merger.new(enumerables, &block)
+  end
+  
+end

data/lib/enumerable_fu/mixing.rb

@@ -0,0 +1,2 @@
+require 'enumerable_fu/merging'
+require 'enumerable_fu/zipping'

data/lib/enumerable_fu/version.rb

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

data/lib/enumerable_fu/zipping.rb

@@ -0,0 +1,36 @@
+module EnumerableFu
+
+  class Zipper
+
+    include Enumerable
+
+    def initialize(enumerables)
+      @enumerables = enumerables
+    end
+
+    def each
+      enumerators = @enumerables.map(&:to_enum)
+      while true
+        chunk = enumerators.map do |enumerator|
+          begin 
+            enumerator.next
+          rescue StopIteration
+            nil
+          end
+        end
+        break if chunk.all?(&:nil?)
+        yield chunk
+      end
+    end
+
+  end
+
+end
+
+class << Enumerable
+
+  def zipping(*enumerables)
+    EnumerableFu::Zipper.new(enumerables)
+  end
+
+end

data/lib/enumerable_fu.rb

@@ -0,0 +1,2 @@
+require 'enumerable_fu/filtering'
+require 'enumerable_fu/mixing'

data/spec/enumerable_fu/filtering_spec.rb

@@ -0,0 +1,62 @@
+require "spec_helper"
+
+describe Enumerable do
+
+  describe "#collecting" do
+
+    it "transforms items" do
+      [1,2,3].collecting { |x| x * 2 }.to_a.should == [2,4,6]
+    end
+
+    it "is lazy" do
+      [1,2,3].with_time_bomb.collecting { |x| x * 2 }.first.should == 2
+    end
+
+  end
+
+  describe "#selecting" do
+
+    it "excludes items that don't pass the predicate" do
+      (1..6).selecting { |x| x.even? }.to_a.should == [2,4,6]
+    end
+
+    it "is lazy" do
+      (1..6).with_time_bomb.selecting { |x| x.even? }.first == 2
+    end
+
+  end
+
+  describe "#rejecting" do
+
+    it "excludes items that do pass the predicate" do
+      (1..6).rejecting { |x| x.even? }.to_a.should == [1,3,5]
+    end
+
+    it "is lazy" do
+      (1..6).with_time_bomb.rejecting { |x| x.even? }.first == 1
+    end
+
+  end
+
+  describe "#uniqing" do
+
+    it "removes duplicates" do
+      [1,3,2,4,3,5,4,6].uniqing.to_a.should == [1,3,2,4,5,6]
+    end
+
+    it "is lazy" do
+      [1,2,3].with_time_bomb.uniqing.first.should == 1
+    end
+
+  end
+
+  describe "#uniqing_by" do
+
+    it "uses the block to derive identity" do
+      @array = %w(A1 A2 B1 A3 C1 B2 C2)
+      @array.uniqing_by { |s| s[0,1] }.to_a.should == %w(A1 B1 C1)
+    end
+
+  end
+
+end

data/spec/enumerable_fu/merging_spec.rb

@@ -0,0 +1,35 @@
+require "spec_helper"
+
+describe Enumerable, :needs_enumerators => true do
+
+  describe ".merging" do
+
+    it "merges multiple Enumerators" do
+      @array1 = [1,3,6]
+      @array2 = [2,4,7]
+      @array3 = [5,8]
+      @merge = Enumerable.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.take(4).should == [1,2,3,4]
+    end
+
+  end
+
+  describe ".merging_by" 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.to_a.should == %w(eeeee cccc bbb dd a)
+    end
+
+  end
+
+end

data/spec/enumerable_fu/zipping_spec.rb

@@ -0,0 +1,22 @@
+require "spec_helper"
+
+describe Enumerable, :needs_enumerators => true do
+
+  describe "#zipping" do
+
+    it "zips together multiple Enumerables" do
+      @array1 = [1,3,6]
+      @array2 = [2,4,7]
+      @array3 = [5,8]
+      @zip = Enumerable.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.take(2).should == [["a", 1], ["b", 2]]
+    end
+
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,37 @@
+require "rubygems"
+
+require 'rspec'
+
+RSpec.configure do |config|
+  unless defined?(::Enumerator)
+    config.filter_run_excluding :needs_enumerators => true
+  end
+end
+
+class Boom < StandardError; end
+
+class WithTimeBomb
+
+  include Enumerable
+
+  def initialize(source)
+    @source = source
+  end
+
+  def each(&block)
+    @source.each(&block)
+    raise Boom
+  end
+
+end
+
+module Enumerable
+  
+  # extend an Enumerable to throw an exception after last element
+  def with_time_bomb
+    WithTimeBomb.new(self)
+  end
+  
+end
+
+require "enumerable_fu"

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification 
+name: enumerable_fu
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Mike Williams
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-04-14 00:00:00 +10:00
+default_executable: 
+dependencies: []
+
+description: EnumerableFu extends Enumerable with "lazy" versions of various operations, allowing streamed processing of large (or even infinite) collections.
+email: mdub@dogbiscuit.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- README.markdown
+- Rakefile
+- benchmarks/pipeline_bench.rb
+- enumerable_fu.gemspec
+- lib/enumerable_fu.rb
+- lib/enumerable_fu/filtering.rb
+- lib/enumerable_fu/merging.rb
+- lib/enumerable_fu/mixing.rb
+- lib/enumerable_fu/version.rb
+- lib/enumerable_fu/zipping.rb
+- spec/enumerable_fu/filtering_spec.rb
+- spec/enumerable_fu/merging_spec.rb
+- spec/enumerable_fu/zipping_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/mdub/enumerable_fu
+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: Lazy extensions to Enumerable
+test_files: 
+- spec/enumerable_fu/filtering_spec.rb
+- spec/enumerable_fu/merging_spec.rb
+- spec/enumerable_fu/zipping_spec.rb
+- spec/spec_helper.rb