money 6.7.1 → 6.13.0

data/lib/money/money.rb

@@ -3,7 +3,9 @@ require "money/bank/variable_exchange"
 require "money/bank/single_currency"
 require "money/money/arithmetic"
 require "money/money/constructors"
-require "money/money/formatting"
+require "money/money/formatter"
+require "money/money/allocation"
+require "money/money/locale_backend"
 
 # "Money is any object or record that is generally accepted as payment for
 # goods and services and repayment of debts in a given socio-economic context
@@ -17,7 +19,6 @@ require "money/money/formatting"
 class Money
   include Comparable
   include Money::Arithmetic
-  include Money::Formatting
   extend Constructors
 
   # Raised when smallest denomination of a currency is not defined
@@ -105,9 +106,9 @@ class Money
     #   @see +Money::Formatting#format+ for more details.
     #
     #   @example
-    #     Money.default_formatting_rules = { :display_free => true }
+    #     Money.default_formatting_rules = { display_free: true }
     #     Money.new(0, "USD").format                          # => "free"
-    #     Money.new(0, "USD").format(:display_free => false)  # => "$0.00"
+    #     Money.new(0, "USD").format(display_free: false)  # => "$0.00"
     #
     # @!attribute [rw] use_i18n
     #   @return [Boolean] Use this to disable i18n even if it's used by other
@@ -117,10 +118,11 @@ class Money
     #   @return [Boolean] Use this to enable infinite precision cents
     #
     # @!attribute [rw] conversion_precision
-    #   @return [Fixnum] Use this to specify precision for converting Rational
+    #   @return [Integer] Use this to specify precision for converting Rational
     #     to BigDecimal
     attr_accessor :default_bank, :default_formatting_rules,
-      :use_i18n, :infinite_precision, :conversion_precision
+      :use_i18n, :infinite_precision, :conversion_precision,
+      :locale_backend
 
     # @attr_writer rounding_mode Use this to specify the rounding mode
     #
@@ -141,6 +143,18 @@ class Money
     end
   end
 
+  def self.locale_backend=(value)
+    @locale_backend = value ? LocaleBackend.find(value) : nil
+  end
+
+  def self.use_i18n=(value)
+    if value
+      warn '[DEPRECATION] `use_i18n` is deprecated - use `Money.locale_backend = :i18n` instead'
+    end
+
+    @use_i18n = value
+  end
+
   def self.setup_defaults
     # Set the default bank for creating new +Money+ objects.
     self.default_bank = Bank::VariableExchange.instance
@@ -149,7 +163,10 @@ class Money
     self.default_currency = Currency.new("USD")
 
     # Default to using i18n
-    self.use_i18n = true
+    @use_i18n = true
+
+    # Default to using legacy locale backend
+    self.locale_backend = :legacy
 
     # Default to not using infinite precision cents
     self.infinite_precision = false
@@ -177,9 +194,9 @@ class Money
   #
   # @example
   #   fee = Money.rounding_mode(BigDecimal::ROUND_HALF_UP) do
-  #     Money.new(1200) * BigDecimal.new('0.029')
+  #     Money.new(1200) * BigDecimal('0.029')
   #   end
-  def self.rounding_mode(mode=nil)
+  def self.rounding_mode(mode = nil)
     if mode.nil?
       Thread.current[:money_rounding_mode] || @rounding_mode
     else
@@ -228,8 +245,9 @@ class Money
   #
   # @see #initialize
   def self.from_amount(amount, currency = default_currency, bank = default_bank)
-    Numeric === amount or raise ArgumentError, "'amount' must be numeric"
-    currency = Currency.wrap(currency)
+    raise ArgumentError, "'amount' must be numeric" unless Numeric === amount
+
+    currency = Currency.wrap(currency) || Money.default_currency
     value = amount.to_d * currency.subunit_to_unit
     value = value.round(0, rounding_mode) unless infinite_precision
     new(value, currency, bank)
@@ -271,7 +289,7 @@ class Money
   # @return [BigDecimal]
   #
   # @example
-  #   Money.new(1_00, "USD").dollars   # => BigDecimal.new("1.00")
+  #   Money.new(1_00, "USD").dollars   # => BigDecimal("1.00")
   #
   # @see #amount
   # @see #to_d
@@ -286,7 +304,7 @@ class Money
   # @return [BigDecimal]
   #
   # @example
