combinatorics 0.3.0 → 0.4.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e0761711a88421b7b0214a3b585b6a843401bd1e84bb189c87a0c4167d7e5f32
+  data.tar.gz: 6c42e53311328f5d0f6c27ea339c3539046fee352dfb548155d35183a19d5aef
+SHA512:
+  metadata.gz: 1d9df890fc1669969b84e48a0b3d6126111cc6e13369308f76c274e0227fcd475a9047872ef247dc83b009f4b5d234526aa9d88c0c59cff7c9129d080c93a044
+  data.tar.gz: 53eabbc7025dbaa9e79d8fe44c8d68c0182de3b575f425f6b4d0231c88920a8ee7b8c85bfd8f94743b8a618184525d0db5264d37232bd8793396b93afbfb1a0f

data/.document

@@ -1,4 +1,4 @@
-lib/**/*.rb
 - 
 LICENSE.txt
+Benchmarks.md
 ChangeLog.md

data/.github/workflows/ruby.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on: [ push, pull_request ]
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby:
+          - 2.6
+          - 2.7
+          - '3.0'
+          - 3.1
+          - jruby
+          - truffleruby
+    name: Ruby ${{ matrix.ruby }}
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+      - name: Install dependencies
+        run: bundle install --jobs 4 --retry 3
+      - name: Run tests
+        run: bundle exec rake test

data/.gitignore

@@ -1,8 +1,7 @@
-pkg
-doc
-web
-tmp
+/Gemfile.lock
+/pkg
+/doc
+/.yardoc
 .DS_Store
-.yardoc
 *.swp
 *~

data/Benchmarks.md

