combinatorics 0.3.0 → 0.4.4

data/Rakefile

@@ -1,36 +1,16 @@
 require 'rubygems'
-require 'rake'
 
-begin
-  gem 'jeweler', '~> 1.4.0'
-  require 'jeweler'
-
-  Jeweler::Tasks.new do |gem|
-    gem.name = 'combinatorics'
-    gem.summary = %Q{Bringing (more) Combinatorics to Ruby}
-    gem.description = %Q{A collection of modules and methods for performing Combinatoric calculations.}
-    gem.email = 'postmodern.mod3@gmail.com'
-    gem.homepage = 'http://github.com/postmodern/combinatorics'
-    gem.authors = ['Postmodern']
-    gem.add_development_dependency 'rspec', '~> 2.0.0'
-    gem.add_development_dependency 'yard', '~> 0.6.0'
-    gem.add_development_dependency 'jeweler', '~> 1.4.0'
-  end
-  Jeweler::GemcutterTasks.new
-rescue LoadError
-  puts 'Jeweler (or a dependency) not available. Install it with: gem install jeweler'
-end
+require 'rubygems/tasks'
+Gem::Tasks.new
 
 require 'rspec/core/rake_task'
 RSpec::Core::RakeTask.new
+task :test => :spec
 task :default => :spec
 
-begin
-  require 'yard'
+require 'yard'
+YARD::Rake::YardocTask.new
 
-  YARD::Rake::YardocTask.new
-rescue LoadError
-  task :yard do
-    abort 'YARD is not available. In order to run yard, you must: gem install yard'
-  end
+task :benchmark do
+  Dir.glob('benchmarks/*.rb') { |script| ruby(script) }
 end

data/benchmarks/cartesian_product.rb

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+
+root_dir = File.expand_path(File.join(File.dirname(__FILE__),'..'))
+lib_dir = File.join(root_dir,'lib')
+$LOAD_PATH << lib_dir unless $LOAD_PATH.include?(lib_dir)
+
+require 'benchmark'
+require 'combinatorics/cartesian_product'
+
+Benchmark.bm(13) do |b|
+  [100, 200, 400, 800].each do |i|
+    n = (1..i).to_a
+
+    b.report("{#{i}} x {#{i}}") do
+      n.cartesian_product(n).to_a
+    end
+  end
+end

data/benchmarks/choose.rb

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+
+root_dir = File.expand_path(File.join(File.dirname(__FILE__),'..'))
+lib_dir = File.join(root_dir,'lib')
+$LOAD_PATH << lib_dir unless $LOAD_PATH.include?(lib_dir)
+
+require 'benchmark'
+require 'combinatorics/choose'
+
+Benchmark.bm do |b|
+  n     = 20
+  array = (1..n).to_a
+
+  (1..n).each do |i|
+    b.report("n=#{n} k=#{i}") do
+      array.choose(i) { |s| }
+    end
+  end
+end

data/benchmarks/derange.rb

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+
+root_dir = File.expand_path(File.join(File.dirname(__FILE__),'..'))
+lib_dir = File.join(root_dir,'lib')
+$LOAD_PATH << lib_dir unless $LOAD_PATH.include?(lib_dir)
+
+require 'benchmark'
+require 'combinatorics/derange'
+
+Benchmark.bm do |b|
+  (1..10).each do |n|
+    array = (1..n).to_a
+
+    b.report("n=#{n}") do
+      array.derange { |s| }
+    end
+  end
+end

data/benchmarks/list_comprehension.rb

@@ -1,5 +1,3 @@
-#!/usr/bin/env ruby
-
 root_dir = File.expand_path(File.join(File.dirname(__FILE__),'..'))
 lib_dir = File.join(root_dir,'lib')
 $LOAD_PATH << lib_dir unless $LOAD_PATH.include?(lib_dir)
@@ -7,6 +5,24 @@ $LOAD_PATH << lib_dir unless $LOAD_PATH.include?(lib_dir)
 require 'benchmark'
 require 'combinatorics/list_comprehension'
 
