money 6.5.1 → 6.16.0

data/lib/money/currency.rb

@@ -8,18 +8,44 @@ class Money
 
   # Represents a specific currency unit.
   #
-  # @see http://en.wikipedia.org/wiki/Currency
+  # @see https://en.wikipedia.org/wiki/Currency
   # @see http://iso4217.net/
   class Currency
     include Comparable
     extend Enumerable
-    extend Money::Currency::Loader
     extend Money::Currency::Heuristics
 
+    # Keeping cached instances in sync between threads
+    @@mutex = Mutex.new
+    @@instances = {}
+
+    # Thrown when a Currency has been registered without all the attributes
+    # which are required for the current action.
+    class MissingAttributeError < StandardError
+      def initialize(method, currency, attribute)
+        super(
+          "Can't call Currency.#{method} - currency '#{currency}' is missing "\
+          "the attribute '#{attribute}'"
+        )
+      end
+    end
+
     # Thrown when an unknown currency is requested.
     class UnknownCurrency < ArgumentError; end
 
     class << self
+      def new(id)
+        id = id.to_s.downcase
+        unless stringified_keys.include?(id)
+          raise UnknownCurrency, "Unknown currency '#{id}'"
+        end
+
+        _instances[id] || @@mutex.synchronize { _instances[id] ||= super }
+      end
+
+      def _instances
+        @@instances
+      end
 
       # Lookup a currency with given +id+ an returns a +Currency+ instance on
       # success, +nil+ otherwise.
@@ -49,10 +75,12 @@ class Money
       #
       # @example
       #   Money::Currency.find_by_iso_numeric(978) #=> #<Money::Currency id: eur ...>
+      #   Money::Currency.find_by_iso_numeric(51) #=> #<Money::Currency id: amd ...>
       #   Money::Currency.find_by_iso_numeric('001') #=> nil
       def find_by_iso_numeric(num)
-        num = num.to_s
-        id, _ = self.table.find{|key, currency| currency[:iso_numeric] == num}
+        num = num.to_s.rjust(3, '0')
+        return if num.empty?
+        id, _ = self.table.find { |key, currency| currency[:iso_numeric] == num }
         new(id)
       rescue UnknownCurrency
         nil
@@ -85,25 +113,31 @@ class Money
       #
       # == monetary unit
       # The standard unit of value of a currency, as the dollar in the United States or the peso in Mexico.
-      # http://www.answers.com/topic/monetary-unit
+      # https://www.answers.com/topic/monetary-unit
       # == fractional monetary unit, subunit
       # A monetary unit that is valued at a fraction (usually one hundredth) of the basic monetary unit
-      # http://www.answers.com/topic/fractional-monetary-unit-subunit
+      # https://www.answers.com/topic/fractional-monetary-unit-subunit
       #
-      # See http://en.wikipedia.org/wiki/List_of_circulating_currencies and
+      # See https://en.wikipedia.org/wiki/List_of_circulating_currencies and
       # http://search.cpan.org/~tnguyen/Locale-Currency-Format-1.28/Format.pm
       def table
-        @table ||= load_currencies
+        @table ||= Loader.load_currencies
       end
 
       # List the currencies imported and registered
       # @return [Array]
       #
       # @example
-      #   Money::Currency.iso_codes()
+      #   Money::Currency.all()
       #   [#<Currency ..USD>, 'CAD', 'EUR']...
       def all
-        table.keys.map {|curr| Currency.new(curr)}.sort_by(&:priority)
+        table.keys.map do |curr|
+          c = Currency.new(curr)
+          if c.priority.nil?
+            raise MissingAttributeError.new(:all, c.id, :priority)
+          end
+          c
+        end.sort_by(&:priority)
       end
 
       # We need a string-based validator before creating an unbounded number of
@@ -135,10 +169,20 @@ class Money
       # @option delimiter [String] character between each thousands place
       def register(curr)
         key = curr.fetch(:iso_code).downcase.to_sym
+        @@mutex.synchronize { _instances.delete(key.to_s) }
         @table[key] = curr
-        @stringified_keys = stringify_keys
+        @stringified_keys = nil
       end
 
+      # Inherit a new currency from existing one
+      #
+      # @param parent_iso_code [String] the international 3-letter code as defined
+      # @param curr [Hash] See {register} method for hash structure
+      def inherit(parent_iso_code, curr)
+        parent_iso_code = parent_iso_code.downcase.to_sym
+        curr = @table.fetch(parent_iso_code, {}).merge(curr)
+        register(curr)
+      end
 
       # Unregister a currency.
       #
@@ -154,15 +198,18 @@ class Money
           key = curr.downcase.to_sym
         end
         existed = @table.delete(key)
-        @stringified_keys = stringify_keys
+        @stringified_keys = nil if existed
         existed ? true : false
       end
 
-
       def each
         all.each { |c| yield(c) }
       end
 
+      def reset!
+        @@instances = {}
+        @table = Loader.load_currencies
+      end
 
       private
 
