Permalink
Browse files

Updated README to match new features

  • Loading branch information...
1 parent f785c86 commit bb657a9aa687001451bf37501dcc74a8033f561b @blambeau committed Jul 12, 2011
Showing with 59 additions and 15 deletions.
  1. +37 −6 README.md
  2. +21 −0 spec/readme_spec.rb
  3. +1 −9 spec/summaryse_spec.rb
View
@@ -188,6 +188,43 @@ returned hashes are in order of encountered 'by key' values. That is, in the
example above, yard comes before summaryse that comes before treetop because
this is the order in which they have been seen initially.
+# Some extra goodness
+
+## Empty arrays
+
+For now, no special support is provided for the corner cases. One could argue
+that the sum of an empty array should be 0, but this is wrong because of duck
+typing (maybe you try to sum something else)... A nil value is returned in
+almost all empty cases unless the semantics is very clear:
+
+ [].summaryse(:count) # => 0
+ [].summaryse(:sum) # => nil
+ [].summaryse(:avg) # => nil
+
+ [].summaryse(:min) # => nil
+ [].summaryse(:max) # => nil
+ [].summaryse(:first) # => nil
+ [].summaryse(:last) # => nil
+
+ [].summaryse(:intersection) # => nil
+ [].summaryse(:union) # => nil
+
+Special support for specifying a default value to use on empty arrays should
+be provided around 2.0. Don't hesitate too contribute a patch if you need it
+earlier.
+
+## Registering your own aggregators
+
+Since 1.1, you can register your own aggregation functions. Such function simply
+takes a single argument which is an array of values to aggregate. This is
+especially useful to install new and/or override existing aggregation functions.
+This also allows handling parameters:
+
+ Summaryse.register(:comma_join) do |ary|
+ ary.join(', ')
+ end
+ [1, 4, 12, 7].summaryse(:comma_join) # => "1, 4, 12, 7"
+
# By the way, why this stupid name?
Just because summarize was already an {https://rubygems.org/gems/summarize existing gem}.
@@ -206,9 +243,3 @@ As usual: the code is on {http://github.com/blambeau/summaryse github}, I follow
{http://semver.org/ semantic versioning} (the public API is almost everything but
implementation details, that is, the method name, its recognized arguments and
the semantics of the returned value), etc.
-
-Now, frankly, you can also copy/paste the source code of this simple array
-extension in your own project. This tend to be much friendly and much simpler
-than using a gem, IMHO. Reuse by copy-pasting even has a name:
-{http://revision-zero.org/reuse code scavenging}.
-
View
@@ -114,4 +114,25 @@
[ left, right ].summaryse(merge).should eq(exp)
end
+ describe "Extra goodness" do
+
+ specify "On empty arrays" do
+ [].summaryse(:count).should eq(0)
+ [].summaryse(:first).should be_nil
+ [].summaryse(:intersection).should be_nil
+ [].summaryse(:last).should be_nil
+ [].summaryse(:min).should be_nil
+ [].summaryse(:sum).should be_nil
+ [].summaryse(:union).should be_nil
+ end
+
+ specify "Installing your own aggregators" do
+ Summaryse.register(:comma_join) do |ary|
+ ary.join(', ')
+ end
+ [1, 4, 12, 7].summaryse(:comma_join).should eq("1, 4, 12, 7")
+ end
+
+ end
+
end
View
@@ -25,28 +25,23 @@
end
it "should recognize count" do
- [].summaryse(:count).should eq(0)
numbers.summaryse(:count).should eq(5)
arrays.summaryse(:count).should eq(2)
end
it "should recognize first" do
- [].summaryse(:first).should be_nil
numbers.summaryse(:first).should eq(15)
end
it "should recognize intersection" do
- [].summaryse(:intersection).should be_nil
arrays.summaryse(:intersection).should eq([12])
end
it "should recognize last" do
- [].summaryse(:last).should be_nil
numbers.summaryse(:last).should eq(12)
end
it "should recognize min" do
- [].summaryse(:min).should be_nil
numbers.summaryse(:min).should eq(3)
end
@@ -56,13 +51,11 @@
end
it "should recognize sum" do
- [].summaryse(:sum).should be_nil
numbers.summaryse(:sum).should eq(15 + 3 + 17 + 4 + 12)
arrays.summaryse(:sum).should eq([15, 3, 12, 17, 4, 12])
end
it "should recognize union" do
- [].summaryse(:union).should be_nil
arrays.summaryse(:union).should eq([15, 3, 12, 17, 4])
end
@@ -126,7 +119,6 @@
{:version => "2.0", :size => 99}
])
end
-
end
-
+
end

0 comments on commit bb657a9

Please sign in to comment.