-list = [(1..200)] * 3
+Benchmark.bm(12) do |b|
+  singleton_list = ([1] * 500)
+  single_enum_list = [1..100, 1]
+  depth_list = [1..100]
+
+  b.report('singleton:') do
+    singleton_list.comprehension.each { |list| list.last }
+  end
+
+  b.report('single-enum:') do
+    single_enum_list.comprehension.each { |list| list.last }
+  end
+
+  (1..3).each do |n|
+    deep_list = (depth_list * n)
 
-puts Benchmark.measure { list.comprehension.each { |list| } }
+    b.report("depth #{n}:") do
+      deep_list.comprehension.each { |list| list.last }
+    end
+  end
+end

data/benchmarks/permute.rb

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+
+root_dir = File.expand_path(File.join(File.dirname(__FILE__),'..'))
+lib_dir = File.join(root_dir,'lib')
+$LOAD_PATH << lib_dir unless $LOAD_PATH.include?(lib_dir)
+
+require 'benchmark'
+require 'combinatorics/permute'
+
+Benchmark.bm do |b|
+  array = (1..10).to_a
+
+  (1..10).each do |n|
+    b.report("r=#{n}") do
+      array.permute(n) { |s| }
+    end
+  end
+end

data/benchmarks/power_set.rb

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+
+root_dir = File.expand_path(File.join(File.dirname(__FILE__),'..'))
+lib_dir = File.join(root_dir,'lib')
+$LOAD_PATH << lib_dir unless $LOAD_PATH.include?(lib_dir)
+
+require 'benchmark'
+require 'combinatorics/power_set'
+
+Benchmark.bm do |b|
+  (10..20).each do |n|
+    array = (1..n).to_a
+
+    b.report("n=#{n}") do
+      array.power_set { |s| }
+    end
+  end
+end

data/combinatorics.gemspec

@@ -1,90 +1,61 @@
-# Generated by jeweler
-# DO NOT EDIT THIS FILE DIRECTLY
-# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
-# -*- encoding: utf-8 -*-
+# encoding: utf-8
 
-Gem::Specification.new do |s|
-  s.name = %q{combinatorics}
-  s.version = "0.3.0"
+require 'yaml'
 
-  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.authors = ["Postmodern"]
-  s.date = %q{2010-10-17}
-  s.description = %q{A collection of modules and methods for performing Combinatoric calculations.}
-  s.email = %q{postmodern.mod3@gmail.com}
-  s.extra_rdoc_files = [
-    "ChangeLog.md",
-     "LICENSE.txt",
-     "README.md"
-  ]
-  s.files = [
-    ".document",
-     ".gitignore",
-     ".rspec",
-     ".yardopts",
-     "ChangeLog.md",
-     "LICENSE.txt",
-     "README.md",
-     "Rakefile",
-     "VERSION",
-     "benchmarks/list_comprehension.rb",
-     "combinatorics.gemspec",
-     "lib/combinatorics.rb",
-     "lib/combinatorics/enumerator.rb",
-     "lib/combinatorics/extensions.rb",
-     "lib/combinatorics/extensions/range.rb",
-     "lib/combinatorics/generator.rb",
-     "lib/combinatorics/list_comprehension.rb",
-     "lib/combinatorics/power_set.rb",
-     "lib/combinatorics/power_set/extensions.rb",
-     "lib/combinatorics/power_set/extensions/array.rb",
-     "lib/combinatorics/power_set/extensions/set.rb",
-     "lib/combinatorics/power_set/mixin.rb",
-     "spec/.rspec",
-     "spec/combinatorics_spec.rb",
-     "spec/enumerator_spec.rb",
-     "spec/extensions/range_spec.rb",
-     "spec/generator_spec.rb",
-     "spec/list_comprehension_spec.rb",
-     "spec/power_set/array_spec.rb",
-     "spec/power_set/mixin_examples.rb",
-     "spec/power_set/set_spec.rb",
-     "spec/spec_helper.rb"
-  ]
-  s.homepage = %q{http://github.com/postmodern/combinatorics}
-  s.rdoc_options = ["--charset=UTF-8"]
-  s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.7}
-  s.summary = %q{Bringing (more) Combinatorics to Ruby}
-  s.test_files = [
-    "spec/enumerator_spec.rb",
-     "spec/combinatorics_spec.rb",
-     "spec/list_comprehension_spec.rb",
-     "spec/generator_spec.rb",
-     "spec/extensions/range_spec.rb",
-     "spec/spec_helper.rb",
-     "spec/power_set/set_spec.rb",
-     "spec/power_set/array_spec.rb",
-     "spec/power_set/mixin_examples.rb"
-  ]
+Gem::Specification.new do |gem|
+  gemspec = YAML.load_file('gemspec.yml')
 
