Updated the gem description and added several new REPL samples in

README.md

README.md

@@ -9,10 +9,20 @@
 
 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` or `len` 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}.
+* Mixes `powerset`, `cartprod`, `permute`, `choose`, and `derange` into
+  {Array} and {Set}.
 * Added {Range#&}, {Range#upto} and {Range#downto}.
 * Adds Haskell/Python style list comprehensions via {Array#comprehension}.
 
@@ -87,17 +97,78 @@ List comprehensions:
           [10, "b"],
           [10, "c"]]
 
+Cartesian products:
+
+require 'combinatorics/cartesian_product'
+
+['a', 'b', 'c'].cartprod([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:
+
+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:
+
+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:
+
+require 'combinatorics/permutation'
+
+include Combinatorics::Permute
+
+Combinatorics::Permute::cardinality(128)
+# => 8256
+
+
 ## Requirements
 
-* [ruby](http://www.ruby-lang.org/) >= 1.8.7
+  * [ruby](http://www.ruby-lang.org/) >= 1.8.7
 
 ## Install
 
-    $ sudo gem install combinatorics
+      $ sudo gem install combinatorics
 
 ## Copyright
 
-Copyright (c) 2010 Hal Brodigan
+  Copyright (c) 2010 Hal Brodigan
 
-See {file:LICENSE.txt} for license information.
+  See {file:LICENSE.txt} for license information.