percentage 1.0.0

data/README.md

@@ -0,0 +1,84 @@
+Percentage
+==========
+
+
+A little library for working with percentages.
+
+
+Feature Tour
+------------
+
+The `Percentage` method converts Integer/BigDecimal/Rational objects
+to percentage objects with values that you would expect:
+
+```ruby
+Percentage(50)  # => 50%
+
+Percentage(BigDecimal('17.5'))  # => 17.5%
+
+Percentage(Rational(25, 2))  # => 12.5%
+```
+
+Percentage objects can also be constructed directly, but in this case
+BigDecimal/Rational values are treated as fractions, for example:
+
+```ruby
+Percentage.new(50)  # => 50%
+
+Percentage.new(BigDecimal('0.175'))  # => 17.5%
+
+Percentage.new(Rational(1, 8))  # => 12.5%
+```
+
+As with other numerics, percentage objects are conceptually immutable.
+Common numeric functionality like `to_i`, `to_f`, `to_s`, `to_r`, `zero?`,
+and equality/comparison methods are defined.
+
+Percentages can be added together:
+
+```ruby
+Percentage(10) + Percentage(20)  # => 30%
+```
+
+They can also be "scaled up" using the `scale` method:
+
+```ruby
+Percentage(10).scale(5)  # => 50%
+```
+
+Multiplication is then defined using the fractional value of the percentage.
+BigDecimal objects can't be coerced into rational objects, so the order of
+the multiplication will matter in some cases. For example:
+
+```ruby
+Percentage(50) * 10  # => (5/1)
+
+Percentage(50) * Percentage(10)  # => 5.0%
+
+BigDecimal('150.00') * Percentage(50)  # => BigDecimal('75.00')
+
+Percentage(50) * BigDecimal('150.00')  # raises TypeError
+```
+
+
+Bonus Extras
+------------
+
+Some shortcut methods are defined on Integer/BigDecimal for convenience:
+
+```ruby
+50.percent  # => 50%
+
+50.percent_of(BigDecimal(150))  # => BigDecimal('75.00')
+
+10.percent_of(100)  # => (10/1)
+
+5.as_percentage_of(10)  # => 50.0%
+```
+
+And there's also a class method for calculating the percentage
+change between two values:
+
+```ruby
+Percentage.change(2, 3)  # => 50.0%
+```

data/Rakefile.rb

@@ -0,0 +1,7 @@
+require 'rake/testtask'
+
+task :default => :spec
+
+Rake::TestTask.new(:spec) do |t|
+  t.test_files = FileList['spec/*_spec.rb']
+end

data/lib/percentage.rb

@@ -0,0 +1,132 @@
+require 'rational'
+require 'bigdecimal'
+
+class Percentage
+  attr_reader :value
+
+  include Comparable
+
+  def initialize(value)
+    @value = value
+  end
+
+  def to_i
+    (fractional_value * 100).to_i
+  end
+
+  def to_f
+    (fractional_value * 100).to_f
+  end
+
+  def to_s
+    "#{string_value}%"
+  end
+
+  def to_r
+    fractional_value.to_r
+  end
+
+  def zero?
+    @value.zero?
+  end
+
+  def <=>(object)
+    if self.class === object
+      fractional_value <=> object.fractional_value
+    elsif Numeric === object
+      fractional_value <=> object
+    end
+  end
+
+  def eql?(object)
+    object.instance_of?(self.class) && @value.eql?(object.value)
+  end
+
+  def hash
+    @value.hash
+  end
+
+  def +(object)
+    if self.class === object
+      if @value.integer? ^ object.value.integer?
+        self.class.new(fractional_value + object.fractional_value)
+      else
+        self.class.new(@value + object.value)
+      end
+    else
+      raise TypeError, "cannot add #{object.class} to #{self.class}"
+    end
+  end
+
+  def *(object)
+    case object
+    when self.class
+      self.class.new(fractional_value.to_r * object.fractional_value)
+    else
+      fractional_value.coerce(object).inject(&:*)
+    end
+  end
+
+  def coerce(other)
+    case other
+    when Numeric
+      return fractional_value, other
+    else
+      raise TypeError, "#{self.class} can't be coerced into #{other.class}"
+    end
+  end
+
+  def truncate(n)
+    self.class.new(fractional_value.truncate(n))
+  end
+
+  def scale(n)
+    self.class.new(@value * n)
+  end
+
+  protected
+
+  def fractional_value
+    @fractional_value ||= @value.integer? ? Rational(@value, 100) : @value
+  end
+
+  private
+
+  def string_value
+    if @value.integer?
+      @value.to_s
+    elsif BigDecimal === @value
+      (@value * 100).to_s('F')
+    else
+      BigDecimal(@value * 100, _precision=10).to_s('F')
+    end
+  end
+end
+
+def Percentage(object)
+  Percentage.new(object.integer? ? object : object / 100)
+end
+
+def Percentage.change(a, b)
+  Percentage.new((b - a).to_r / a)
+end
+
+class BigDecimal
+  def as_percentage_of(n)
+    Percentage.new(self / n)
+  end
+end
+
+class Integer
+  def percent
+    Percentage.new(self)
+  end
+
+  def percent_of(n)
+    n * Percentage.new(self)
+  end
+
+  def as_percentage_of(n)
+    Percentage.new(Rational(self, n))
+  end
+end

