reductions 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c4dcd97fa68d0d05cac8b5620fd5d534b0467708
+  data.tar.gz: 2b05ad9ba6f3068e4d1523ae908f1c76d0ff6670
+SHA512:
+  metadata.gz: 92a36ebb66b117705f7b5059398b5b20d0cc38dcc377805a197fe6328805c63780d122860dac17c01bceece4c4317ae8beac8ed91ba31bfa0a277618704dd8f7
+  data.tar.gz: af67b82c462547faf25e71feacb48b229909677717fb72c8f2c3cd271f1d9b620ab04140259a59d3e8fd89d07d045d46aee300a93ec16ef9e29832904d623088

data/README.md

@@ -0,0 +1,70 @@
+Reductions
+==========
+
+Reductions is an addition to Ruby's Enumerable module that returns
+an array containing all of the intermediate values that would be
+generated in a call to Enumerable#reduce.
+
+Installation
+============
+
+`gem install reductions`
+
+Usage
+=====
+
+    require 'reductions'
+
+    (5..10).reductions(:+)           # => [5, 11, 18, 26, 35, 45]
+    (5..10).reductions{|a,b| a + b}  # => [5, 11, 18, 26, 35, 45]
+
+    # (5..10).reduce(:+)  would result in 45
+
+**If you have monkey-patched Enumerable#reduce** and need to
+ensure #reductions works according to your patched #reduce, pass
+`use_reduce: true` to reductions:
+
+    (5..10).reductions(:+,use_reduce: true)
+    (5..10).reductions(use_reduce: true){|a,b| a + b}
+
+Using this flag increases the required execution time. See Benchmarking
+section for performance difference.
+
+
+Why a gem for this?
+-------------------
+
+You _could_ just provide a block to Enumerable#reduce that does the same
+thing:
+
+    (5..10).reduce([]){|acc,n| acc += acc.last ? [acc.last + n] : [n] }
+
+However, a gem is preferable for two key reasons:
+
+*  It allows for more compact, more understandable code. Compare the above with
+   `(5..10).reductions(:+)`.
+*  There are significant performance problems with the "provide a block to reduce"
+   approach once you get into reductions with tens of thousands of elements. See
+   "naïve reductions" in the Benchmarking section.
+
+
+Benchmarking
+------------
+The case being benchmarked here is `(1..100000).reductions{|a,b| a + b}`
+
+                                   user     system      total        real
+    reduce                     0.010000   0.000000   0.010000 (  0.017606)
+    reductions                 0.040000   0.000000   0.040000 (  0.036335)
+    reductions use_reduce      0.050000   0.000000   0.050000 (  0.051783)
+    naïve reductions          15.190000   0.530000  15.720000 ( 15.699648)
+
+* `reduce` is a plain #reduce, included here to give a reference point for performance.
+* `reductions` is the reduction using the exact case shown above.
+    Notice the full reduction --which returns an array
+    with 100,000 entries-- took only **~2** times as long as a plain reduce!
+* `reductions use_reduce` is the reduction with the `use_reduce` flag set to
+    true. This reduction uses #reduce in its implementation.
+* `naïve reductions` is the reduction using reduce as shown in the "Why a gem for this?"
+    section. The large number of incremental Array allocations makes
+    it _really_ slow, in this case taking more than 400 times as long
+    as the `reductions` version.

data/benchmarks/run_benchmarks.rb

@@ -0,0 +1,39 @@
+#!/usr/bin/env ruby
+
+require 'benchmark'
+require 'reductions'
+
+# For comparison purposes, monkey-patch in a naive implementation. Ignore all
+# the setup and just look at the two return statements to understand what this
+# is doing.
+module Enumerable
+  def naive_reductions(init=nil,sym=nil,&block)
+    if sym == nil && block == nil && (init.kind_of?(Symbol) || init.kind_of?(String))
+      sym = init
+      init = nil
+    end
+
+    raise LocalJumpError.new("no block given") if !sym && !block
+
+    iv = init ? [init] : []
+    if block
+      return self.reduce(iv){|acc,n| acc += acc.last ? [yield(acc.last,n)] : [n]}
+    else
+      return self.reduce(iv){|acc,n| acc += acc.last ? [acc.last.method(sym).call(n)] : [n]}
+    end
+  end
+end
+
+
+# And now the benchmarking:
+
+br = (1..100000)
+ba = br.to_a
+
+Benchmark.bmbm(29) do |b|
+  b.report('100K reduce') {ba.reduce{|a,n| a + n}}
+  b.report('100K reductions direct access') {ba.reductions{|a,n| a + n}}
+  b.report('100K reductions each-style') {br.reductions{|a,n| a + n}}
+  b.report('100K reductions use_reduce') {br.reductions(use_reduce: true){|a,n| a + n}}
+  b.report('100K naive reductions') {br.naive_reductions{|a,n| a + n}}
+end

