combinatorics 0.3.1 → 0.4.1

data/lib/combinatorics/generator.rb

@@ -1,4 +1,9 @@
-require 'generator'
+require 'enumerator'
+
+begin
+  require 'generator' # 1.8.7
+rescue LoadError
+end
 
 module Combinatorics
   # auto-detects the `Generator` class.
@@ -6,5 +11,7 @@ module Combinatorics
                 ::Enumerator::Generator
               elsif defined?(::Generator) # 1.8.7
                 ::Generator
+              else
+                raise("unable to find the Generator class")
               end
 end

data/lib/combinatorics/permute.rb

@@ -0,0 +1,3 @@
+require 'combinatorics/permute/cardinality'
+require 'combinatorics/permute/mixin'
+require 'combinatorics/permute/extensions'

data/lib/combinatorics/permute/cardinality.rb

@@ -0,0 +1,98 @@
+require 'combinatorics/extensions/math'
+
+module Combinatorics
+  #
+  # @author duper <super@manson.vistech.net>
+  #
+  # @since 0.4.0
+  #
+  module Permute
+    #
+    # Mathematically determine the number of elements in a r-permutations
+    # set.
+    # 
+    # @param [Fixnum] n
+    #   The number of elements in the input set.
+    #
+    # @param [Fixnum] r
+    #   Cardinality of permuted subsets.
+    #
+    # @raise [RangeError]
+    #   `n` must be non-negative.
+    #
+    # @raise [RangeError]
+    #   `r` must be non-negative.
+    #
+    # @raise [RangeError]
+    #   `r` must be less than or equal to `n`.
+    #
+    # @return [Fixnum]
+    #   The product of the first `r` factors of `n`.
+    #
+    # @example Calculate total 4-permutations for a set whose cardinality is 6
+    #   cardinality(6, 4)
+    #   # => 360
+    #
+    # @see http://en.wikipedia.org/wiki/Permutations
+    #
+    # @note
+    #   This function is well-known within fields of academic inquiry such as 
+    #   discrete mathematics and set theory. It is represented in "chalkboard"
+    #   notation by the letter "P."
+    #
+    def self.cardinality(n,r=nil) 
+      raise(RangeError,"n must be non-negative") if n < 0
+
+      case r
+      when 0   then 0
+      when nil then Math.factorial(n)
+      else
+        raise(RangeError,"r must be non-negative") if r < 0
+        raise(RangeError,"r must be less than or equal to n") if r > n
+
+        Math.factorial(n) / Math.factorial(n - r)
+      end
+    end
+
+    #
+    # @see cardinality
+    #
+    # @note In the study of set theory, permutations are often referenced by
+    #       the name of an associated algorithm called "n-choose-r."
+    #
+    def self.N(n,r=nil);  cardinality(n,r); end
+    def self.NR(n,r=nil); cardinality(n,r); end
+    def self.R(n,r=nil);  cardinality(n,r); end
+
+    #
+    # Compute cardinality of all r-permutations for a set with cardinality c
+    #
+    # @param [Fixnum] c
+    #   Input set cardinality.
+    #
+    # @return [Array]
+    #   Elements are cardinalities for each subset `1 .. c`.
+    #
+    # @raise [RangeError]
+    #   `c` must be non-negative.
+    #
+    # @example cardinality_all(4)
+    #   # => [4, 3, 10, 1]
+    #
+    # @note sum of elements will equal `factorial(c)`
+    #
+    # @see http://en.wikipedia.org/wiki/Permutations
+    #
+    def self.cardinality_all(n,c=(1..n))
+      if n < 0
+        raise(RangeError,"n must be non-negative")
+      end
+
+      c.map { |r| cardinality(n,r) }
+    end
+
+    def self.N_all(c);  cardinality_all(c); end
+    def self.NR_all(c); cardinality_all(c); end
+    def self.R_all(c);  cardinality_all(c); end
+  end
+end

data/lib/combinatorics/permute/extensions.rb