@@ -0,0 +1,281 @@
+# Benchmarks
+
+Benchmarks for the {Combinatorics} code can be found in the `benchmarks/`
+directory.
+
+Benchmark machine specs:
+
+* CPU: AMD Athlon(tm) 64 Processor 3400+ (2202.785 MHz)
+* Cache Size: 1024 KB
+* Memory: 1 Gb
+
+## List Comprehensions:
+
+Ruby 1.9.2-p290 (2011-07-09 revision 32553) [x86_64-linux]:
+
+                      user     system      total        real
+    singleton:    0.050000   0.020000   0.070000 (  0.081225)
+    single-enum:  0.000000   0.000000   0.000000 (  0.009706)
+    depth 1:      0.000000   0.000000   0.000000 (  0.000652)
+    depth 2:      0.070000   0.010000   0.080000 (  0.084974)
+    depth 3:      5.670000   0.240000   5.910000 (  6.623347)
+
+JRuby 1.6.4 (ruby-1.8.7-p330) (2011-08-23 17ea768)
+(OpenJDK 64-Bit Server VM 1.6.0_22) [linux-amd64-java]:
+
+                      user     system      total        real
+    singleton:    1.365000   0.000000   1.365000 (  1.212000)
+    single-enum:  0.134000   0.000000   0.134000 (  0.134000)
+    depth 1:      0.046000   0.000000   0.046000 (  0.045000)
+    depth 2:      1.613000   0.000000   1.613000 (  1.614000)
+    depth 3:     10.054000   0.000000  10.054000 ( 10.054000)
+
+Rubinius 2.0.0dev (1.8.7 5e67b11e yyyy-mm-dd JI) [x86_64-unknown-linux-gnu]:
+
+                      user     system      total        real
+    singleton:    0.802878   0.112983   0.915861 (  1.722362)
+    single-enum:  0.128980   0.011998   0.140978 (  0.176392)
+    depth 1:      0.000000   0.000000   0.000000 (  0.000897)
+    depth 2:      0.058991   0.004999   0.063990 (  0.143435)
+    depth 3:      3.483470   0.148977   3.632447 (  5.156510)
+
+## Cartesian Product
+
+Ruby 1.9.2-p290 (2011-07-09 revision 32553) [x86_64-linux]:
+
+                       user     system      total        real
+    {100} x {100}  0.070000   0.000000   0.070000 (  0.084734)
+    {200} x {200}  0.290000   0.020000   0.310000 (  0.347752)
+    {400} x {400}  1.370000   0.070000   1.440000 (  1.582130)
+    {800} x {800}  8.250000   0.370000   8.620000 (  9.498290)
+
+JRuby 1.6.4 (ruby-1.8.7-p330) (2011-08-23 17ea768)
+(OpenJDK 64-Bit Server VM 1.6.0_22) [linux-amd64-java]:
+
+                       user     system      total        real
+    {100} x {100}  2.469000   0.000000   2.469000 (  2.349000)
+    {200} x {200}  2.575000   0.000000   2.575000 (  2.574000)
+    {400} x {400}  2.354000   0.000000   2.354000 (  2.354000)
+    {800} x {800}  7.730000   0.000000   7.730000 (  7.730000)
+
+Rubinius 2.0.0dev (1.8.7 5e67b11e yyyy-mm-dd JI) [x86_64-unknown-linux-gnu]:
+
+                       user     system      total        real
+    {100} x {100}  0.114982   0.051992   0.166974 (  1.184129)
+    {200} x {200}  0.391941   0.159976   0.551917 (  1.396105)
+    {400} x {400}  1.333797   0.653901   1.987698 (  3.120384)
+    {800} x {800}  5.961093   2.614602   8.575695 ( 13.643119)
+
+## Choose
+
+Ruby 1.9.2-p290 (2011-07-09 revision 32553) [x86_64-linux]:
+
+          user     system      total        real
+    n=20 k=1  0.000000   0.000000   0.000000 (  0.000172)
+    n=20 k=2  0.010000   0.000000   0.010000 (  0.003592)
+    n=20 k=3  0.010000   0.000000   0.010000 (  0.017710)
+    n=20 k=4  0.040000   0.000000   0.040000 (  0.060566)
+    n=20 k=5  0.180000   0.010000   0.190000 (  0.211709)
+    n=20 k=6  0.490000   0.030000   0.520000 (  0.583004)
+    n=20 k=7  1.110000   0.070000   1.180000 (  1.307065)
+    n=20 k=8  1.980000   0.050000   2.030000 (  2.204111)
+    n=20 k=9  2.770000   0.120000   2.890000 (  3.221468)
+    n=20 k=10  3.310000   0.150000   3.460000 (  3.904973)
+    n=20 k=11  3.120000   0.150000   3.270000 (  4.085721)
+    n=20 k=12  2.520000   0.140000   2.660000 (  3.139445)
+    n=20 k=13  1.570000   0.060000   1.630000 (  1.853883)
+    n=20 k=14  0.820000   0.040000   0.860000 (  1.142598)
+    n=20 k=15  0.350000   0.020000   0.370000 (  0.436363)
+    n=20 k=16  0.110000   0.000000   0.110000 (  0.141398)
+    n=20 k=17  0.030000   0.010000   0.040000 (  0.047691)
+    n=20 k=18  0.000000   0.000000   0.000000 (  0.003746)
+    n=20 k=19  0.000000   0.000000   0.000000 (  0.000438)
+    n=20 k=20  0.000000   0.000000   0.000000 (  0.000043)
+
+JRuby 1.6.4 (ruby-1.8.7-p330) (2011-08-23 17ea768)
+(OpenJDK 64-Bit Server VM 1.6.0_22) [linux-amd64-java]:
+
+          user     system      total        real
+    n=20 k=1  0.271000   0.000000   0.271000 (  0.048000)
+    n=20 k=2  0.163000   0.000000   0.163000 (  0.163000)
+    n=20 k=3  0.184000   0.000000   0.184000 (  0.184000)
+    n=20 k=4  0.759000   0.000000   0.759000 (  0.759000)
+    n=20 k=5  1.157000   0.000000   1.157000 (  1.157000)
+    n=20 k=6  1.116000   0.000000   1.116000 (  1.116000)
+    n=20 k=7  0.490000   0.000000   0.490000 (  0.490000)
+    n=20 k=8  0.632000   0.000000   0.632000 (  0.632000)
+    n=20 k=9  0.907000   0.000000   0.907000 (  0.908000)
+    n=20 k=10  1.040000   0.000000   1.040000 (  1.040000)
+    n=20 k=11  0.991000   0.000000   0.991000 (  0.991000)
+    n=20 k=12  0.784000   0.000000   0.784000 (  0.784000)
+    n=20 k=13  0.513000   0.000000   0.513000 (  0.514000)
+    n=20 k=14  0.285000   0.000000   0.285000 (  0.285000)
+    n=20 k=15  0.141000   0.000000   0.141000 (  0.142000)
+    n=20 k=16  0.045000   0.000000   0.045000 (  0.045000)
+    n=20 k=17  0.009000   0.000000   0.009000 (  0.009000)
+    n=20 k=18  0.004000   0.000000   0.004000 (  0.004000)
+    n=20 k=19  0.001000   0.000000   0.001000 (  0.001000)
+    n=20 k=20  0.000000   0.000000   0.000000 (  0.000000)
+
+Rubinius 2.0.0dev (1.8.7 5e67b11e yyyy-mm-dd JI) [x86_64-unknown-linux-gnu]:
+
+          user     system      total        real
+    n=20 k=1  0.001000   0.000000   0.001000 (  0.001005)
+    n=20 k=2  0.005999   0.000000   0.005999 (  0.016681)
+    n=20 k=3  0.051992   0.002000   0.053992 (  0.177731)
+    n=20 k=4  0.159976   0.005999   0.165975 (  0.564428)
+    n=20 k=5  0.412938   0.016998   0.429936 (  1.410280)
+    n=20 k=6  1.045841   0.034994   1.080835 (  1.220624)
+    n=20 k=7  2.234661   0.073989   2.308650 (  2.514775)
+    n=20 k=8  3.821419   0.157976   3.979395 (  4.479381)
+    n=20 k=9  5.377183   0.230965   5.608148 (  6.545616)
+    n=20 k=10  6.270047   0.271958   6.542005 (  7.481663)
+    n=20 k=11  6.056079   0.201970   6.258049 (  7.179931)
+    n=20 k=12  4.684288   0.237963   4.922251 (  5.829043)
+    n=20 k=13  3.066534   0.122982   3.189516 (  3.633006)
+    n=20 k=14  1.716739   0.060990   1.777729 (  2.083863)
+    n=20 k=15  0.708892   0.031996   0.740888 (  0.814869)
+    n=20 k=16  0.233965   0.006999   0.240964 (  0.272663)
+    n=20 k=17  0.057992   0.000999   0.058991 (  0.075194)
+    n=20 k=18  0.008999   0.001000   0.009999 (  0.015695)
+    n=20 k=19  0.001999   0.000000   0.001999 (  0.001539)
+    n=20 k=20  0.000000   0.000000   0.000000 (  0.000253)
+
+## Permute
+
+Ruby 1.9.2-p290 (2011-07-09 revision 32553) [x86_64-linux]:
+
+          user     system      total        real
+    r=1  0.000000   0.000000   0.000000 (  0.000029)
+    r=2  0.000000   0.000000   0.000000 (  0.000029)
+    r=3  0.010000   0.000000   0.010000 (  0.002234)
+    r=4  0.000000   0.000000   0.000000 (  0.002388)
+    r=5  0.020000   0.000000   0.020000 (  0.028709)
+    r=6  0.100000   0.000000   0.100000 (  0.119063)
+    r=7  0.380000   0.030000   0.410000 (  0.462036)
+    r=8  1.210000   0.080000   1.290000 (  1.447420)
+    r=9  2.510000   0.130000   2.640000 (  2.919967)
+    r=10  2.840000   0.200000   3.040000 (  3.664906)
+
+JRuby 1.6.4 (ruby-1.8.7-p330) (2011-08-23 17ea768)
+(OpenJDK 64-Bit Server VM 1.6.0_22) [linux-amd64-java]:
+
+          user     system      total        real
+    r=1  0.274000   0.000000   0.274000 (  0.041000)
+    r=2  0.001000   0.000000   0.001000 (  0.001000)
+    r=3  0.012000   0.000000   0.012000 (  0.012000)
+    r=4  0.154000   0.000000   0.154000 (  0.154000)
+    r=5  0.306000   0.000000   0.306000 (  0.307000)
+    r=6  0.081000   0.000000   0.081000 (  0.081000)
+    r=7  0.168000   0.000000   0.168000 (  0.168000)
+    r=8  0.516000   0.000000   0.516000 (  0.517000)
+    r=9  1.224000   0.000000   1.224000 (  1.224000)
+    r=10  1.649000   0.000000   1.649000 (  1.649000)
+
+Rubinius 2.0.0dev (1.8.7 5e67b11e yyyy-mm-dd JI) [x86_64-unknown-linux-gnu]:
+
+          user     system      total        real
+    r=1  0.001000   0.000000   0.001000 (  0.000062)
+    r=2  0.001000   0.000000   0.001000 (  0.004535)
+    r=3  0.006000   0.000000   0.006000 (  0.016175)
+    r=4  0.049993   0.003000   0.052993 (  0.171867)
+    r=5  0.153976   0.012998   0.166974 (  0.584311)
+    r=6  0.578912   0.020997   0.599909 (  0.654977)
+    r=7  2.694590   0.106984   2.801574 (  3.170215)
+    r=8  9.167606   0.337948   9.505554 ( 10.952164)
+    r=9 21.419744   0.785881  22.205625 ( 24.619187)
+    r=10 29.557506   1.087834  30.645340 ( 34.234011)
+
+## Derange
+
+Ruby 1.9.2-p290 (2011-07-09 revision 32553) [x86_64-linux]:
+
+          user     system      total        real
+    n=1  0.000000   0.000000   0.000000 (  0.000021)
+    n=2  0.000000   0.000000   0.000000 (  0.000041)
+    n=3  0.000000   0.000000   0.000000 (  0.000021)
+    n=4  0.000000   0.000000   0.000000 (  0.000069)
+    n=5  0.000000   0.000000   0.000000 (  0.000393)
+    n=6  0.000000   0.000000   0.000000 (  0.002281)
+    n=7  0.020000   0.010000   0.030000 (  0.028188)
+    n=8  0.170000   0.000000   0.170000 (  0.207589)
+    n=9  1.630000   0.070000   1.700000 (  1.974767)
+    n=10 17.200000   0.670000  17.870000 ( 20.047089)
+
+JRuby 1.6.4 (ruby-1.8.7-p330) (2011-08-23 17ea768)
+(OpenJDK 64-Bit Server VM 1.6.0_22) [linux-amd64-java]:
+
+          user     system      total        real
+    n=1  0.150000   0.000000   0.150000 (  0.023000)
+    n=2  0.003000   0.000000   0.003000 (  0.003000)
+    n=3  0.001000   0.000000   0.001000 (  0.001000)
+    n=4  0.006000   0.000000   0.006000 (  0.007000)
+    n=5  0.022000   0.000000   0.022000 (  0.022000)
+    n=6  0.173000   0.000000   0.173000 (  0.173000)
+    n=7  1.045000   0.000000   1.045000 (  1.045000)
+    n=8  0.821000   0.000000   0.821000 (  0.821000)
+    n=9  1.917000   0.000000   1.917000 (  1.917000)
+    n=10 25.652000   0.000000  25.652000 ( 25.652000)
+
+Rubinius 2.0.0dev (1.8.7 5e67b11e yyyy-mm-dd JI) [x86_64-unknown-linux-gnu]:
+
+          user     system      total        real
+    n=1  0.000000   0.000000   0.000000 (  0.000025)
+    n=2  0.000000   0.000000   0.000000 (  0.000394)
+    n=3  0.000000   0.000000   0.000000 (  0.000145)
+    n=4  0.000000   0.000000   0.000000 (  0.000637)
+    n=5  0.004000   0.000000   0.004000 (  0.010315)
+    n=6  0.036994   0.003000   0.039994 (  0.151349)
+    n=7  0.130980   0.009998   0.140978 (  0.584286)
+    n=8  0.579912   0.028996   0.608908 (  0.946738)
+    n=9  5.563154   0.191970   5.755124 (  6.588485)
+    n=10 59.973882   2.427631  62.401513 ( 80.877847)
+
+## Power Set
+
+Ruby 1.9.2-p290 (2011-07-09 revision 32553) [x86_64-linux]:
+
+          user     system      total        real
+    n=10  0.000000   0.000000   0.000000 (  0.015275)
+    n=11  0.020000   0.000000   0.020000 (  0.033685)
+    n=12  0.050000   0.000000   0.050000 (  0.063667)
+    n=13  0.110000   0.010000   0.120000 (  0.131612)
+    n=14  0.230000   0.010000   0.240000 (  0.276595)
+    n=15  0.500000   0.010000   0.510000 (  0.559058)
+    n=16  1.040000   0.050000   1.090000 (  1.222567)
+    n=17  2.110000   0.120000   2.230000 (  2.607683)
+    n=18  4.410000   0.230000   4.640000 (  5.223074)
+    n=19  9.240000   0.460000   9.700000 ( 10.995905)
+    n=20 19.280000   0.810000  20.090000 ( 23.152085)
+
+JRuby 1.6.4 (ruby-1.8.7-p330) (2011-08-23 17ea768)
+(OpenJDK 64-Bit Server VM 1.6.0_22) [linux-amd64-java]:
+
+          user     system      total        real
+    n=10  0.539000   0.000000   0.539000 (  0.369000)
+    n=11  0.609000   0.000000   0.609000 (  0.609000)
+    n=12  0.490000   0.000000   0.490000 (  0.490000)
+    n=13  0.701000   0.000000   0.701000 (  0.701000)
+    n=14  1.013000   0.000000   1.013000 (  1.013000)
+    n=15  0.729000   0.000000   0.729000 (  0.729000)
+    n=16  0.306000   0.000000   0.306000 (  0.306000)
+    n=17  0.601000   0.000000   0.601000 (  0.601000)
+    n=18  1.291000   0.000000   1.291000 (  1.291000)
+    n=19  2.591000   0.000000   2.591000 (  2.591000)
+    n=20  5.573000   0.000000   5.573000 (  5.573000)
+
+Rubinius 2.0.0dev (1.8.7 5e67b11e yyyy-mm-dd JI) [x86_64-unknown-linux-gnu]:
+
+          user     system      total        real
+    n=10  0.050992   0.009999   0.060991 (  0.196739)
+    n=11  0.088986   0.011998   0.100984 (  0.295952)
+    n=12  0.141979   0.003999   0.145978 (  0.632228)
+    n=13  0.248962   0.012998   0.261960 (  0.939763)
+    n=14  0.482927   0.015998   0.498925 (  0.562893)
+    n=15  0.988849   0.035994   1.024843 (  1.134604)
+    n=16  2.034691   0.076988   2.111679 (  2.342626)
+    n=17  4.188363   0.158976   4.347339 (  4.882135)
+    n=18  8.595693   0.347947   8.943640 ( 10.191949)
+    n=19 17.662315   0.674898  18.337213 ( 20.490505)
+    n=20 36.434461   1.536766  37.971227 ( 42.821087)
+