-  if s.respond_to? :specification_version then
-    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
-    s.specification_version = 3
+  gem.name    = gemspec.fetch('name')
+  gem.version = gemspec.fetch('version') do
+                  lib_dir = File.join(File.dirname(__FILE__),'lib')
+                  $LOAD_PATH << lib_dir unless $LOAD_PATH.include?(lib_dir)
 
-    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_development_dependency(%q<rspec>, ["~> 2.0.0"])
-      s.add_development_dependency(%q<yard>, ["~> 0.6.0"])
-      s.add_development_dependency(%q<jeweler>, ["~> 1.4.0"])
-    else
-      s.add_dependency(%q<rspec>, ["~> 2.0.0"])
-      s.add_dependency(%q<yard>, ["~> 0.6.0"])
-      s.add_dependency(%q<jeweler>, ["~> 1.4.0"])
+                  require 'combinatorics/version'
+                  Combinatorics::VERSION
+                end
+
+  gem.summary     = gemspec['summary']
+  gem.description = gemspec['description']
+  gem.licenses    = Array(gemspec['license'])
+  gem.authors     = Array(gemspec['authors'])
+  gem.email       = gemspec['email']
+  gem.homepage    = gemspec['homepage']
+  gem.metadata    = gemspec['metadata'] if gemspec['metadata']
+
+  glob = lambda { |patterns| gem.files & Dir[*patterns] }
+
+  gem.files = `git ls-files`.split($/)
+  gem.files = glob[gemspec['files']] if gemspec['files']
+
+  gem.executables = gemspec.fetch('executables') do
+    glob['bin/*'].map { |path| File.basename(path) }
+  end
+  gem.default_executable = gem.executables.first if Gem::VERSION < '1.7.'
+
+  gem.extensions       = glob[gemspec['extensions'] || 'ext/**/extconf.rb']
+  gem.test_files       = glob[gemspec['test_files'] || '{test/{**/}*_test.rb']
+  gem.extra_rdoc_files = glob[gemspec['extra_doc_files'] || '*.{txt,md}']
+
+  gem.require_paths = Array(gemspec.fetch('require_paths') {
+    %w[ext lib].select { |dir| File.directory?(dir) }
+  })
+
+  gem.requirements              = gemspec['requirements']
+  gem.required_ruby_version     = gemspec['required_ruby_version']
+  gem.required_rubygems_version = gemspec['required_rubygems_version']
+  gem.post_install_message      = gemspec['post_install_message']
+
+  split = lambda { |string| string.split(/,\s*/) }
+
+  if gemspec['dependencies']
+    gemspec['dependencies'].each do |name,versions|
+      gem.add_dependency(name,split[versions])
     end
-  else
-    s.add_dependency(%q<rspec>, ["~> 2.0.0"])
-    s.add_dependency(%q<yard>, ["~> 0.6.0"])
-    s.add_dependency(%q<jeweler>, ["~> 1.4.0"])
   end
-end
 
+  if gemspec['development_dependencies']
+    gemspec['development_dependencies'].each do |name,versions|
+      gem.add_development_dependency(name,split[versions])
+    end
+  end
+end

data/gemspec.yml

@@ -0,0 +1,25 @@
+name: combinatorics
+summary: Bringing (more) Combinatorics to Ruby
+description:
+  A collection of modules and methods for performing Combinatoric
+  calculations.
+license: MIT
+authors:
+ - Postmodern
+ - Duper
+email:
+ - postmodern.mod3@gmail.com
+ - super@manson.vistech.net
+homepage: https://github.com/postmodern/combinatorics#readme
+has_yard: true
+
+metadata:
+  documentation_uri: https://rubydoc.info/gems/combinatorics
+  source_code_uri:   https://github.com/postmodern/combinatorics.rb
+  bug_tracker_uri:   https://github.com/postmodern/combinatorics.rb/issues
+  changelog_uri:     https://github.com/postmodern/combinatorics.rb/blob/master/ChangeLog.md
+
+required_ruby_version: ">= 1.8.7"
+
+development_dependencies:
+  bundler: ~> 2.0