-  #   Money.new(1_00, "USD").amount    # => BigDecimal.new("1.00")
+  #   Money.new(1_00, "USD").amount    # => BigDecimal("1.00")
   #
   # @see #to_d
   # @see #fractional
@@ -302,6 +320,7 @@ class Money
   # @example
   #   Money.new(100, :USD).currency_as_string #=> "USD"
   def currency_as_string
+    warn "[DEPRECATION] `currency_as_string` is deprecated. Please use `.currency.to_s` instead."
     currency.to_s
   end
 
@@ -314,13 +333,15 @@ class Money
   # @example
   #   Money.new(100).currency_as_string("CAD") #=> #<Money::Currency id: cad>
   def currency_as_string=(val)
+    warn "[DEPRECATION] `currency_as_string=` is deprecated - Money instances are immutable." \
+      " Please use `with_currency` instead."
     @currency = Currency.wrap(val)
   end
 
-  # Returns a Fixnum hash value based on the +fractional+ and +currency+ attributes
+  # Returns a Integer hash value based on the +fractional+ and +currency+ attributes
   # in order to use functions like & (intersection), group_by, etc.
   #
-  # @return [Fixnum]
+  # @return [Integer]
   #
   # @example
   #   Money.new(100).hash #=> 908351
@@ -352,19 +373,10 @@ class Money
   # @example
   #   Money.ca_dollar(100).to_s #=> "1.00"
   def to_s
-    unit, subunit, fraction = strings_from_fractional
-
-    str = if currency.decimal_places == 0
-            if fraction == ""
-              unit
-            else
-              "#{unit}#{decimal_mark}#{fraction}"
-            end
-          else
-            "#{unit}#{decimal_mark}#{pad_subunit(subunit)}#{fraction}"
-          end
-
-    fractional < 0 ? "-#{str}" : str
+    format thousands_separator: '',
+           no_cents_if_whole: currency.decimal_places == 0,
+           symbol: false,
+           ignore_defaults: true
   end
 
   # Return the amount of money as a BigDecimal.
@@ -372,7 +384,7 @@ class Money
   # @return [BigDecimal]
   #
   # @example
-  #   Money.us_dollar(1_00).to_d #=> BigDecimal.new("1.00")
+  #   Money.us_dollar(1_00).to_d #=> BigDecimal("1.00")
   def to_d
     as_d(fractional) / as_d(currency.subunit_to_unit)
   end
@@ -400,7 +412,22 @@ class Money
     to_d.to_f
   end
 
-  # Conversation to +self+.
+  # Returns a new Money instance in a given currency leaving the amount intact
+  # and not performing currency conversion.
+  #
+  # @param [Currency, String, Symbol] new_currency Currency of the new object.
+  #
+  # @return [self]
+  def with_currency(new_currency)
+    new_currency = Currency.wrap(new_currency)
+    if !new_currency || currency == new_currency
+      self
+    else
+      self.class.new(fractional, new_currency, bank)
+    end
+  end
+
+  # Conversion to +self+.
   #
   # @return [self]
   def to_money(given_currency = nil)
@@ -473,52 +500,27 @@ class Money
     exchange_to("EUR")
   end
 
-  # Allocates money between different parties without losing pennies.
-  # After the mathematical split has been performed, leftover pennies will
-  # be distributed round-robin amongst the parties. This means that parties
-  # listed first will likely receive more pennies than ones that are listed later
+  # Splits a given amount in parts without loosing pennies. The left-over pennies will be
+  # distributed round-robin amongst the parties. This means that parties listed first will likely
+  # receive more pennies than ones that are listed later.
   #
-  # @param [Array<Numeric>] splits [0.50, 0.25, 0.25] to give 50% of the cash to party1, 25% to party2, and 25% to party3.
+  # @param [Array<Numeric>, Numeric] pass [2, 1, 1] to give twice as much to party1 as party2 or
+  # party3 which results in 50% of the cash to party1, 25% to party2, and 25% to party3. Passing a
+  # number instead of an array will split the amount evenly (without loosing pennies when rounding).
   #
   # @return [Array<Money>]
   #
   # @example