@@ -171,49 +218,50 @@ class Money
       end
     end
 
-    # @!attribute [r] id 
+    # @!attribute [r] id
     #   @return [Symbol] The symbol used to identify the currency, usually THE
     #     lowercase +iso_code+ attribute.
-    # @!attribute [r] priority 
+    # @!attribute [r] priority
     #   @return [Integer] A numerical value you can use to sort/group the
     #     currency list.
-    # @!attribute [r] iso_code 
+    # @!attribute [r] iso_code
     #   @return [String] The international 3-letter code as defined by the ISO
     #     4217 standard.
-    # @!attribute [r] iso_numeric 
+    # @!attribute [r] iso_numeric
     #   @return [String] The international 3-numeric code as defined by the ISO
     #     4217 standard.
-    # @!attribute [r] name 
+    # @!attribute [r] name
     #   @return [String] The currency name.
-    # @!attribute [r] symbol 
+    # @!attribute [r] symbol
     #   @return [String] The currency symbol (UTF-8 encoded).
-    # @!attribute [r] disambiguate_symbol 
+    # @!attribute [r] disambiguate_symbol
     #   @return [String] Alternative currency used if symbol is ambiguous
-    # @!attribute [r] html_entity 
+    # @!attribute [r] html_entity
     #   @return [String] The html entity for the currency symbol
-    # @!attribute [r] subunit 
+    # @!attribute [r] subunit
     #   @return [String] The name of the fractional monetary unit.
-    # @!attribute [r] subunit_to_unit 
+    # @!attribute [r] subunit_to_unit
     #   @return [Integer] The proportion between the unit and the subunit
-    # @!attribute [r] decimal_mark 
+    # @!attribute [r] decimal_mark
     #   @return [String] The decimal mark, or character used to separate the
     #     whole unit from the subunit.
-    # @!attribute [r] The 
-    #   @return [String] character used to separate thousands grouping of the
-    #     whole unit.
-    # @!attribute [r] symbol_first 
+    # @!attribute [r] thousands_separator
+    #   @return [String] The character used to separate thousands grouping of
+    #     the whole unit.
+    # @!attribute [r] symbol_first
     #   @return [Boolean] Should the currency symbol precede the amount, or
     #     should it come after?
-    # @!attribute [r] smallest_denomination 
+    # @!attribute [r] smallest_denomination
     #   @return [Integer] Smallest amount of cash possible (in the subunit of
     #     this currency)
 
     attr_reader :id, :priority, :iso_code, :iso_numeric, :name, :symbol,
       :disambiguate_symbol, :html_entity, :subunit, :subunit_to_unit, :decimal_mark,
-      :thousands_separator, :symbol_first, :smallest_denomination
+      :thousands_separator, :symbol_first, :smallest_denomination, :format
 
     alias_method :separator, :decimal_mark
     alias_method :delimiter, :thousands_separator
+    alias_method :eql?, :==
 
     # Create a new +Currency+ object.
     #
@@ -225,10 +273,6 @@ class Money
     # @example
     #   Money::Currency.new(:usd) #=> #<Money::Currency id: usd ...>
     def initialize(id)
-      id = id.to_s.downcase
-      unless self.class.stringified_keys.include?(id)
-        raise UnknownCurrency, "Unknown currency '#{id}'"
-      end
       @id = id.to_sym
       initialize_data!
     end
@@ -283,26 +327,10 @@ class Money
     end
     private :compare_ids
 
-    # Compares +self+ with +other_currency+ and returns +true+ if the are the
-    # same or if their +id+ attributes match.
-    #
-    # @param [Money::Currency] other_currency The currency to compare to.
-    #
-    # @return [Boolean]
-    #
-    # @example
-    #   c1 = Money::Currency.new(:usd)
-    #   c2 = Money::Currency.new(:jpy)
-    #   c1.eql? c1 #=> true
-    #   c1.eql? c2 #=> false
-    def eql?(other_currency)
-      self == other_currency
-    end
-
-    # Returns a Fixnum hash value based on the +id+ attribute in order to use
+    # Returns a Integer hash value based on the +id+ attribute in order to use
     # functions like & (intersection), group_by, etc.
     #
-    # @return [Fixnum]
+    # @return [Integer]
     #
     # @example
     #   Money::Currency.new(:usd).hash #=> 428936
@@ -317,7 +345,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}, smallest_denomination: #{smallest_denomination}>"
+      "#<#{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}, format: #{format}>"
     end
 
     # Returns a string representation corresponding to the upcase +id+
@@ -359,7 +387,7 @@ class Money
       id.to_s.upcase.to_sym
     end
 
-    # Conversation to +self+.
+    # Conversion to +self+.
     #
     # @return [self]
     def to_currency
@@ -377,42 +405,30 @@ class Money
       !!@symbol_first
     end
 
-    # Returns the number of digits after the decimal separator.
+    # Returns if a code currency is ISO.
     #
