combinatorics 0.3.0 → 0.4.4

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

@@ -0,0 +1,5 @@
+require 'combinatorics/derange/mixin'
+
+class Array
+  include Combinatorics::Derange::Mixin
+end

data/lib/combinatorics/derange/extensions.rb

@@ -0,0 +1 @@
+require 'combinatorics/derange/extensions/array'

data/lib/combinatorics/derange/mixin.rb

@@ -0,0 +1,47 @@
+module Combinatorics
+  module Derange
+    #
+    # @author duper <super@manson.vistech.net>
+    #
+    # @since 0.4.0
+    #
+    module Mixin
+      #
+      # Calculate all derangements for an Enumerable object.
+      #
+      # @yield [derangement] 
+      #   If a block is given, it will be passed an Array representing
+      #   an individual derangement from the full calculation.
+      #
+      # @yieldparam [Array] derangement
+      #   One of the calculated derangements.
+      #
+      # @return [Enumerator] 
+      #   If no block is given, an Enumerator of all derangements will be
+      #   returned.
+      #
+      # @example Produce the derangements of a three-element Array
+      #   [1, 2, 3].derange.to_a
+      #   # => [[2, 3, 1], [3, 1, 2]]
+      #
+      # @see http://en.wikipedia.org/wiki/Derangements
+      # @see http://mathworld.wolfram.com/Derangement.html
+      #
+      def derange
+        return enum_for(:derange) unless block_given?
+
+        if size <= 1
+          yield []
+        else
+          elements = self.to_a
+
+          elements.permutation do |x|
+            unless elements.each_with_index.any? { |e,i| e == x[i] }
+              yield x
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/combinatorics/derange.rb

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

data/lib/combinatorics/enumerator.rb

@@ -6,5 +6,7 @@ module Combinatorics
                  ::Enumerator
                elsif defined?(::Enumerable::Enumerator) # 1.8.7
                  ::Enumerable::Enumerator
+               else
+                 raise("unable to find the Enumerator class")
                end
 end

data/lib/combinatorics/extensions/math.rb

@@ -0,0 +1,176 @@
+#
+# @author duper <super@manson.vistech.net>
+#
+module Math
+  #
+  # Mathematical summation (invokes a block for k = 1 until ++k = n).
+  #
+  # @param [Range] r
+  #   Range containing the number of times to yield.
+  #
+  # @yield [i]
+  #   The given block is expected to return an Integer, which is added to the
+  #   total sum.
+  #
+  # @yieldparam [Integer] i
+  #   An element from `r`.
+  #
+  # @return [Integer]
+  #   Total sum after yielding for each element in `r`.
+  #
+  # @raise [TypeError]
+  #   `r` must be a {Range}.
+  #
+  # @example
+  #   sigma(1..4) { |i| i }
+  #   # => 10
+  #
+  # @note
+  #   "chalkboard" notation for summation is the capital Greek letter Sigma.
+  #
+  # @see http://en.wikipedia.org/wiki/Summation
+  #
+  # @since 0.4.0
+  #
+  def Math.sigma(r)
+    unless r.kind_of?(Range)
+      raise(TypeError,"r must be a Range")
+    end
+
+    k = 0
+
+    if block_given?
+      r.each { |n| k += yield n }
+    else
+      r.each { |n| k += n }
+    end
+
+    k
+  end
+
+  #
+  # CamelCase alias for sigma (defined above)
+  #
+  # @see Math.sigma
+  #
+  # @since 0.4.0
+  #
+  def Math.Sigma(r)
+    Math.sigma(r)
+  end
+
+  #
+  # Pi notation for iterative product computations.
+  #
+  # @param [Range<Integer>] r
+  #   Inclusive range of Integers.
+  #
+  # @yield [i]
+  #   The given block will be passed elements of `r`. The return value from
+  #   the block will be combined with the product.
+  #
+  # @yield [Integer] i
+  #   An element from `r`.
+  #
+  # @return [Integer]
+  #   The total product after iterating over each element in `r`.
+  #
+  # @raise [TypeError]
+  #   `r` must be a Range.
+  #
+  # @example
+  #   Math.pi(1..4)
+  #   # => 24
+  #
+  # @see http://en.wikipedia.org/wiki/Pi_notation#Capital_Pi_notation
+  #
+  # @since 0.4.0
+  #
+  def Math.pi(r)
+    unless r.kind_of?(Range)
+      raise(TypeError,"r must be a Range")
+    end
+
+    k = 1
+
+    if block_given?
+      r.each { |n| k *= yield n }
+    else
+      r.each { |n| k *= n }
+    end
+
+    k
+  end
+
+  #
+  # CamelCase alias for pi (defined above)
+  #
+  # @see Math.pi
+  #
+  # @since 0.4.0
+  #
+  def Math.Pi(r)
+    Math.pi(r)
+  end
+  
+  #
+  # Subfactorial function for calculation of derangement cardinalities.
+  #
+  # @param [Fixnum] n
+  #   The length of sequence.
+  #
+  # @raise [RangeError]
+  #   `n` must be non-negative.
+  #
+  # @return [Integer]
+  #   Cardinality of derangements set.
+  #
+  # @example
+  #   subfactorial([1, 2, 3].size)
+  #   # => 2
+  #
+  # @note The notation used in academia for subfactorial notation is "!n"
+  #
+  # @see http://mathworld.wolfram.com/Subfactorial.html
+  # @see Derange.cardinality
+  #
+  # @since 0.4.0
+  #
+  def Math.subfactorial(n)
+    if    n >= 1 then ((Math.factorial(n) + 1) / Math::E).floor
+    elsif n == 0 then 1
+    else
+      raise(RangeError,"n must be non-negative")
+    end
+  end
+
+  # 
+  # Apply the well-known factorial function to the given Integer.
+  #
+  # @param [Fixnum] x
+  #   Positive integer to apply algebraic factorial function to.
+  #
+  # @return [Integer]
+  #   Solution to factorial function as a whole number.
+  #
+  # @raise [RangeError]
+  #   The given number must be non-negative.
+  #
+  # @example
+  #   factorial(4)
+  #   # => 24
+  #
+  # @note The factorial of zero equals one!
+  #
+  # @see http://en.wikipedia.org/wiki/Factorial
+  #
+  # @since 0.4.0
+  #
+  def Math.factorial(x=1)
+    if    x >= 1  then pi(1..x)
+    elsif x == 0  then 1
+    else
+      raise(RangeError,"x must be non-negative")
+    end
+  end
+end

data/lib/combinatorics/extensions/range.rb

@@ -53,7 +53,7 @@ class Range
 
     self.first.upto(other.first) do |start|
       self.last.upto(other.last) do |stop|
-        yield (start..stop)
+        yield start..stop
       end
     end
   end
@@ -89,7 +89,7 @@ class Range
 
     self.first.downto(other.first) do |start|
       self.last.downto(other.last) do |stop|
-        yield (start..stop)
+        yield start..stop
       end
     end
   end

data/lib/combinatorics/generator.rb

@@ -1,10 +1,13 @@
-require 'generator'
+require 'enumerator'
+require 'generator' if RUBY_VERSION < '1.9'
 
 module Combinatorics
   # auto-detects the `Generator` class.
-  Generator = if defined?(::Enumerator::Generator) # 1.9
-                ::Enumerator::Generator
-              elsif defined?(::Generator) # 1.8.7
+  Generator = if defined?(::Generator) # 1.8.7
                 ::Generator
+              elsif defined?(::Enumerator::Generator) # >= 1.9.1
+                ::Enumerator::Generator
+              else
+                raise(NameError,"unable to find the Generator class")
               end
 end

data/lib/combinatorics/list_comprehension.rb

@@ -1,3 +1,5 @@
+require 'combinatorics/enumerator'
+
 class Array
 
   #
@@ -48,7 +50,10 @@ class Array
     end
 
     enums = self.map do |value|
-      if value.kind_of?(Enumerable)
+      case value
+      when Combinatorics::Enumerator
+        value
+      when Enumerable
         value.enum_for
       else
         [value].enum_for

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/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/extensions.rb

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

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/permute.rb

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

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/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/version.rb

@@ -0,0 +1,4 @@
+module Combinatorics
+  # Combinatorics module revision number
+  VERSION = '0.4.4'
+end

data/lib/combinatorics.rb

@@ -1,3 +1,11 @@
+require 'combinatorics/cartesian_product'
+require 'combinatorics/choose'
+require 'combinatorics/derange'
 require 'combinatorics/extensions'
 require 'combinatorics/list_comprehension'
 require 'combinatorics/power_set'
+require 'combinatorics/permute'
+require 'combinatorics/version'
+
+# @todo inversions (permutation mutations)
+# @todo set families (approximate power set subsets)

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 
+      expect(subject.cardinality(1, 1)).to eq(1)
+    end
+
+    it "should return 2 for cardinality(1, 2)" do
+      expect(subject.cardinality(1, 2)).to eq(2)
+    end
+
+    it "should return 2 for cardinality(2, 1)" do
+      expect(subject.cardinality(2, 1)).to eq(2)
+    end
+
+    it "should return 4 for cardinality(2, 2)" do
+      expect(subject.cardinality(2, 2)).to eq(4)
+    end
+
+    it "should return 3 for cardinality(3, 1)" do
+      expect(subject.cardinality(3, 1)).to eq(3)
+    end
+
+    it "should return 3 for cardinality(1, 3)" do
+      expect(subject.cardinality(1, 3)).to eq(3)
+    end
+
+    it "should return 6 for cardinality(2, 3)" do
+      expect(subject.cardinality(2, 3)).to eq(6)
+    end
+
+    it "should return 6 for cardinality(3, 2)" do
+      expect(subject.cardinality(3, 2)).to eq(6)
+    end
+    
+    it "should return 9 for cardinality(3, 3)" do
+      expect(subject.cardinality(3, 3)).to eq(9)
+    end
+
+    it "should raise RangeError if c1 is negative" do
+      expect { subject.cardinality(-1, 1) }.to raise_error(RangeError)
+    end
+
+    it "should raise RangeError if c2 is negative" do
+      expect { subject.cardinality(1, -1) }.to raise_error(RangeError)
+    end
+
+    it "should raise RangeError if c1 is zero" do
+      expect { subject.cardinality(0, 1) }.to raise_error(RangeError)
+    end
+
+    it "should raise RangeError if c2 is zero" do
+      expect { subject.cardinality(1, 0) }.to raise_error(RangeError)
+    end
+  end
+
+  it "should wrap cardinality with CartesianProduct.X" do
+    should respond_to(:X)
+  end
+end