-  #   Money.new(5,   "USD").allocate([0.3, 0.7])         #=> [Money.new(2), Money.new(3)]
-  #   Money.new(100, "USD").allocate([0.33, 0.33, 0.33]) #=> [Money.new(34), Money.new(33), Money.new(33)]
-  #
-  def allocate(splits)
-    allocations = allocations_from_splits(splits)
-
-    if (allocations - BigDecimal("1")) > Float::EPSILON
-      raise ArgumentError, "splits add to more then 100%"
-    end
-
-    amounts, left_over = amounts_from_splits(allocations, splits)
-
-    unless self.class.infinite_precision
-      left_over.to_i.times { |i| amounts[i % amounts.length] += 1 }
-    end
-
-    amounts.collect { |fractional| self.class.new(fractional, currency) }
-  end
-
-  # Split money amongst parties evenly without losing pennies.
-  #
-  # @param [Numeric] num number of parties.
+  #   Money.new(5,   "USD").allocate([3, 7]) #=> [Money.new(2), Money.new(3)]
+  #   Money.new(100, "USD").allocate([1, 1, 1]) #=> [Money.new(34), Money.new(33), Money.new(33)]
+  #   Money.new(100, "USD").allocate(2) #=> [Money.new(50), Money.new(50)]
+  #   Money.new(100, "USD").allocate(3) #=> [Money.new(34), Money.new(33), Money.new(33)]
   #
-  # @return [Array<Money>]
-  #
-  # @example
-  #   Money.new(100, "USD").split(3) #=> [Money.new(34), Money.new(33), Money.new(33)]
-  def split(num)
-    raise ArgumentError, "need at least one party" if num < 1
-
-    if self.class.infinite_precision
-      split_infinite(num)
-    else
-      split_flat(num)
-    end
+  def allocate(parts)
+    amounts = Money::Allocation.generate(fractional, parts, !Money.infinite_precision)
+    amounts.map { |amount| self.class.new(amount, currency) }
   end
+  alias_method :split, :allocate
 
   # Round the monetary amount to smallest unit of coinage.
   #
@@ -535,85 +537,46 @@ class Money
   # @see
   #   Money.infinite_precision
   #
-  def round(rounding_mode = self.class.rounding_mode)
-    if self.class.infinite_precision
-      self.class.new(fractional.round(0, rounding_mode), self.currency)
-    else
-      self
-    end
-  end
-
-  private
-
-  def as_d(num)
-    if num.respond_to?(:to_d)
-      num.is_a?(Rational) ? num.to_d(self.class.conversion_precision) : num.to_d
-    else
-      BigDecimal.new(num.to_s)
-    end
+  def round(rounding_mode = self.class.rounding_mode, rounding_precision = 0)
+    rounded_amount = as_d(@fractional).round(rounding_precision, rounding_mode)
+    self.class.new(rounded_amount, currency, bank)
   end
 
-  def strings_from_fractional
-    unit, subunit = fractional().abs.divmod(currency.subunit_to_unit)
-
-    if self.class.infinite_precision
-      strings_for_infinite_precision(unit, subunit)
-    else
-      strings_for_base_precision(unit, subunit)
-    end
-  end
-
-  def strings_for_infinite_precision(unit, subunit)
-    subunit, fraction = subunit.divmod(BigDecimal("1"))
-    fraction = fraction.to_s("F")[2..-1] # want fractional part "0.xxx"
-    fraction = "" if fraction =~ /^0+$/
-
-    [unit.to_i.to_s, subunit.to_i.to_s, fraction]
-  end
-
-  def strings_for_base_precision(unit, subunit)
-    [unit.to_s, subunit.to_s, ""]
-  end
-
-  def pad_subunit(subunit)
-    cnt = currency.decimal_places
-    padding = "0" * cnt
-    "#{padding}#{subunit}"[-1 * cnt, cnt]
-  end
-
-  def allocations_from_splits(splits)
-    splits.inject(0) { |sum, n| sum + as_d(n) }
+  # Creates a formatted price string according to several rules.
+  #
+  # @param [Hash] See Money::Formatter for the list of formatting options
+  #
+  # @return [String]
+  #
+  def format(*rules)
+    Money::Formatter.new(self, *rules).to_s
   end
 
-  def amounts_from_splits(allocations, splits)
-    left_over = fractional
-
-    amounts = splits.map do |ratio|
-      if self.class.infinite_precision
-        fractional * ratio
-      else
-        (fractional * ratio / allocations).floor.tap do |frac|
-          left_over -= frac
-        end
-      end
-    end
-
-    [amounts, left_over]
+  # Returns a thousands separator according to the locale
+  #
+  # @return [String]
+  #
+  def thousands_separator
+    (locale_backend && locale_backend.lookup(:thousands_separator, currency)) ||
+      Money::Formatter::DEFAULTS[:thousands_separator]
   end
 