data/lib/reductions.rb

@@ -0,0 +1,162 @@
+
+module Enumerable
+
+  # Returns an Array containing all the intermediate values collected when
+  # performing +Enumerable#reduce+. It accepts the same parameters and block
+  # as +Enumerable#reduce+, with the addition of the named parameter +use_reduce+
+  #
+  # *WARNING:* If you have monkey-patched +Enumerable#reduce+, you should pass 
+  # +use\_reduce: true+ in the parameter list.
+  #
+  # @param [Object] init an initial value for the reduction. Just like the one for reduce....
+  #
+  # @param [Symbol] sym symbol representing a binary operation. Just like the one for reduce....
+  #
+  # @param [Bool] use_reduce: (named parameter) uses Enumerable#reduce in the
+  #               implementation if true. Defaults to false for faster execution.
+  #
+  # @param [Block] block a block to use instead of a symbol. Just like the one for reduce....
+  #
+  # @return [Array] the array of intermediate values
+  #
+  # @example
+  #   # These attempt to follow the examples used for Enumerable#reduce
+  #
+  #   # Sum some numbers
+  #   (5..10).reductions(:+)                              # => [5, 11, 18, 26, 35, 45]
+  #   # Multiply some numbers
+  #   (5..10).reductions(1, :*)                           # => [1, 5, 30, 210, 1680, 15120, 151200]
+  #   # Same using a block
+  #   (5..10).reductions(1) { |product, n| product * n }  # => [1, 5, 30, 210, 1680, 15120, 151200]
+  #   # Force the use of Enumerable#reduce
+  #   (5..10).reductions(1, :*, use_reduce: true)         # => [1, 5, 30, 210, 1680, 15120, 151200]
+  #
+  def reductions(init=nil,sym=nil,use_reduce: false,&block)
+
+    if sym == nil && block == nil && (init.kind_of?(Symbol) || init.kind_of?(String))
+      sym = init
+      init = nil
+    end
+
+    raise LocalJumpError.new("no block given") if !sym && !block
+
+    sz = get_reductions_prealloc_size
+
+    acc = init ? Array.new(sz + 1) : Array.new(sz)
+
+    # Use the slower version if requested
+    return reductions2(init: init,sym: sym,acc: acc,&block) if use_reduce
+
+    # Direct access reductions with no initial value are faster than
+    # each style reductions with no initial value because the latter
+    # are forced to perform a boolean test at each iteration
+    direct = self.respond_to?(:[])
+
+    # presence or absence of init changes how we treat index
+    # We use +yield+ rather than +block.call+ wherever possible since yield
+    # executes with less overhead.
+    if block && !init
+      if direct
+        acc[0] = self[0]
+        sz -= 1
+        sz.times do |j|
+          acc[j+1] = yield(acc[j],self[j+1])
+        end
+      else
+        self.each_with_index do |k,j|
+          if j == 0
+            acc[0] = k
+          else
+            acc[j] = yield(acc[j-1],k)
+          end
+        end
+      end
+
+    elsif block && init
+      acc[0] = init
+      self.each_with_index do |k,j|
+        acc[j+1] = yield(acc[j],k)
+      end
+
+    elsif !block && !init
+      if direct
+        acc[0] = self[0]
+        sz -= 1
+        sz.times do |j|
+          acc[j+1] = acc[j].method(sym).call(self[j+1])
+        end
+      else
+        self.each_with_index do |k,j|
+          if j == 0
+            acc[0] = k
+          else
+            acc[j] = acc[j-1].method(sym).call(k)
+          end
+        end
+      end
+
+    elsif !block && init
+      acc[0] = init
+      self.each_with_index do |k,j|
+        acc[j+1] = acc[j].method(sym).call(k)
+      end
+    end
+
+    return acc
+  end
+
+
+
+  private
+  # Returns the allocation size we need for the results.
+  def get_reductions_prealloc_size
+    if self.respond_to?(:size)
+      return self.size
+    else
+      # Works for any Enumerable, but generally slower than #size
+      return self.count
+    end
+  end
+
+
+  private
+  # Variant of reductions that uses Enumerable#reduce directly in its
+  # implementation, while still getting the advantages of result array
+  # pre-allocation. Parameter checking and array allocation occurs in
+  # #reductions, which then optionally calls this function.
+  def reductions2(init: nil,sym: nil, acc: [],&block)
+
+    acc[0] = init if init
+    idx = init ? 1 : 0
+    iv = [idx,acc]
+
+    if block
+      return self.reduce(iv) do |acc,n|
+        idx = acc[0]
+        v = acc[1]
+        if idx == 0
+          v[0] = n
+        else
+          v[idx] = yield(v[idx - 1],n)
+        end
+        acc[0] = idx + 1
+        acc
+      end.last
+    else
+      return self.reduce(iv) do |acc,n|
+        idx = acc[0]
+        v = acc[1]
+        if idx == 0
+          v[0] = n
+        else
+          v[idx] = v[idx - 1].method(sym).call(n)
+        end
+        acc[0] = idx + 1
+        acc
+      end.last
+    end
+  end
+
+end
+
+(1..5).reductions(:+,use_reduce: true)

