combinatorics 0.3.1 → 0.4.1

data/lib/combinatorics/choose.rb

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

data/lib/combinatorics/choose/cardinality.rb

@@ -0,0 +1,99 @@
+require 'combinatorics/extensions/math'
+
+module Combinatorics
+  #
+  # @author duper <super@manson.vistech.net>
+  #
+  # @since 0.4.0
+  #
+  module Choose
+    #
+    # Compute the number of elements in a subset of given size
+    #
+    # @param [Fixnum] n
+    #   The number of elements in the input set
+    #
+    # @param [Fixnum] r
+    #   Cardinality of subsets to choose
+    #
+    # @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 binomial coefficient for "n-choose-r"
+    #
+    # @example
+    #   cardinality(6, 4)
+    #   # => 15
+    #
+    # @see http://en.wikipedia.org/wiki/Binomial_coefficient
+    #
+    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
+        Math.factorial(n) / (Math.factorial(r) * Math.factorial(n - r))
+      end
+    end
+
+    # 
+    # Wrapper for combination cardinality method defined above. The letter `C'
+    # is "chalkboard" notation for subset cardinality.
+    #
+    # @note
+    #   This method's naming convention reflects well-known notation used
+    #   within fields of academic inquiry such as discrete mathematics and
+    #   set theory. It represents a function returning an integer value
+    #   for the cardinality of a k-combination (i.e. binomial coefficient.)
+    #
+    # @see Choose.cardinality
+    #
+    def self.C(n,r=nil)
+      cardinality(n,r)
+    end
+
+    #
+    # @param [Integer] n
+    #   The total number of choices.
+    #
+    # @param [Enumerable] c
+    #   The set of `r` values to choose from `n`.
+    #
+    # @return [Array]
+    #   Elements are cardinalities for each subset "1" through "c".
+    #
+    # @raise [RangeError]
+    #   `n` must be non-negative.
+    #
+    # @example
+    #   cardinality_all(4)
+    #   # => [4, 6, 4, 1]
+    #
+    # @example
+    #   cardinality_all(10, 5..10)
+    #   # => [252, 210, 120, 45, 10, 1]
+    #
+    # @note
+    #   Sum of elements will equal Math.factorial(c)
+    #
+    # @see cardinality
+    # @see http://en.wikipedia.org/wiki/Combinations
+    # 
+    def self.cardinality_all(n,c=(1..n))
+      if n < 0
+        raise(RangeError,"c must be non-negative")
+      end
+
+      c.map { |r| cardinality(n,r) }
+    end
+  end
+end

data/lib/combinatorics/choose/extensions.rb

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

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

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

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

@@ -0,0 +1,6 @@
+require 'set'
+require 'combinatorics/choose/mixin'
+
+class Set
+  include Combinatorics::Choose::Mixin
+end

data/lib/combinatorics/choose/mixin.rb

@@ -0,0 +1,53 @@
+require 'set'
+
+module Combinatorics
+  module Choose
+    #
+    # @author duper <super@manson.vistech.net>
+    #
+    # @since 0.4.0
+    #
+    module Mixin
+      #
+      # Get combinations with a specified number of elements from an input
+      # set.
+      #
+      # @param [Fixnum] k
+      #   Cardinality of chosen subsets
+      #
+      # @yield [combo]
+      #   The given block will be passed each combination.
+      #
+      # @yieldparam [Array] combo
+      #   A k-sized combination of elements from the set.
+      #
+      # @raise [TypeError]
+      #   `self` must be Enumerable.
+      #
+      # @return [Enumerator]
+      #   If no block is given, an Enumerator of the k-sized combinations
+      #   within the set will be returned.
+      #
+      # @example
+      #   [1, 2, 3].choose(2).to_a 
+      #   # => [#<Set: {1, 2}>, #<Set: {1, 3}>, #<Set: {2, 3}>]
+      #
+      # @see http://rubydoc.info/stdlib/core/Array#combination-instance_method
+      #
+      def choose(k,&block)
+        return enum_for(:choose,k) unless block
+
+        unless kind_of?(Enumerable)
+          raise(TypeError,"#{inspect} must be Enumerable")
+        end
+
+        elements = self.to_a
+        elements.uniq!
+
+        elements.combination(k) do |subset|
+          yield Set.new(subset)
+        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/derange/cardinality.rb

@@ -0,0 +1,23 @@
+require 'combinatorics/extensions/math'
+
+module Combinatorics
+  module Derange
+    #
+    # Compute the number of derangements for a data structure of given size
+    #
+    # @see Math.subfactorial
+    #
+    def self.cardinality(n)
+      Math.subfactorial(n)
+    end
+
+    #
+    # Wrapper for derangement cardinality method defined above
+    #
+    # @note The letter `D' is academic representation for derangements
+    #
+    def self.D(n)
+      cardinality(n)
+    end
+  end
+end

data/lib/combinatorics/derange/extensions.rb

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

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/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/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,177 @@
+#
+# @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