@@ -0,0 +1,2 @@
+require 'combinatorics/permute/extensions/array'
+require 'combinatorics/permute/extensions/set'

data/lib/combinatorics/permute/extensions/array.rb

@@ -0,0 +1,7 @@
+require 'combinatorics/permute/mixin'
+
+class Array
+
+  include Combinatorics::Permute::Mixin
+
+end

data/lib/combinatorics/permute/extensions/set.rb

@@ -0,0 +1,9 @@
+require 'combinatorics/permute/mixin'
+
+require 'set'
+
+class Set
+
+  include Combinatorics::Permute::Mixin
+
+end

data/lib/combinatorics/permute/mixin.rb

@@ -0,0 +1,48 @@
+module Combinatorics
+  module Permute
+    #
+    # @author duper <super@manson.vistech.net>
+    #
+    # @since 0.4.0
+    #
+    module Mixin
+      #
+      # Enumerate distinct r-permutations for a particular sequence of
+      # elements.
+      #
+      # @param [Fixnum] r
+      #   Length of permuted subsets to return.
+      #
+      # @yield [permutation]
+      #   If a block is given, it will be passed each k-permutation.
+      #
+      # @yieldparam [Array] permutation
+      #   A k-permutation of the elements from `self`.
+      #
+      # @return [Enumerator]
+      #   If no block is given, an Enumerator of the k-permutations of
+      #   elements from `self` is returned.
+      #
+      # @raise [TypeError]
+      #   `self` must be Enumerable.
+      #
+      # @example
+      #   [1, 2, 3].permute(2).to_a
+      #   # => [[1, 2], [1, 3],
+      #   #     [2, 1], [2, 3],
+      #   #     [3, 1], [3, 2]]
+      #
+      # @see http://rubydoc.info/stdlib/core/Array#permutation-instance_method
+      #
+      def permute(r,&block)
+        return enum_for(:permute,r) unless block
+
+        unless kind_of?(Enumerable)
+          raise(TypeError,"#{inspect} must be Enumerable")
+        end
+
+        self.to_a.permutation(r,&block)
+      end
+    end
+  end
+end

data/lib/combinatorics/power_set.rb

@@ -1,2 +1,3 @@
 require 'combinatorics/power_set/mixin'
 require 'combinatorics/power_set/extensions'
+require 'combinatorics/power_set/cardinality'

data/lib/combinatorics/power_set/cardinality.rb

@@ -0,0 +1,36 @@
+require 'combinatorics/extensions/math'
+
+module Combinatorics
+  module PowerSet
+    #
+    # Get number of elements in power set from number of elements in input
+    # set.
+    #
+    # @param [Fixnum] n
+    #   Number of elements input set.
+    #
+    # @return [Fixnum]
+    #   Number of elements in power set.
+    #
+    # @see Math::factorial
+    # @see http://en.wikipedia.org/wiki/Cardinality
+    #
+    # @note
+    #   Cardinality of power set on an empty set equals `factorial(0)`
+    #   equals 1.
+    #
+    def self.cardinality(n)
+      Math.factorial(n)
+    end
+
+    # 
+    # Wrapper function for power set cardinality method defined above
+    #
+    # @note The letter `P' stands for the power set function in the context of
+    #       statements regarding discrete mathematics.
+    #
+    def self.P(n)
+      cardinality(n)
+    end
+  end
+end

data/lib/combinatorics/power_set/mixin.rb

@@ -1,5 +1,8 @@
 module Combinatorics
   module PowerSet
+    #
+    # @author postmodern <postmodern.mod3@gmail.com>
+    #
     module Mixin
       #
       # Calculates the power-set of an Enumerable object.
@@ -11,40 +14,34 @@ module Combinatorics
       # @yieldparam [Array] subset
       #   A sub-set from the power-set.
       #
-      # @return [Array]
+      # @return [Enumerator]
       #   The power set.
       #