-    # @return [Float]
-    def exponent
-      Math.log10(@subunit_to_unit)
-    end
-
-    # Cache decimal places for subunit_to_unit values.  Common ones pre-cached.
-    def self.decimal_places_cache
-      @decimal_places_cache ||= {1 => 0, 10 => 1, 100 => 2, 1000 => 3}
+    # @return [Boolean]
+    #
+    # @example
+    #   Money::Currency.new(:usd).iso?
+    #
+    def iso?
+      iso_numeric && iso_numeric != ''
     end
 
-    # The number of decimal places needed.
+    # Returns the relation between subunit and unit as a base 10 exponent.
+    #
+    # Note that MGA and MRU are exceptions and are rounded to 1
+    # @see https://en.wikipedia.org/wiki/ISO_4217#Active_codes
     #
     # @return [Integer]
-    def decimal_places
-      cache[subunit_to_unit] ||= calculate_decimal_places(subunit_to_unit)
+    def exponent
+      Math.log10(subunit_to_unit).round
     end
+    alias decimal_places exponent
 
     private
 
-    def cache
-      self.class.decimal_places_cache
-    end
-
-    # If we need to figure out how many decimal places we need we
-    # use repeated integer division.
-    def calculate_decimal_places(num)
-      i = 1
-      while num >= 10
-        num /= 10
-        i += 1 if num >= 10
-      end
-      i
-    end
-
     def initialize_data!
       data = self.class.table[@id]
       @alternate_symbols     = data[:alternate_symbols]
@@ -429,6 +445,7 @@ class Money
       @symbol                = data[:symbol]
       @symbol_first          = data[:symbol_first]
       @thousands_separator   = data[:thousands_separator]
+      @format                = data[:format]
     end
   end
 end

data/lib/money/locale_backend/base.rb

@@ -0,0 +1,7 @@
+require 'money/locale_backend/errors'
+
+class Money
+  module LocaleBackend
+    class Base; end
+  end
+end

data/lib/money/locale_backend/currency.rb

@@ -0,0 +1,11 @@
+require 'money/locale_backend/base'
+
+class Money
+  module LocaleBackend
+    class Currency < Base
+      def lookup(key, currency)
+        currency.public_send(key) if currency.respond_to?(key)
+      end
+    end
+  end
+end

data/lib/money/locale_backend/errors.rb

@@ -0,0 +1,6 @@
+class Money
+  module LocaleBackend
+    class NotSupported < StandardError; end
+    class Unknown < ArgumentError; end
+  end
+end

data/lib/money/locale_backend/i18n.rb

@@ -0,0 +1,25 @@
+require 'money/locale_backend/base'
+
+class Money
+  module LocaleBackend
+    class I18n < Base
+      KEY_MAP = {
+        thousands_separator: :delimiter,
+        decimal_mark: :separator,
+        symbol: :unit
+      }.freeze
+
+      def initialize
+        raise NotSupported, 'I18n not found' unless defined?(::I18n)
+      end
+
+      def lookup(key, _)
+        i18n_key = KEY_MAP[key]
+
+        ::I18n.t i18n_key, scope: 'number.currency.format', raise: true
+      rescue ::I18n::MissingTranslationData
+        ::I18n.t i18n_key, scope: 'number.format', default: nil
+      end
+    end
+  end
+end

data/lib/money/locale_backend/legacy.rb

@@ -0,0 +1,28 @@
+require 'money/locale_backend/base'
+require 'money/locale_backend/i18n'
+
+class Money
+  module LocaleBackend
+    class Legacy < Base
+      def initialize
+        raise NotSupported, 'I18n not found' if Money.use_i18n && !defined?(::I18n)
+      end
+
+      def lookup(key, currency)
+        warn '[DEPRECATION] You are using the default localization behaviour that will change in the next major release. Find out more - https://github.com/RubyMoney/money#deprecation'
+
+        if Money.use_i18n
+          i18n_backend.lookup(key, nil) || currency.public_send(key)
+        else
+          currency.public_send(key)
+        end
+      end
+
+      private
+
+      def i18n_backend
+        @i18n_backend ||= Money::LocaleBackend::I18n.new
+      end
+    end
+  end
+end

data/lib/money/money/allocation.rb

@@ -0,0 +1,46 @@
+# encoding: utf-8
+
+class Money
+  class Allocation
+    # Splits a given amount in parts without losing pennies.
+    # The left-over pennies will be distributed round-robin amongst the parts. This means that
+    # parts listed first will likely receive more pennies than the ones 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 = if parts.is_a?(Numeric)
+        Array.new(parts, 1)
+      elsif parts.all?(&:zero?)
+        Array.new(parts.count, 1)
+      else
+        parts.dup
+      end
+
+      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 = 0
+        if parts_sum > 0
+          current_split = remaining_amount * part / parts_sum
+          current_split = current_split.truncate if whole_amounts
+        end
+
+        result.unshift current_split
+        remaining_amount -= current_split
+      end
+
+      result
+    end
+  end
+end