data/tests/unit_tests.rb

@@ -0,0 +1,72 @@
+#!/usr/bin/env ruby
+
+require 'minitest/autorun'
+require 'reductions'
+
+class TestReductions < Minitest::Test
+
+  def test_simple_block_reduction_esr
+    assert_equal [1,3,6,10,15], (1..5).reductions{|a,b| a + b}
+  end
+
+  def test_simple_block_reduction_dar
+    assert_equal [1,3,6,10,15], (1..5).to_a.reductions{|a,b| a + b}
+  end
+
+  def test_simple_block_reduction2
+    assert_equal [1,3,6,10,15], (1..5).reductions(use_reduce: true){|a,b| a + b}
+  end
+
+  def test_simple_sym_reduction_esr
+    assert_equal [1,3,6,10,15], (1..5).reductions(:+)
+  end
+
+  def test_simple_sym_reduction_dar
+    assert_equal [1,3,6,10,15], (1..5).to_a.reductions(:+)
+  end
+
+  def test_simple_sym_reduction2
+    assert_equal [1,3,6,10,15], (1..5).reductions(:+,use_reduce: true)
+  end
+
+  def test_simple_string_reduction_esr
+    assert_equal [1,3,6,10,15], (1..5).reductions('+')
+  end
+
+  def test_simple_string_reduction_dar
+    assert_equal [1,3,6,10,15], (1..5).to_a.reductions('+')
+  end
+
+  def test_simple_string_reduction2
+    assert_equal [1,3,6,10,15], (1..5).reductions('+',use_reduce: true)
+  end
+
+  def test_init_block_reduction_esr
+    assert_equal [2,3,5,8,12,17], (1..5).reductions(2){|a,b| a + b}
+  end
+
+  def test_init_block_reduction_dar
+    assert_equal [2,3,5,8,12,17], (1..5).to_a.reductions(2){|a,b| a + b}
+  end
+
+  def test_init_block_reduction2
+    assert_equal [2,3,5,8,12,17], (1..5).reductions(2,use_reduce: true){|a,b| a + b}
+  end
+
+  def test_init_sym_reduction_esr
+    assert_equal [2,3,5,8,12,17], (1..5).reductions(2,:+)
+  end
+
+  def test_init_sym_reduction_dar
+    assert_equal [2,3,5,8,12,17], (1..5).to_a.reductions(2,:+)
+  end
+
+  def test_init_sym_reduction2
+    assert_equal [2,3,5,8,12,17], (1..5).reductions(2,:+,use_reduce: true)
+  end
+
+  def test_raises_no_block
+    assert_raises(LocalJumpError){ (1..5).reductions }
+  end
+
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: reductions
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Penn Taylor
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-03-13 00:00:00.000000000 Z
+dependencies: []
+description: |2
+      Reductions is an addition to Enumerable that returns
+      an array containing all of the intermediate values that would
+      be generated in a call to Enumerable#reduce.
+
+      (5..10).reductions(:+)    # => [5, 11, 18, 26, 35, 45]
+email: rpenn3@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- benchmarks/run_benchmarks.rb
+- lib/reductions.rb
+- tests/unit_tests.rb
+homepage: https://github.com/penntaylor/reductions
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.6
+signing_key: 
+specification_version: 4
+summary: Adds reductions capability to Enumerable
+test_files: []
+has_rdoc: