README.rdoc in davidrichards-just_enumerable_stats-0.0.4 vs README.rdoc in davidrichards-just_enumerable_stats-0.0.5

@@ -95,10 +95,52 @@
   a.default_block = lambda {|e| e * 2}
   a.sum
   # => [2,4,6]
   a.std
   # => 2.0 instead of 1.0
-  
+    
+== Categories
+
+Once I started using this gem with my distribution table classes, I needed to have flexible categories on an enumerable.  What that looks like is:
+
+  Loading Just Enumerable Stats version: 0.0.4
+  >> a = [1,2,3]
+  => [1, 2, 3]
+  >> a.categories
+  => [1, 2, 3]
+  >> a.category_values
+  => {1=>[1], 2=>[2], 3=>[3]}
+  >> a.set_range_class FixedRange, 1, 3, 0.5
+  => FixedRange
+  >> a.categories
+  => [1.0, 1.5, 2.0, 2.5, 3.0]
+  >> a.category_values(true)
+  => {1.0=>[1], 1.5=>[], 2.0=>[2], 2.5=>[], 3.0=>[3]}
+  >> a.set_range({
+  ?> "<3" => lambda{|e| e < 3},
+  ?> "3" => lambda{|e| e == 3}
+  >> })
+  => ["<3", "3"]
+  >> a.categories
+  => ["<3", "3"]
+  >> a.category_values(true)
+  => {"<3"=>[1, 2], "3"=>[3]}
+  >> a.count_if {|e| e < 3}
+  => 2
+  >> a.count_if {|e| e == 3}
+  => 1
+
+OK, here we go:
+
+* If you have facets installed (sudo gem install facets), it will use a Dictionary instead of a Hash, keeping the order of the hash values consistent with the order they were loaded.  It's nice to have an ordered hash, so go ahead and install that.
+* The categories default as all the unique values in the enumerable
+* category_values is a hash or dictionary of values for each category.  The values are returned as an array.  This is cached, so call it like a.category_values(true) to reset the hash.
+* set_range_class sets an arbitrary class to use for calculating a range.  It should respond to map that will return an array of all values in the range.  The arguments after FixedRange are the arguments I want to use when instantiating the class.  This is an arbitrary list as well.  I could just as easily have typed a.set_range_class FixedRange, a.min, a.max, 0.5 with similar results.
+* FixedRange is a Range that can work with floating numbers.  Range.new(1.0, 3.0).map chokes but FixedRange.new(1.0, 3.0).map does not.
+* set_range takes an arbitrary hash of lambdas and sets the categories to the keys of that hash.
+* The category_values calculated with a hash of lambdas makes a very flexible set interface for enumerables.  There is no rule that the categories setup this way have to be mutually exclusive or collectively exhaustive (MECE), so interesting data sets can be setup here.  However, MECE is generally a good guideline for most analysis.
+* count_if is just like a.select_all{|e| e < 3}.size, but a little more obvious.
+
 ==Installation
 
 sudo gem install davidrichards-just_enumerable_stats
 
 == Dependencies