data/lib/combinatorics/cartesian_product/cardinality.rb

@@ -0,0 +1,45 @@
+module Combinatorics
+  #
+  # @author duper <super@manson.vistech.net>
+  #
+  # @since 0.4.0
+  #
+  module CartesianProduct
+    #
+    # Wrapper for Cartesian product cardinality method defined above
+    #
+    # @param [Fixnum] a
+    #   Cardinality of first set.
+    #
+    # @param [Fixnum] b
+    #   Cardinality of second set.
+    #
+    # @raise [RangeError]
+    #   Inputs must be greater than zero.
+    #
+    # @return [Fixnum]
+    #   Length of enumeration resulting from a Cartesian product.
+    #
+    # @example Calculate elements in Cartesian product of two equal-size sets
+    #   cardinality(3, 4) 
+    #   # => 12
+    # 
+    def self.cardinality(a,b)
+      if (a <= 0 || b <= 0)
+        raise(RangeError,"inputs must be greater than zero")
+      end
+
+      a * b
+    end
+
+    #
+    # @note The letter `X' is scholastic notation for the Cartesian product
+    #       set operation
+    #
+    # @see cardinality
+    #
+    def self.X(a,b)
+      cardinality(a,b)
+    end
+  end
+end

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

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

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

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

data/lib/combinatorics/cartesian_product/extensions.rb

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

data/lib/combinatorics/cartesian_product/mixin.rb

@@ -0,0 +1,57 @@
+require 'combinatorics/list_comprehension'
+
+module Combinatorics
+  module CartesianProduct
+    #
+    # @author duper <super@manson.vistech.net>
+    #
+    # @since 0.4.0
+    #
+    module Mixin
+      #
+      # Calculates the Cartesian product of an Enumerable object.
+      #
+      # @yield [subset]
+      #   If a block is given, it will be passed each individual subset
+      #   element from the Cartesian product set as a whole.
+      #
+      # @yieldparam [Array] subset
+      #   The sub-set from the Cartesian product.
+      #
+      # @return [Enumerator]
+      #   Resulting Cartesian product set.
+      #
+      # @raise [TypeError]
+      #   `other` must be Enumerable.
+      #
+      # @example Cartesian product of an Array
+      #   [1, 2].cartesian_product([3, 4])
+      #   # => [[1, 3], [2, 3], [1, 4], [2, 4]]
+      #
+      # @example Cartesian product over an Array of Strings
+      #   ['a'].cartesian_product(['b', 'c', 'd']).to_a
+      #   # => [["a", "b"], ["a", "c"], ["a", "d"]]
+      #
+      # @example Three-way Cartesian product operation
+      #   [0, 1].cartesian_product([2, 3], [4, 5]).to_a
+      #   # => [
+      #   #      [0, 2, 4], [0, 2, 5], [0, 3, 4], [0, 3, 5],
+      #   #      [1, 2, 4], [1, 2, 5], [1, 3, 4], [1, 3, 5],
+      #   #    ]
+      #   
+      # @see http://en.wikipedia.org/wiki/Cartesian_product
+      #
+      def cartesian_product(*others,&block)
+        return enum_for(:cartesian_product,*others) unless block
+
+        # a single empty Set will result in an empty Set
+        return nil if (empty? || others.any?(&:empty?))
+
+        Array[self,*others].comprehension(&block)
+      end
+
+      alias cartprod  cartesian_product
+      alias cartesian cartesian_product
+    end
+  end
+end

data/lib/combinatorics/cartesian_product.rb

@@ -0,0 +1,3 @@
+require 'combinatorics/cartesian_product/mixin'
+require 'combinatorics/cartesian_product/extensions'
+require 'combinatorics/cartesian_product/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 1
+      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/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/extensions.rb

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

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

@@ -0,0 +1,3 @@
+require 'combinatorics/choose/mixin'
+require 'combinatorics/choose/extensions'
+require 'combinatorics/choose/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