data/ChangeLog.md

@@ -1,3 +1,45 @@
+### 0.4.4 / 2022-01-16
+
+* Fixed a bug in {Combinatorics::Choose.cardinality} for when `0`
+  is given and `0` was returned instead of `1`.
+
+### 0.4.3 / 2012-05-28
+
+* Fixed a typo in the gemspec, which incorrectly set
+  `required_rubygems_version` to the same value as `required_ruby_version`.
+
+### 0.4.2 / 2012-05-27
+
+* Avoid warnings on JRuby by checking for `::Generator` before
+  `::Enumerator::Generator` in `combinatorics/generator`.
+* Raise a `NameError` when the `Generator` class cannot be found in
+  `combinatorics/generator`.
+* Replaced ore-tasks with
+  [rubygems-tasks](https://github.com/postmodern/rubygems-tasks#readme).
+
+### 0.4.1 / 2011-10-15
+
+* Fixed a typo in the gemspec.
+
+### 0.4.0 / 2011-10-15
+
+* Added {Math.sigma}.
+* Added {Math.pi}.
+* Added {Math.factorial}.
+* Added {Math.subfactorial}.
+* Added {Combinatorics::CartesianProduct}.
+* Added {Combinatorics::Choose}.
+* Added {Combinatorics::Derange}.
+* Added {Combinatorics::Permute}.
+* Added {Combinatorics::PowerSet}.
+
+### 0.3.1 / 2010-10-26
+
+* Do not call `enum_for` on `Enumerator` objects passed to
+  {Array#comprehension}.
+* Improved {Array#comprehension} benchmarks.
+* Added [benchmark results] (see {file:Benchmarks.md}).
+
 ### 0.3.0 / 2010-10-17
 
 * Added {Combinatorics::Generator} which auto-detects the `Generator`

data/Gemfile

@@ -0,0 +1,14 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :development do
+  gem 'rake'
+  gem 'rubygems-tasks', '~> 0.2'
+
+  gem 'rspec',          '~> 3.0'
+
+  gem 'kramdown'
+  gem 'yard',           '~> 0.9'
+  gem 'yard-spellcheck', require: false
+end

data/LICENSE.txt

@@ -1,5 +1,4 @@
-
-Copyright (c) 2010 Hal Brodigan
+Copyright (c) 2010-2022 Hal Brodigan
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,96 +1,205 @@
 # Combinatorics
 
-* [github.com/postmodern/combinatorics](http://github.com/postmodern/combinatorics)
-* [github.com/postmodern/combinatorics/issues](http://github.com/postmodern/combinatorics/issues)
-* Postmodern (postmodern.mod3 at gmail.com)
+[![CI](https://github.com/postmodern/combinatorics/actions/workflows/ruby.yml/badge.svg)](https://github.com/postmodern/combinatorics/actions/workflows/ruby.yml)
+[![Code Climate](https://codeclimate.com/github/postmodern/combinatorics.svg)](https://codeclimate.com/github/postmodern/combinatorics)
+
+* [Source](https://github.com/postmodern/combinatorics)
+* [Issues](https://github.com/postmodern/combinatorics/issues)
+* [Documentation](http://rubydoc.info/gems/combinatorics)
 
 ## Description
 
 A collection of modules and methods for performing
 [Combinatoric](http://en.wikipedia.org/wiki/Combinatoric) calculations.
+Methods are defined to compute power sets, Cartesian products, permutations, 
+combinations, and derangements.
+
+Note: this includes k-combinations and k-permutations, i.e. only generating
+resultant sets of a given size. Each set theory operation method supports block 
+arguments to allow continuous code execution during the combinatoric set
+generation process. Each combinatoric operation implementation also supports a
+`cardinality` method which determines the total number of subsets that will be
+created beforehand (to aid in the avoidance of starting an operation which will 
+never complete due to exponential computational complexity.)
 
 ## Features
 
-* Adds `powerset` to {Array} and {Set}.
-* Added {Range#&}, {Range#upto} and {Range#downto}.
-* Adds Haskell/Python style list comprehensions via {Array#comprehension}.
+* Adds Haskell/Python style list comprehensions via [Array#comprehension].
+* Provides reusable Combinatorics Mixins:
+  * [Combinatorics::CartesianProduct]
+  * [Combinatorics::Choose]
+  * [Combinatorics::Derange]
+  * [Combinatorics::Permute]
+  * [Combinatorics::PowerSet]
+* Adds Combinatorics core extension methods to {Array} and {Set}:
+  * [cartesian_product]
+  * [choose]
+  * [derange]
+  * [permute]
+  * [powerset]
+* Adds additional core extension methods:
+  * [Range#&]
+  * [Range#upto]
+  * [Range#downto]
+  * [Math.sigma]
+  * [Math.pi]
+  * [Math.factorial]
+  * [Math.subfactorial]
+
+[Array#comprehension]: https://rubydoc.info/gems/combinatorics/Array#comprehension-instance_method
+[Combinatorics::CartesianProduct]: https://rubydoc.info/gems/combinatorics/Combinatorics/CartesianProduct
+[Combinatorics::Choose]: https://rubydoc.info/gems/combinatorics/Combinatorics/Choose
+[Combinatorics::Derange]: https://rubydoc.info/gems/combinatorics/Combinatorics/Derange
+[Combinatorics::Permute]: https://rubydoc.info/gems/combinatorics/Combinatorics/Permute
+[Combinatorics::PowerSet]: https://rubydoc.info/gems/combinatorics/Combinatorics/PowerSet
+[cartesian_product]: https://rubydoc.info/gems/combinatorics/Combinatorics/CartesianProduct/Mixin#cartesian_product-instance_method
+[choose]: https://rubydoc.info/gems/combinatorics/Combinatorics/Choose/Mixin#choose-instance_method
+[derange]: https://rubydoc.info/gems/combinatorics/Combinatorics/Derange/Mixin#derange-instance_method
+[permute]: https://rubydoc.info/gems/combinatorics/Combinatorics/Permute/Mixin#permute-instance_method
+[powerset]: https://rubydoc.info/gems/combinatorics/Combinatorics/PowerSet/Mixin#powerset-instance_method
+[Range#&]: https://rubydoc.info/gems/combinatorics/Range#&-instance_method
+[Range#upto]: https://rubydoc.info/gems/combinatorics/Range#upto-instance_method
+[Range#downto]: https://rubydoc.info/gems/combinatorics/Range#downto-instance_method
+[Math.sigma]: https://rubydoc.info/gems/combinatorics/Math#sigma-class_method
+[Math.pi]: https://rubydoc.info/gems/combinatorics/Math#pi-class_method
+[Math.factorial]: https://rubydoc.info/gems/combinatorics/Math#factorial-class_method
+[Math.subfactorial]: https://rubydoc.info/gems/combinatorics/Math#subfactorial-class_method
 
 ## Examples
 
-Power-set of an {Array}:
-
-    require 'combinatorics/power_set'
-
-    [1,2,3,4].powerset
-    # => [[],
-          [4],
-          [3],
-          [3, 4],
-          [2],
-          [2, 4],
-          [2, 3],
-          [2, 3, 4],
-          [1],
-          [1, 4],
-          [1, 3],
-          [1, 3, 4],
-          [1, 2],
-          [1, 2, 4],
-          [1, 2, 3],
-          [1, 2, 3, 4]]
-
-Power-set of a {Set}:
-
-    Set['ab', 'cd', 'ef'].powerset
-    # => [#<Set: {}>,
-          #<Set: {"ef"}>,
-          #<Set: {"cd"}>,
-          #<Set: {"cd", "ef"}>,
-          #<Set: {"ab"}>,
-          #<Set: {"ab", "ef"}>,
-          #<Set: {"ab", "cd"}>,
-          #<Set: {"ab", "cd", "ef"}>]
+Power-set:
+
+```ruby
+Set['ab', 'cd', 'ef'].powerset
+# => [#<Set: {}>,
+      #<Set: {"ef"}>,
+      #<Set: {"cd"}>,
+      #<Set: {"cd", "ef"}>,
+      #<Set: {"ab"}>,
+      #<Set: {"ab", "ef"}>,
+      #<Set: {"ab", "cd"}>,
+      #<Set: {"ab", "cd", "ef"}>]
+```
+
+Cartesian products:
+
+```ruby
+require 'combinatorics/cartesian_product'
+
+['a', 'b', 'c'].cartesian_product([0, 1, 2]).to_a
+# => [["a", 0], 
+      ["b", 0], 
+      ["c", 0], 
+      ["a", 1], 
+      ["b", 1], 
+      ["c", 1], 
+      ["a", 2], 
+      ["b", 2], 
+      ["c", 2]]
+```
+
+k-combinations:
+
+```ruby
+require 'combinatorics/choose'
+
+('a'..'f').to_a.choose(2).to_a
+# => [["a", "b"], 
+      ["a", "c"], 
+      ["a", "d"], 
+      ["a", "e"], 
+      ["a", "f"], 
+      ["b", "c"], 
+      ["b", "d"], 
+      ["b", "e"], 
+      ["b", "f"], 
+      ["c", "d"], 
+      ["c", "e"], 
+      ["c", "f"], 
+      ["d", "e"], 
+      ["d", "f"], 
+      ["e", "f"]]
+```
+
+Derangements:
+
+```ruby
+require 'combinatorics/derange'
+
+[:_, :q, :z, :x].derange.to_a
+# => [[:q, :_, :x, :z], 
+      [:q, :z, :x, :_], 
+      [:q, :x, :_, :z], 
+      [:z, :_, :x, :q], 
+      [:z, :x, :_, :q], 
+      [:z, :x, :q, :_], 
+      [:x, :_, :q, :z], 
+      [:x, :z, :_, :q], 
+      [:x, :z, :q, :_]]
+```
+
+Permutation cardinality:
+
+```ruby
+require 'combinatorics/permutation'
+
+Combinatorics::Permute.cardinality(128)
+# => 8256
+```
+
+List comprehensions:
+
+```ruby
+require 'combinatorics/list_comprehension'
+
+[(0..10).step(2),('a'..'c')].comprehension.to_a
+# => [[0, "a"],
+      [0, "b"],
+      [0, "c"],
+      [2, "a"],
+      [2, "b"],
+      [2, "c"],
+      [4, "a"],
+      [4, "b"],
+      [4, "c"],
+      [6, "a"],
+      [6, "b"],
+      [6, "c"],
+      [8, "a"],
+      [8, "b"],
+      [8, "c"],
+      [10, "a"],
+      [10, "b"],
+      [10, "c"]]
+```
 
 Find the intersecting sub-range between two ranges:
 
-    (1..50) & (20..100)
-    # => (20..50)
+```ruby
+(1..50) & (20..100)
+# => (20..50)
+```
 
 Enumerate over every sub-range between two ranges:
 
-    (1..5).upto(2..10).to_a
-    # => [1..5, 1..6, 1..7, 1..8, 1..9, 1..10,
-          2..5, 2..6, 2..7, 2..8, 2..9, 2..10]
+```ruby
+(1..5).upto(2..10).to_a
+# => [1..5, 1..6, 1..7, 1..8, 1..9, 1..10,
+      2..5, 2..6, 2..7, 2..8, 2..9, 2..10]
+```
 
-List comprehensions:
+## Requirements
 
-    require 'combinatorics/list_comprehension'
-
-    [(0..10).step(2),('a'..'c')].comprehension.to_a
-    # => [[0, "a"],
-          [0, "b"],
-          [0, "c"],
-          [2, "a"],
-          [2, "b"],
-          [2, "c"],
-          [4, "a"],
-          [4, "b"],
-          [4, "c"],
-          [6, "a"],
-          [6, "b"],
-          [6, "c"],
-          [8, "a"],
-          [8, "b"],
-          [8, "c"],
-          [10, "a"],
-          [10, "b"],
-          [10, "c"]]
+* [ruby](http://www.ruby-lang.org/) >= 1.8.7
 
 ## Install
 
-    $ sudo gem install combinatorics
+```shell
+$ gem install combinatorics
+```
 
-## License
+## Copyright
 
-See {file:LICENSE.txt} for license information.
+Copyright (c) 2010-2022 Hal Brodigan
 
+See {file:LICENSE.txt} for license information.