-      # @example Power-set of an Array.
-      #   [1,2,3].powerset
-      #   # => [[], [3], [2], [2, 3], [1], [1, 3], [1, 2], [1, 2, 3]]
-      #
       # @example Power-set on a Set of strings.
-      #   Set['abc', 'xyz', '123'].powerset
-      #   # => [#<Set: {}>, #<Set: {"123"}>, #<Set: {"xyz"}>,
-      #         #<Set: {"abc"}>, #<Set: {"xyz", "123"}>,
-      #         #<Set: {"abc", "123"}>, #<Set: {"abc", "xyz"}>,
+      #   Set['abc', 'xyz', '123'].powerset.to_a
+      #   # => [#<Set: {}>,
+      #         #<Set: {"123"}>,
+      #         #<Set: {"xyz"}>,
+      #         #<Set: {"abc"}>,
+      #         #<Set: {"xyz", "123"}>,
+      #         #<Set: {"abc", "123"}>,
+      #         #<Set: {"abc", "xyz"}>,
       #         #<Set: {"abc", "xyz", "123"}>]
       #
-      # @see http://johncarrino.net/blog/2006/08/11/powerset-in-ruby/
-      #
       def powerset
-        inject([self.class.new]) do |power_set,element|
-          sub_set = []
+        return enum_for(:powerset) unless block_given?
 
-          power_set.each do |previous_set|
-            new_set = previous_set + [element]
-            yield new_set if block_given?
+        elements = self.to_a
+        elements.uniq!
 
-            sub_set << previous_set
-            sub_set << new_set
+        0.upto(elements.length) do |k|
+          elements.combination(k) do |subset|
+            yield Set.new(subset)
           end
-
-          sub_set
         end
       end
 
-      alias cartesian_product powerset
-
+      alias power_set powerset
     end
   end
 end

data/lib/combinatorics/version.rb

@@ -1,4 +1,4 @@
 module Combinatorics
-  # combinatorics version
-  VERSION = '0.3.1'
+  # Combinatorics module revision number
+  VERSION = '0.4.1'
 end

data/spec/cartesian_product/array_spec.rb

@@ -0,0 +1,10 @@
+require 'spec_helper'
+require 'cartesian_product/mixin_examples'
+
+require 'combinatorics/cartesian_product/extensions/array'
+
+describe Array do
+  subject { Array }
+
+  it_should_behave_like "CartesianProduct::Mixin"
+end

data/spec/cartesian_product/cardinality_spec.rb

@@ -0,0 +1,64 @@
+require 'spec_helper'
+require 'combinatorics/cartesian_product'
+
+describe CartesianProduct do
+  subject { CartesianProduct } 
+
+  describe "cardinality" do
+    it "should return 1 for cardinality(1, 1)" do 
+      subject.cardinality(1, 1).should == 1
+    end
+
+    it "should return 2 for cardinality(1, 2)" do
+      subject.cardinality(1, 2).should == 2
+    end
+
+    it "should return 2 for cardinality(2, 1)" do
+      subject.cardinality(2, 1).should == 2
+    end
+
+    it "should return 4 for cardinality(2, 2)" do
+      subject.cardinality(2, 2).should == 4
+    end
+
+    it "should return 3 for cardinality(3, 1)" do
+      subject.cardinality(3, 1).should == 3
+    end
+
+    it "should return 3 for cardinality(1, 3)" do
+      subject.cardinality(1, 3).should == 3
+    end
+
+    it "should return 6 for cardinality(2, 3)" do
+      subject.cardinality(2, 3).should == 6
+    end
+
+    it "should return 6 for cardinality(3, 2)" do
+      subject.cardinality(3, 2).should == 6
+    end
+    
+    it "should return 9 for cardinality(3, 3)" do
+      subject.cardinality(3, 3).should == 9
+    end
+
+    it "should raise RangeError if c1 is negative" do
+      lambda { subject.cardinality(-1, 1) }.should raise_error(RangeError)
+    end
+
+    it "should raise RangeError if c2 is negative" do
+      lambda { subject.cardinality(1, -1) }.should raise_error(RangeError)
+    end
+
+    it "should raise RangeError if c1 is zero" do
+      lambda { subject.cardinality(0, 1) }.should raise_error(RangeError)
+    end
+
+    it "should raise RangeError if c2 is zero" do
+      lambda { subject.cardinality(1, 0) }.should raise_error(RangeError)
+    end
+  end
+
+  it "should wrap cardinality with CartesianProduct.X" do
+    should respond_to(:X)
+  end
+end