data/percentage.gemspec

@@ -0,0 +1,12 @@
+Gem::Specification.new do |s|
+  s.name = 'percentage'
+  s.version = '1.0.0'
+  s.platform = Gem::Platform::RUBY
+  s.authors = ['Tim Craft']
+  s.email = ['mail@timcraft.com']
+  s.homepage = 'http://github.com/timcraft/percentage'
+  s.description = 'A little library for working with percentages'
+  s.summary = 'See description'
+  s.files = Dir.glob('{lib,spec}/**/*') + %w(README.md Rakefile.rb percentage.gemspec)
+  s.require_path = 'lib'
+end

data/spec/percentage_spec.rb

@@ -0,0 +1,352 @@
+require 'minitest/autorun'
+
+require_relative '../lib/percentage'
+
+describe 'Percentage object' do
+  it 'is comparable' do
+    percentage = Percentage.new(Rational(1, 8))
+
+    (Comparable === percentage).must_equal(true)
+  end
+
+  it 'is comparable to other objects of the same class' do
+    (Percentage.new(Rational(1, 8)) > Percentage.new(Rational(1, 10))).must_equal(true)
+  end
+
+  it 'is comparable to other numeric objects' do
+    (Percentage.new(Rational(1, 8)) > Rational(1, 10)).must_equal(true)
+  end
+
+  it 'can be used as a hash key' do
+    hash = Hash.new(0)
+
+    3.times { hash[Percentage.new(Rational(1, 10))] += 1 }
+
+    hash[Percentage.new(Rational(1, 10))].must_equal(3)
+  end
+end
+
+describe 'Percentage object initialized with an integer value' do
+  before do
+    @percentage = Percentage.new(10)
+  end
+
+  describe 'value method' do
+    it 'returns the value passed to the constructor' do
+      @percentage.value.must_equal(10)
+    end
+  end
+
+  describe 'to_i method' do
+    it 'returns the integer value of the percentage' do
+      @percentage.to_i.must_equal(10)
+    end
+  end
+
+  describe 'to_f method' do
+    it 'returns the float value of the percentage' do
+      @percentage.to_f.must_be_close_to(10.0)
+    end
+  end
+
+  describe 'to_s method' do
+    it 'returns the integer value of the percentage suffixed with the percent symbol' do
+      @percentage.to_s.must_equal('10%')
+    end
+  end
+
+  describe 'to_r method' do
+    it 'returns the rational value of the percentage' do
+      @percentage.to_r.must_equal(Rational(1, 10))
+    end
+  end
+
+  describe 'zero query method' do
+    it 'returns true if the percentage has a zero value' do
+      Percentage.new(0).zero?.must_equal(true)
+    end
+
+    it 'returns false otherwise' do
+      @percentage.zero?.must_equal(false)
+    end
+  end
+
+  describe 'truncate method' do
+    it 'returns a percentage object with a truncated rational value' do
+      percentage = @percentage.truncate(1)
+      percentage.must_be_instance_of(Percentage)
+      percentage.value.must_equal(Rational(1, 10))
+    end
+  end
+
+  describe 'scale method' do
+    it 'returns a percentage object with the value of the percentage multiplied by the integer argument' do
+      percentage = @percentage.scale(2)
+      percentage.must_be_instance_of(Percentage)
+      percentage.value.must_equal(20)
+    end
+  end
+end
+
+describe 'Percentage object initialized with a rational value' do
+  before do
+    @percentage = Percentage.new(Rational(1, 8))
+  end
+
+  describe 'value method' do
+    it 'returns the value passed to the constructor' do
+      @percentage.value.must_equal(Rational(1, 8))
+    end
+  end
+
+  describe 'to_i method' do
+    it 'returns the integer value of the percentage' do
+      @percentage.to_i.must_equal(12)
+    end
+  end
+
+  describe 'to_f method' do
+    it 'returns the float value of the percentage' do
+      @percentage.to_f.must_be_close_to(12.5)
+    end
+  end
+
+  describe 'to_s method' do
+    it 'returns the decimal value of the percentage suffixed with the percent symbol' do
+      @percentage.to_s.must_equal('12.5%')
+    end
+  end
+
+  describe 'to_r method' do
+    it 'returns the rational value of the percentage' do
+      @percentage.to_r.must_equal(Rational(1, 8))
+    end
+  end
+
+  describe 'zero query method' do
+    it 'returns true if the percentage has a zero value' do
+      Percentage.new(Rational(0)).zero?.must_equal(true)
+    end
+
+    it 'returns false otherwise' do
+      @percentage.zero?.must_equal(false)
+    end
+  end
+
+  describe 'truncate method' do
+    it 'returns a percentage object with a truncated rational value' do
+      percentage = @percentage.truncate(1)
+      percentage.must_be_instance_of(Percentage)
+      percentage.value.must_equal(Rational(1, 10))
+    end
+  end
+
+  describe 'scale method' do
+    it 'returns a percentage object with the value of the percentage multiplied by the integer argument' do
+      percentage = @percentage.scale(2)
+      percentage.must_be_instance_of(Percentage)
+      percentage.value.must_equal(Rational(1, 4))
+    end
+  end
+end
+
+describe 'Percentage object initialized with a decimal value' do
+  before do
+    @percentage = Percentage.new(BigDecimal('0.175'))
+  end
+
+  describe 'value method' do
+    it 'returns the value passed to the constructor' do
+      @percentage.value.must_equal(BigDecimal('0.175'))
+    end
+  end
+
+  describe 'to_i method' do
+    it 'returns the integer value of the percentage' do
+      @percentage.to_i.must_equal(17)
+    end
+  end
+
+  describe 'to_f method' do
+    it 'returns the float value of the percentage' do
+      @percentage.to_f.must_be_close_to(17.5)
+    end
+  end
+
+  describe 'to_s method' do
+    it 'returns the decimal value of the percentage suffixed with the percent symbol' do
+      @percentage.to_s.must_equal('17.5%')
+    end
+  end
+
+  describe 'to_r method' do
+    it 'returns the rational value of the percentage' do
+      @percentage.to_r.must_equal(Rational(175, 1000))
+    end
+  end
+
+  describe 'zero query method' do
+    it 'returns true if the percentage has a zero value' do
+      Percentage.new(BigDecimal(0)).zero?.must_equal(true)
+    end
+
+    it 'returns false otherwise' do
+      @percentage.zero?.must_equal(false)
+    end
+  end
+
+  describe 'truncate method' do
+    it 'returns a percentage object with a truncated decimal value' do
+      percentage = @percentage.truncate(1)
+      percentage.must_be_instance_of(Percentage)
+      percentage.value.must_equal(BigDecimal('0.1'))
+    end
+  end
+
+  describe 'scale method' do
+    it 'returns a percentage object with the value of the percentage multiplied by the integer argument' do
+      percentage = @percentage.scale(2)
+      percentage.must_be_instance_of(Percentage)
+      percentage.value.must_equal(BigDecimal('0.35'))
+    end
+  end
+end
+
+describe 'Addition of percentage objects' do
+  it 'returns a percentage object with the value of the two percentages added together' do
+    percentage = Percentage.new(10) + Percentage.new(10)
+    percentage.must_be_instance_of(Percentage)
+    percentage.value.must_equal(20)
+
+    percentage = Percentage.new(Rational(1, 8)) + Percentage.new(10)
+    percentage.must_be_instance_of(Percentage)
+    percentage.value.must_equal(Rational(9, 40))
+
+    percentage = Percentage.new(BigDecimal('0.175')) + Percentage.new(BigDecimal('0.025'))
+    percentage.must_be_instance_of(Percentage)
+    percentage.value.must_equal(BigDecimal('0.2'))
+  end
+end
+
+describe 'Addition of percentage object with another type of object' do
+  it 'raises an exception' do
+    proc { Percentage.new(10) + 5 }.must_raise(TypeError)
+  end
+end
+
+describe 'Multiplication of percentage objects' do
+  it 'returns a percentage object with the fractional value of the two percentages multiplied together' do
+    percentage = Percentage.new(10) * Percentage.new(10)
+    percentage.must_be_instance_of(Percentage)
+    percentage.value.must_equal(Rational(1, 100))
+
+    percentage = Percentage.new(Rational(1, 8)) * Percentage.new(10)
+    percentage.must_be_instance_of(Percentage)
+    percentage.value.must_equal(Rational(1, 80))
+
+    percentage = Percentage.new(BigDecimal('0.175')) * Percentage.new(10)
+    percentage.must_be_instance_of(Percentage)
+    percentage.value.must_equal(Rational(7, 400))
+  end
+end
+
+describe 'Multiplication of a decimal object with a percentage object' do
+  it 'returns a decimal object with the value of the decimal multiplied by the fractional value of the percentage' do
+    percentage, decimal = Percentage.new(BigDecimal('0.175')), BigDecimal('99.00')
+
+    (decimal * percentage).must_equal(BigDecimal('17.325'))
+    (percentage * decimal).must_equal(BigDecimal('17.325'))
+  end
+end
+
+describe 'Percentage object equality' do
+  describe 'double equals method' do
+    it 'returns true for percentage objects with the same fractional value' do
+      (Percentage.new(50) == Percentage.new(50)).must_equal(true)
+      (Percentage.new(50) == Percentage.new(Rational(1, 2))).must_equal(true)
+      (Percentage.new(50) == Percentage.new(BigDecimal('0.5'))).must_equal(true)
+    end
+
+    it 'returns false otherwise' do
+      (Percentage.new(50) == Percentage.new(100)).must_equal(false)
+    end
+  end
+
+  describe 'eql query method' do
+    it 'returns true for percentage objects with exactly the same fractional value' do
+      (Percentage.new(50).eql? Percentage.new(50)).must_equal(true)
+    end
+
+    it 'returns false otherwise' do
+      (Percentage.new(50).eql? Percentage.new(Rational(1, 2))).must_equal(false)
+      (Percentage.new(50).eql? Percentage.new(BigDecimal('0.5'))).must_equal(false)
+      (Percentage.new(50).eql? Percentage.new(100)).must_equal(false)
+    end
+  end
+end
+
+describe 'Percentage method' do
+  describe 'when called with an integer argument' do
+    it 'returns a percentage object with the integer value' do
+      percentage = Percentage(10)
+      percentage.must_be_instance_of(Percentage)
+      percentage.value.must_equal(10)
+    end
+  end
+
+  describe 'when called with a decimal argument' do
+    it 'returns a percentage object with the value of the argument divided by 100' do
+      percentage = Percentage(BigDecimal('17.5'))
+      percentage.must_be_instance_of(Percentage)
+      percentage.value.must_equal(BigDecimal('0.175'))
+    end
+  end
+
+  describe 'when called with a rational argument' do
+    it 'returns a percentage object with the value of the argument divided by 100' do
+      percentage = Percentage(Rational(100, 3))
+      percentage.must_be_instance_of(Percentage)
+      percentage.value.must_equal(Rational(1, 3))
+    end
+  end
+end
+
+describe 'Percentage change method' do
+  it 'returns the difference between the arguments as a percentage of the first argument' do
+    percentage = Percentage.change(2, 3)
+    percentage.must_be_instance_of(Percentage)
+    percentage.must_equal(Percentage.new(50))
+  end
+end
+
+describe 'BigDecimal as_percentage_of method' do
+  it 'returns a percentage object with the value of the decimal divided by the argument' do
+    percentage = BigDecimal('50.00').as_percentage_of(BigDecimal('100.00'))
+    percentage.must_be_instance_of(Percentage)
+    percentage.value.must_equal(BigDecimal('0.5'))
+  end
+end
+
+describe 'Integer percent method' do
+  it 'returns a percentage object with the value of the integer' do
+    percentage = 10.percent
+    percentage.must_be_instance_of(Percentage)
+    percentage.value.must_equal(10)
+  end
+end
+
+describe 'Integer percent_of method' do
+  it 'returns the value of the receiver as a percentage multiplied by the argument' do
+    10.percent_of(100).must_equal(10)
+    10.percent_of(BigDecimal(15)).must_equal(BigDecimal('1.5'))
+    10.percent_of(Rational(150, 2)).must_equal(Rational(15, 2))
+  end
+end
+
+describe 'Integer as_percentage_of method' do
+  it 'returns a percentage object with the value of the integer divided by the argument' do
+    percentage = 10.as_percentage_of(20)
+    percentage.must_be_instance_of(Percentage)
+    percentage.value.must_equal(Rational(1, 2))
+  end
+end

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification
+name: percentage
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Tim Craft
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-11-29 00:00:00.000000000 Z
+dependencies: []
+description: A little library for working with percentages
+email:
+- mail@timcraft.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/percentage.rb
+- spec/percentage_spec.rb
+- README.md
+- Rakefile.rb
+- percentage.gemspec
+homepage: http://github.com/timcraft/percentage
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: See description
+test_files: []
+has_rdoc: