money 6.2.1 → 6.3.0

data/config/currency_non_iso.json

@@ -25,6 +25,7 @@
     "html_entity": "£",
     "decimal_mark": ".",
     "thousands_separator": ",",
-    "iso_numeric": ""
+    "iso_numeric": "",
+    "smallest_denomination": 1
   }
 }

data/lib/money/currency.rb

@@ -151,10 +151,12 @@ class Money
     # of the whole unit.
     # @attr_reader [Boolean] symbol_first Should the currency symbol precede
     # the amount, or should it come after?
+    # @attr_reader [Integer] smallest_denomination Smallest amount of cash 
+    # possible (in the subunit of this currency)
 
     attr_reader :id, :priority, :iso_code, :iso_numeric, :name, :symbol,
       :html_entity, :subunit, :subunit_to_unit, :decimal_mark,
-      :thousands_separator, :symbol_first
+      :thousands_separator, :symbol_first, :smallest_denomination
 
     alias_method :separator, :decimal_mark
     alias_method :delimiter, :thousands_separator
@@ -186,6 +188,7 @@ class Money
         @decimal_mark = data[:decimal_mark]
         @thousands_separator = data[:thousands_separator]
         @iso_numeric = data[:iso_numeric]
+        @smallest_denomination = data[:smallest_denomination]
       else
         raise UnknownCurrency, "Unknown currency '#{id}'"
       end
@@ -268,7 +271,7 @@ class Money
     # @example
     #   Money::Currency.new(:usd) #=> #<Currency id: usd ...>
     def inspect
-      "#<#{self.class.name} id: #{id}, priority: #{priority}, symbol_first: #{symbol_first}, thousands_separator: #{thousands_separator}, html_entity: #{html_entity}, decimal_mark: #{decimal_mark}, name: #{name}, symbol: #{symbol}, subunit_to_unit: #{subunit_to_unit}, exponent: #{exponent}, iso_code: #{iso_code}, iso_numeric: #{iso_numeric}, subunit: #{subunit}>"
+      "#<#{self.class.name} id: #{id}, priority: #{priority}, symbol_first: #{symbol_first}, thousands_separator: #{thousands_separator}, html_entity: #{html_entity}, decimal_mark: #{decimal_mark}, name: #{name}, symbol: #{symbol}, subunit_to_unit: #{subunit_to_unit}, exponent: #{exponent}, iso_code: #{iso_code}, iso_numeric: #{iso_numeric}, subunit: #{subunit}, smallest_denomination: #{smallest_denomination}>"
     end
 
     # Returns a string representation corresponding to the upcase +id+

data/lib/money/money.rb

@@ -15,6 +15,9 @@ require "money/money/formatting"
 # @see http://en.wikipedia.org/wiki/Money
 class Money
   include Comparable, Money::Arithmetic, Money::Formatting
+  
+  # Raised when smallest denomination of a currency is not defined
+  class UndefinedSmallestDenomination < StandardError; end
 
   # Convenience method for fractional part of the amount. Synonym of #fractional
   #
@@ -47,11 +50,28 @@ class Money
     # from YAML, @fractional can end up being set to a Float.
     fractional = as_d(@fractional)
 
-    if self.class.infinite_precision
-      fractional
-    else
-      fractional.round(0, self.class.rounding_mode).to_i
+    return_value(fractional)
+  end
+  
+  # Round a given amount of money to the nearest possible amount in cash value. For
+  # example, in Swiss francs (CHF), the smallest possible amount of cash value is
+  # CHF 0.05. Therefore, this method rounds CHF 0.07 to CHF 0.05, and CHF 0.08 to
+  # CHF 0.10.
+  #
+  # @return [Integer] when infinite_precision is false
+  # @return [BigDecimal] when infinite_precision is true
+  #
+  # @see infinite_precision
+  def round_to_nearest_cash_value
+    unless self.currency.smallest_denomination
+      raise UndefinedSmallestDenomination, 'Smallest denomination of this currency is not defined'
     end
+    
+    fractional = as_d(@fractional)
+    smallest_denomination = as_d(self.currency.smallest_denomination)
+    rounded_value = (fractional / smallest_denomination).round(0, self.class.rounding_mode) * smallest_denomination
+    
+    return_value(rounded_value)
   end
 
   # @attr_reader [Currency] currency The currency the money is in.
@@ -455,7 +475,7 @@ class Money
     exchange_to("EUR")
   end
 
-  # Allocates money between different parties without loosing pennies.
+  # Allocates money between different parties without losing pennies.
   # After the mathmatically split has been performed, left over pennies will
   # be distributed round-robin amongst the parties. This means that parties
   # listed first will likely recieve more pennies then ones that are listed later