-  def split_infinite(num)
-    amt = div(as_d(num))
-    1.upto(num).map{amt}
+  # Returns a decimal mark according to the locale
+  #
+  # @return [String]
+  #
+  def decimal_mark
+    (locale_backend && locale_backend.lookup(:decimal_mark, currency)) ||
+      Money::Formatter::DEFAULTS[:decimal_mark]
   end
 
-  def split_flat(num)
-    low = self.class.new(fractional / num, currency)
-    high = self.class.new(low.fractional + 1, currency)
-
-    remainder = fractional % num
+  private
 
-    Array.new(num).each_with_index.map do |_, index|
-      index < remainder ? high : low
+  def as_d(num)
+    if num.respond_to?(:to_d)
+      num.is_a?(Rational) ? num.to_d(self.class.conversion_precision) : num.to_d
+    else
+      BigDecimal(num.to_s.empty? ? 0 : num.to_s)
     end
   end
 
@@ -624,4 +587,8 @@ class Money
       value.round(0, self.class.rounding_mode).to_i
     end
   end
+
+  def locale_backend
+    self.class.locale_backend
+  end
 end

data/lib/money/money/allocation.rb

@@ -0,0 +1,37 @@
+# encoding: utf-8
+
+class Money
+  class Allocation
+    # Splits a given amount in parts without loosing pennies.
+    # The left-over pennies will be distributed round-robin amongst the parties. This means that
+    # parties listed first will likely receive more pennies than ones that are listed later.
+    #
+    # The results should always add up to the original amount.
+    #
+    # The parts can be specified as:
+    #   Numeric — performs the split between a given number of parties evenely
+    #   Array<Numeric> — allocates the amounts proportionally to the given array
+    #
+    def self.generate(amount, parts, whole_amounts = true)
+      parts = parts.is_a?(Numeric) ? Array.new(parts, 1) : parts.dup
+
+      raise ArgumentError, 'need at least one party' if parts.empty?
+
+      result = []
+      remaining_amount = amount
+
+      until parts.empty? do
+        parts_sum = parts.inject(0, :+)
+        part = parts.pop
+
+        current_split = remaining_amount * part / parts_sum
+        current_split = current_split.truncate if whole_amounts
+
+        result.unshift current_split
+        remaining_amount -= current_split
+      end
+
+      result
+    end
+  end
+end

data/lib/money/money/arithmetic.rb

@@ -16,7 +16,7 @@ class Money
     # @example
     #    - Money.new(100) #=> #<Money @fractional=-100>
     def -@
-      self.class.new(-fractional, currency)
+      self.class.new(-fractional, currency, bank)
     end
 
     # Checks whether two Money objects have the same currency and the same
@@ -48,16 +48,17 @@ class Money
     #
     # @param [Money] other_money Value to compare with.
     #
-    # @return [Fixnum]
+    # @return [Integer]
     #
     # @raise [TypeError] when other object is not Money
     #
     def <=>(other)
-      if other.respond_to?(:zero?) && other.zero?
+      unless other.is_a?(Money)
+        return unless other.respond_to?(:zero?) && other.zero?
         return other.is_a?(CoercedNumeric) ? 0 <=> fractional : fractional <=> 0
       end
-      return unless other.is_a?(Money)
-      other = other.exchange_to(currency) if nonzero? && currency != other.currency
+      return 0 if zero? && other.zero?
+      other = other.exchange_to(currency)
       fractional <=> other.fractional
     rescue Money::Bank::UnknownRate
     end
@@ -97,6 +98,7 @@ class Money
       fractional < 0
     end
 
+    # @method +(other)
     # Returns a new Money object containing the sum of the two operands' monetary
     # values. If +other_money+ has a different currency then its monetary value
     # is automatically exchanged to this object's currency using +exchange_to+.
@@ -107,13 +109,8 @@ class Money
     #
     # @example
     #   Money.new(100) + Money.new(100) #=> #<Money @fractional=200>
-    def +(other_money)
-      return self if other_money.zero?
-      raise TypeError unless other_money.is_a?(Money)
-      other_money = other_money.exchange_to(currency)
-      self.class.new(fractional + other_money.fractional, currency)
-    end
-
+    #
+    # @method -(other)
     # Returns a new Money object containing the difference between the two
     # operands' monetary values. If +other_money+ has a different currency then
     # its monetary value is automatically exchanged to this object's currency