data/spec/cartesian_product/mixin_examples.rb

@@ -0,0 +1,98 @@
+require 'spec_helper'
+
+require 'combinatorics/cartesian_product/mixin'
+
+shared_examples_for "CartesianProduct::Mixin" do
+  it "the cartprod of any two Set's should return an Enumerator" do
+    set     = subject[1]
+    results = set.cartprod(set)
+
+    results.should be_kind_of(Enumerator)
+  end
+
+  it "the cartprod of two empty Set's should return an empty Set" do
+    set     = subject[]
+    results = set.cartprod([]).to_a
+    
+    results.should be_empty
+  end
+
+  it "the cartprod of a single empty set should return an empty Set" do
+    set     = subject[1,2]
+    results = set.cartprod([2,3],[]).to_a
+    
+    results.should be_empty
+  end
+
+  it "the cartprod of another empty set should also return an empty Set" do
+    set     = subject[]
+    results = set.cartprod([1]).to_a
+    
+    results.should be_empty
+  end
+
+  it "the cartprod of [1] and [1] should be [[1, 1]]" do
+    set     = subject[1]
+    results = set.cartprod([1]).to_a
+    
+    results.should == [[1, 1]]
+  end
+
+  it "the cartprod of [1, 2] and [3] should be [[1, 3], [2, 3]]" do
+    set     = subject[1, 2]
+    results = set.cartprod([3]).to_a
+    
+    results.should =~ [[1, 3], [2, 3]]
+  end
+
+  it "the cartprod of [1, 2] and [3, 4] should be [[1, 3], [1, 4], [2, 3], [2, 4]]" do
+    set     = subject[1, 2]
+    results = set.cartprod([3, 4]).to_a
+    
+    results.should =~ [
+      [1, 3], [1, 4],
+      [2, 3], [2, 4]
+    ]
+  end
+
+  it "the cartprod of ['a'].cartprod(['b', 'c', 'd']) should be [['a', 'b'], ['a', 'c'], ['a', 'd']]" do
+    set1    = subject['a']
+    set2    = subject['b', 'c', 'd']
+    results = set1.cartprod(set2).to_a
+    
+    results.should =~ [['a', 'b'], ['a', 'c'], ['a', 'd']]
+  end
+
+  it "the cartprod of [0, 1] and [[2, 3], [4, 5]] should be [[0, 2, 4], [1, 2, 4], [0, 3, 4], [1, 3, 4], [0, 2, 5], [1, 2, 5], [0, 3, 5], [1, 3, 5]]" do
+    set1    = subject[0, 1]
+    set2    = subject[2, 3]
+    set3    = subject[4, 5]
+    results = set1.cartprod(set2, set3).to_a
+    
+    results.should =~ [
+      [0, 2, 4], [0, 2, 5], [0, 3, 4], [0, 3, 5],
+      [1, 2, 4], [1, 2, 5], [1, 3, 4], [1, 3, 5],
+    ]
+  end
+
+  it "should take an optional block argument" do
+    set     = subject[1]
+    results = []
+
+    set.cartprod(set) { |result| results << result }
+
+    results.should == [[1, 1]]
+  end
+
+  it "should alias cartprod to cartesian_product" do
+    aset = subject[1]
+
+    aset.should respond_to(:cartesian_product)
+  end
+
+  it "should alias cartprod to cartesian" do
+    aset = subject[1]
+
+    aset.should respond_to(:cartesian)
+  end
+end