@@ -484,7 +504,7 @@ class Money
     amounts.collect { |fractional| Money.new(fractional, currency) }
   end
 
-  # Split money amongst parties evenly without loosing pennies.
+  # Split money amongst parties evenly without losing pennies.
   #
   # @param [Numeric] num number of parties.
   #
@@ -598,4 +618,12 @@ class Money
       index < remainder ? high : low
     end
   end
+  
+  def return_value(value)
+    if self.class.infinite_precision
+      value
+    else
+      value.round(0, self.class.rounding_mode).to_i
+    end
+  end
 end

data/lib/money/version.rb

@@ -1,3 +1,3 @@
 class Money
-  VERSION = "6.2.1"
+  VERSION = "6.3.0"
 end

data/spec/currency_spec.rb

@@ -4,7 +4,7 @@ require "spec_helper"
 
 describe Money::Currency do
 
-  FOO = '{ "priority": 1, "iso_code": "FOO", "iso_numeric": "840", "name": "United States Dollar", "symbol": "$", "subunit": "Cent", "subunit_to_unit": 450, "symbol_first": true, "html_entity": "$", "decimal_mark": ".", "thousands_separator": "," }'
+  FOO = '{ "priority": 1, "iso_code": "FOO", "iso_numeric": "840", "name": "United States Dollar", "symbol": "$", "subunit": "Cent", "subunit_to_unit": 450, "symbol_first": true, "html_entity": "$", "decimal_mark": ".", "thousands_separator": ",", "smallest_denomination": 1 }'
 
   describe ".find" do
     before :each do
@@ -75,15 +75,16 @@ describe Money::Currency do
   describe "#initialize" do
     it "lookups data from loaded config" do
       currency = Money::Currency.new("USD")
-      expect(currency.id).to                  eq :usd
-      expect(currency.priority).to            eq 1
-      expect(currency.iso_code).to            eq "USD"
-      expect(currency.iso_numeric).to         eq "840"
-      expect(currency.name).to                eq "United States Dollar"
-      expect(currency.decimal_mark).to        eq "."
-      expect(currency.separator).to           eq "."
-      expect(currency.thousands_separator).to eq ","
-      expect(currency.delimiter).to           eq ","
+      expect(currency.id).to                    eq :usd
+      expect(currency.priority).to              eq 1
+      expect(currency.iso_code).to              eq "USD"
+      expect(currency.iso_numeric).to           eq "840"
+      expect(currency.name).to                  eq "United States Dollar"
+      expect(currency.decimal_mark).to          eq "."
+      expect(currency.separator).to             eq "."
+      expect(currency.thousands_separator).to   eq ","
+      expect(currency.delimiter).to             eq ","
+      expect(currency.smallest_denomination).to eq 1
     end
 
     it "raises UnknownMoney::Currency with unknown currency" do
@@ -144,7 +145,7 @@ describe Money::Currency do
 
   describe "#inspect" do
     it "works as documented" do
-      expect(Money::Currency.new(:usd).inspect).to eq %Q{#<Money::Currency id: usd, priority: 1, symbol_first: true, thousands_separator: ,, html_entity: $, decimal_mark: ., name: United States Dollar, symbol: $, subunit_to_unit: 100, exponent: 2.0, iso_code: USD, iso_numeric: 840, subunit: Cent>}
+      expect(Money::Currency.new(:usd).inspect).to eq %Q{#<Money::Currency id: usd, priority: 1, symbol_first: true, thousands_separator: ,, html_entity: $, decimal_mark: ., name: United States Dollar, symbol: $, subunit_to_unit: 100, exponent: 2.0, iso_code: USD, iso_numeric: 840, subunit: Cent, smallest_denomination: 1>}
     end
   end
 

data/spec/money/formatting_spec.rb

@@ -4,9 +4,9 @@ require "spec_helper"
 
 describe Money, "formatting" do
 
-  BAR = '{ "priority": 1, "iso_code": "BAR", "iso_numeric": "840", "name": "Dollar with 4 decimal places", "symbol": "$", "subunit": "Cent", "subunit_to_unit": 10000, "symbol_first": true, "html_entity": "$", "decimal_mark": ".", "thousands_separator": "," }'
-  INDIAN_BAR = '{ "priority": 1, "iso_code": "INDIAN_BAR", "iso_numeric": "840", "name": "Dollar with 4 decimal places", "symbol": "$", "subunit": "Cent", "subunit_to_unit": 10000, "symbol_first": true, "html_entity": "$", "decimal_mark": ".", "thousands_separator": ",", "south_asian_number_formatting": true}'
-  EU4 = '{ "priority": 1, "iso_code": "EU4", "iso_numeric": "841", "name": "Euro with 4 decimal places", "symbol": "€", "subunit": "Cent", "subunit_to_unit": 10000, "symbol_first": true, "html_entity": "€", "decimal_mark": ",", "thousands_separator": "." }'
+  BAR = '{ "priority": 1, "iso_code": "BAR", "iso_numeric": "840", "name": "Dollar with 4 decimal places", "symbol": "$", "subunit": "Cent", "subunit_to_unit": 10000, "symbol_first": true, "html_entity": "$", "decimal_mark": ".", "thousands_separator": ",", "smallest_denomination": 1 }'
+  INDIAN_BAR = '{ "priority": 1, "iso_code": "INDIAN_BAR", "iso_numeric": "840", "name": "Dollar with 4 decimal places", "symbol": "$", "subunit": "Cent", "subunit_to_unit": 10000, "symbol_first": true, "html_entity": "$", "decimal_mark": ".", "thousands_separator": ",", "south_asian_number_formatting": true, "smallest_denomination": 1}'
+  EU4 = '{ "priority": 1, "iso_code": "EU4", "iso_numeric": "841", "name": "Euro with 4 decimal places", "symbol": "€", "subunit": "Cent", "subunit_to_unit": 10000, "symbol_first": true, "html_entity": "€", "decimal_mark": ",", "thousands_separator": ".", "smallest_denomination": 1 }'
 
   context "without i18n" do
     subject(:money) { Money.empty("USD") }

data/spec/money_spec.rb

@@ -293,6 +293,89 @@ YAML
       end
     end
   end
+  
+  describe "#round_to_nearest_cash_value" do
+    it "rounds to the nearest possible cash value" do
+      money = Money.new(2350, "AED")
+      expect(money.round_to_nearest_cash_value).to eq 2350
+      
+      money = Money.new(-2350, "AED")
+      expect(money.round_to_nearest_cash_value).to eq -2350
+      
+      money = Money.new(2213, "AED")
+      expect(money.round_to_nearest_cash_value).to eq 2225
+      
+      money = Money.new(-2213, "AED")
+      expect(money.round_to_nearest_cash_value).to eq -2225
+      
+      money = Money.new(2212, "AED")
+      expect(money.round_to_nearest_cash_value).to eq 2200
+      
+      money = Money.new(-2212, "AED")
+      expect(money.round_to_nearest_cash_value).to eq -2200
+    
+      money = Money.new(178, "CHF")
+      expect(money.round_to_nearest_cash_value).to eq 180
+      
+      money = Money.new(-178, "CHF")
+      expect(money.round_to_nearest_cash_value).to eq -180
+      
+      money = Money.new(177, "CHF")
+      expect(money.round_to_nearest_cash_value).to eq 175
+      
+      money = Money.new(-177, "CHF")
+      expect(money.round_to_nearest_cash_value).to eq -175
+      
+      money = Money.new(175, "CHF")
+      expect(money.round_to_nearest_cash_value).to eq 175
+      
+      money = Money.new(-175, "CHF")
+      expect(money.round_to_nearest_cash_value).to eq -175
+      
+      money = Money.new(299, "USD")
+      expect(money.round_to_nearest_cash_value).to eq 299
+      
+      money = Money.new(-299, "USD")
+      expect(money.round_to_nearest_cash_value).to eq -299
+      
+      money = Money.new(300, "USD")
+      expect(money.round_to_nearest_cash_value).to eq 300
+      
+      money = Money.new(-300, "USD")
+      expect(money.round_to_nearest_cash_value).to eq -300
+      
+      money = Money.new(301, "USD")
+      expect(money.round_to_nearest_cash_value).to eq 301
+      
+      money = Money.new(-301, "USD")
+      expect(money.round_to_nearest_cash_value).to eq -301
+    end
+    
+    it "raises an exception if smallest denomination is not defined" do
+      money = Money.new(100, "XAG")
+      expect {money.round_to_nearest_cash_value}.to raise_error(Money::UndefinedSmallestDenomination)
+    end
+    
+    it "returns a Fixnum when infinite_precision is not set" do
+      money = Money.new(100, "USD")
+      expect(money.round_to_nearest_cash_value).to be_a Fixnum
+    end
+  
+    context "with infinite_precision" do
+      before do
+        Money.infinite_precision = true
+      end
+
+      after do
+        Money.infinite_precision = false
+      end
+
+      it "returns a BigDecimal" do
+        money = Money.new(100, "EUR")
+        expect(money.round_to_nearest_cash_value).to be_a BigDecimal
+      end
+    end
+  end
 
   describe "#amount" do
     it "returns the amount of cents as dollars" do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: money
 version: !ruby/object:Gem::Version
-  version: 6.2.1
+  version: 6.3.0
 platform: ruby
 authors:
 - Shane Emmons
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-09-08 00:00:00.000000000 Z
+date: 2014-09-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: i18n