@@ -125,11 +122,17 @@ class Money
     #
     # @example
     #   Money.new(100) - Money.new(99) #=> #<Money @fractional=1>
-    def -(other_money)
-      return self if other_money.zero?
-      raise TypeError unless other_money.is_a?(Money)
-      other_money = other_money.exchange_to(currency)
-      self.class.new(fractional - other_money.fractional, currency)
+    [:+, :-].each do |op|
+      define_method(op) do |other|
+        unless other.is_a?(Money)
+          if other.zero?
+            return other.is_a?(CoercedNumeric) ? Money.empty(currency).public_send(op, self) : self
+          end
+          raise TypeError
+        end
+        other = other.exchange_to(currency)
+        self.class.new(fractional.public_send(op, other.fractional), currency, bank)
+      end
     end
 
     # Multiplies the monetary value with the given number and returns a new
@@ -149,7 +152,7 @@ class Money
     def *(value)
       value = value.value if value.is_a?(CoercedNumeric)
       if value.is_a? Numeric
-        self.class.new(fractional * value, currency)
+        self.class.new(fractional * value, currency, bank)
       else
         raise TypeError, "Can't multiply a #{self.class.name} by a #{value.class.name}'s value"
       end
@@ -175,7 +178,7 @@ class Money
         fractional / as_d(value.exchange_to(currency).fractional).to_f
       else
         raise TypeError, 'Can not divide by Money' if value.is_a?(CoercedNumeric)
-        self.class.new(fractional / as_d(value), currency)
+        self.class.new(fractional / as_d(value), currency, bank)
       end
     end
 
@@ -195,9 +198,9 @@ class Money
     # Divide money by money or fixnum and return array containing quotient and
     # modulus.
     #
-    # @param [Money, Fixnum] val Number to divmod by.
+    # @param [Money, Integer] val Number to divmod by.
     #
-    # @return [Array<Money,Money>,Array<Fixnum,Money>]
+    # @return [Array<Money,Money>,Array<Integer,Money>]
     #
     # @example
     #   Money.new(100).divmod(9)            #=> [#<Money @fractional=11>, #<Money @fractional=1>]
@@ -213,19 +216,19 @@ class Money
     def divmod_money(val)
       cents = val.exchange_to(currency).cents
       quotient, remainder = fractional.divmod(cents)
-      [quotient, self.class.new(remainder, currency)]
+      [quotient, self.class.new(remainder, currency, bank)]
     end
     private :divmod_money
 
     def divmod_other(val)
       quotient, remainder = fractional.divmod(as_d(val))
-      [self.class.new(quotient, currency), self.class.new(remainder, currency)]
+      [self.class.new(quotient, currency, bank), self.class.new(remainder, currency, bank)]
     end
     private :divmod_other
 
     # Equivalent to +self.divmod(val)[1]+
     #
-    # @param [Money, Fixnum] val Number take modulo with.
+    # @param [Money, Integer] val Number take modulo with.
     #
     # @return [Money]
     #
@@ -238,7 +241,7 @@ class Money
 
     # Synonym for +#modulo+.
     #
-    # @param [Money, Fixnum] val Number take modulo with.
+    # @param [Money, Integer] val Number take modulo with.
     #
     # @return [Money]
     #
@@ -249,7 +252,7 @@ class Money
 
     # If different signs +self.modulo(val) - val+ otherwise +self.modulo(val)+
     #
-    # @param [Money, Fixnum] val Number to rake remainder with.
+    # @param [Money, Integer] val Number to rake remainder with.
     #
     # @return [Money]
     #
@@ -263,7 +266,7 @@ class Money
       if (fractional < 0 && val < 0) || (fractional > 0 && val > 0)
         self.modulo(val)
       else
-        self.modulo(val) - (val.is_a?(Money) ? val : self.class.new(val, currency))
+        self.modulo(val) - (val.is_a?(Money) ? val : self.class.new(val, currency, bank))
       end
     end
 
@@ -274,7 +277,7 @@ class Money
     # @example
     #   Money.new(-100).abs #=> #<Money @fractional=100>
     def abs
-      self.class.new(fractional.abs, currency)
+      self.class.new(fractional.abs, currency, bank)
     end
 
     # Test if the money amount is zero.