add Stats API

Added a way to access descriptive statistics in case it is
desired to keep the collection pristine.

Gemfile.lock

@@ -1,16 +1,20 @@
 GEM
   remote: https://rubygems.org/
   specs:
-    diff-lcs (1.2.4)
-    rake (10.1.1)
-    rspec (2.14.1)
-      rspec-core (~> 2.14.0)
-      rspec-expectations (~> 2.14.0)
-      rspec-mocks (~> 2.14.0)
-    rspec-core (2.14.3)
-    rspec-expectations (2.14.0)
-      diff-lcs (>= 1.1.3, < 2.0)
-    rspec-mocks (2.14.1)
+    diff-lcs (1.2.5)
+    rake (10.3.2)
+    rspec (3.0.0)
+      rspec-core (~> 3.0.0)
+      rspec-expectations (~> 3.0.0)
+      rspec-mocks (~> 3.0.0)
+    rspec-core (3.0.4)
+      rspec-support (~> 3.0.0)
+    rspec-expectations (3.0.4)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.0.0)
+    rspec-mocks (3.0.4)
+      rspec-support (~> 3.0.0)
+    rspec-support (3.0.4)
 
 PLATFORMS
   ruby

README.md

@@ -149,6 +149,19 @@ requiring DescriptiveStatistics safely, thus avoiding the monkey patch. For exam
  => 54 
 ```
 
+Or if you prefer leaving your collection pristine
+```
+> require 'descriptive_statistics/safe'
+ => true 
+> stats = DescriptiveStatistics::Stats.new([1,2,3,4,5,1])
+ => #<DescriptiveStatistics::Stats:0x00000101a38228 @collection=[1, 2, 3, 4, 5, 1]> 
+> stats.mean
+ => 2.6666666666666665 
+> stats.median
+ => 2.5 
+> stats.mode
+ => 1 
+```
 
 Notes
 -----

descriptive_statistics.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name        = 'descriptive_statistics'
-  s.version     = '2.0.1'
+  s.version     = '2.1.0'
   s.homepage    = 'https://github.com/thirtysixthspan/descriptive_statistics'
   s.summary     = 'Descriptive Statistics'
   s.description = 'Adds descriptive statistics methods to Enumerable module for use on collections or Numeric data'

lib/descriptive_statistics/safe.rb

@@ -10,4 +10,5 @@
 require 'descriptive_statistics/percentile_rank.rb'
 require 'descriptive_statistics/range.rb'
 require 'descriptive_statistics/descriptive_statistics.rb'
+require 'descriptive_statistics/stats.rb'
 

lib/descriptive_statistics/stats.rb

@@ -0,0 +1,18 @@
+require 'forwardable'
+
+module DescriptiveStatistics
+
+  class Stats
+    extend Forwardable
+
+    DescriptiveStatistics.instance_methods.each do |m|
+      def_delegator :@collection, m 
+    end
+
+    def initialize(collection)
+      @collection = collection.clone.extend(DescriptiveStatistics)
+    end
+
+  end
+
+end

spec/stats_spec.rb

@@ -0,0 +1,58 @@
+require 'rspec'
+
+describe "DescriptiveStatistics::Stats" do
+  require 'descriptive_statistics/safe'
+
+  context "calculated from a Stats object" do
+
+    subject { DescriptiveStatistics::Stats.new([2,6,9,3,5,1,8,3,6,9,2]) }
+
+    it "calculates the number" do
+      expect(subject.number).to eql(11.0)
+    end
+
+    it "calculates the sum" do
+      expect(subject.sum).to eql(54.0)
+    end
+
+    it "calculates the mean" do
+      expect(subject.mean).to eql(4.909090909090909)
+    end
+
+    it "calculates the median" do
+      expect(subject.median).to eql(5.0)
+    end
+
+    it "calculates the variance" do
+      expect(subject.variance).to eql(7.7190082644628095)
+    end
+
+    it "calculates the standard_deviation" do
+      expect(subject.standard_deviation).to eql(2.778310325442932)
+    end
+
+    it "calculates the percentile" do
+      expect(subject.percentile(30)).to eql(3.0)
+      expect(subject.percentile(50)).to eql(5.0)
+      expect(subject.percentile(70)).to eql(6.0)
+    end
+
+    it "calculates the same value for the 50th percentile and median" do
+      expect(subject.percentile(50)).to eql(subject.median)
+    end
+
+    it "calculates the mode" do
+      expect(subject.mode).to eql(2)
+    end
+
+    it "calculates the range" do
+      expect(subject.range).to eql(8.0)
+    end
+
+    it "calculates the percentile rank" do
+      expect(subject.percentile_rank(8)).to eql(81.81818181818183)
+    end
+
+   end
+
+end