minting 1.6.3 → 1.7.2

data/lib/minting/{mint/currency → currency}/currency_registry.rb

@@ -24,7 +24,7 @@ module Mint
     def currency_symbols
       @currency_symbols ||= begin
         currencies.values
-                  .reject { |currency| currency.symbol.empty? }
+                  .reject { |c| c.symbol.empty? }
                   .map { |currency| [currency.symbol, currency] }
                   .sort_by { |symbol, currency| [-symbol.length, -currency.priority] }
       end.freeze

data/lib/minting/{mint/currency → currency}/world_currencies.rb

@@ -8,7 +8,7 @@ module Mint
   # @api private
   def self.world_currencies
     @world_currencies ||= begin
-      path = File.join(File.expand_path('../../data', __dir__), 'world-currencies.yaml')
+      path = File.join(File.expand_path('../data', __dir__), 'world-currencies.yaml')
 
       YAML.load_file(path).to_h { |entry| [entry['code'], Currency.new(**entry.transform_keys(&:to_sym))] }
     end.freeze

data/lib/minting/mint/aliases.rb

@@ -3,5 +3,8 @@
 # Optional top‑level aliases for application use.
 # Not required automatically.
 
+# Alias for {Mint::Money} — enables `Money.new(...)` shorthand.
 Money = Mint::Money
+
+# Alias for {Mint::Currency} — enables `Currency.new(...)` shorthand.
 Currency = Mint::Currency

data/lib/minting/mint/dsl/numeric.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Mint Numeric refinements
+module Mint
+  refine Numeric do
+    # @return [Money] self interpreted as BRL
+    def reais = Mint.money(self, 'BRL')
+
+    # @return [Money] self interpreted as USD
+    def dollars = Mint.money(self, 'USD')
+
+    # @return [Money] self interpreted as EUR
+    def euros = Mint.money(self, 'EUR')
+
+    # @param currency [String, Symbol, Currency] target currency
+    # @return [Money] self interpreted as the given currency
+    def to_money(currency) = Mint.money(self, currency)
+
+    alias_method :dollar, :dollars
+    alias_method :euro, :euros
+    alias_method :mint, :to_money
+  end
+end

data/lib/minting/mint/dsl/range.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+# Mint Range patch
+# @api private
+module Mint
+  if RUBY_VERSION < '4.0'
+    # Ruby < 4.0's Range#step calls rb_to_int on non-Numeric step arguments,
+    # which raises TypeError for Money objects. Ruby 4.0+ uses arithmetic
+    # iteration (+ / <=>) for non-numeric steps natively, so this patch is
+    # only needed on older Rubies.
+    module RangeStepPatch
+      # Iterates over the range using a Money step value.
+      # Overrides Range#step to handle Mint::Money step sizes on Ruby < 4.0.
+      #
+      # @param step_size [Mint::Money, nil] step amount
+      # @return [self, Enumerator] self if block given, Enumerator otherwise
+      def step(step_size = nil, &block)
+        return super unless step_size.is_a?(Mint::Money)
+
+        raise TypeError, "can't iterate from NilClass" unless self.begin
+        raise ArgumentError, "step can't be 0" if step_size.zero?
+
+        if block
+          each_money_step(step_size, &block)
+          self
+        else
+          Enumerator.new { |yielder| each_money_step(step_size) { |value| yielder << value } }
+        end
+      end
+
+      private
+
+      # Dispatches to the appropriate iteration strategy based on range bounds.
+      # @private
+      def each_money_step(step, &)
+        self.end ? bounded_step(step, &) : unbounded_step(step, &)
+      end
+
+      # Iterates an open-ended range (no upper bound) with a Money step.
+      # @private
+      def unbounded_step(step)
+        current = self.begin
+        loop do
+          yield current
+          current += step
+        end
+      end
+
+      # Iterates a bounded range with a Money step, respecting direction and exclude_end?.
+      # @private
+      def bounded_step(step)
+        current = self.begin
+        last    = self.end
+        asc     = step.positive?
+
+        loop do
+          break if asc ? current > last : current < last
+          break if exclude_end? && current == last
+
+          yield current
+          current += step
+        end
+      end
+    end
+    Range.prepend(Mint::RangeStepPatch)
+  end
+end

data/lib/minting/mint/dsl/string.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Mint String refinement
+module Mint
+  refine String do
+    # Parses self as a numeric string and creates a Money in the given currency.
+    #
+    # @param currency [String, Symbol, Currency] target currency
+    # @return [Money]
+    def to_money(currency) = Mint.money(to_r, currency)
+  end
+end

data/lib/minting/mint/{dsl.rb → dsl/top_level.rb}

@@ -2,24 +2,9 @@
 
 # Mint refinements
 module Mint
-  refine Numeric do
-    def reais = Mint.money(self, 'BRL')
-
-    def dollars = Mint.money(self, 'USD')
-
-    def euros = Mint.money(self, 'EUR')
-
-    def to_money(currency) = Mint.money(self, currency)
-
-    alias_method :dollar, :dollars
-    alias_method :euro, :euros
-    alias_method :mint, :to_money
-  end
-
-  refine String do
-    def to_money(currency) = Mint.money(to_r, currency)
-  end
-
+  # Registers top-level ::Money and ::Currency constants as aliases for Mint's classes.
+  #
+  # @raise [NameError] if ::Money or ::Currency are already defined and differ
   def self.use_top_level_constants!
     if !defined?(::Money) && !defined?(::Currency)
       require 'minting/mint/aliases'

data/lib/minting/mint/mint.rb

@@ -21,14 +21,28 @@ module Mint
   # @return [Currency, nil] the registered Currency instance or nil if not found
   def self.currency(currency)
     case currency
-    when nil      then nil
+    when NilClass then nil
     when Currency then currency
     when String   then CurrencyRegistry.currencies[currency]
-    else raise ArgumentError, "currency must be [Currency] ot [String] (#{currency})"
+    else          raise ArgumentError, "currency must be [Currency], [String] or nil (#{currency})"
     end
   end
 
-  # Registers a new currency, raising a KeyError if already registered.
+  # Returns a zero {Money} in the given currency, useful as a default value
+  # for discounts, totals, or placeholders.
+  #
+  # @param currency [String, Currency] a currency code or object
+  # @return [Money] a frozen zero-Money
+  # @raise [ArgumentError] if the currency is not registered
+  def self.zero(currency)
+    checked = Mint.currency(currency)
+    raise ArgumentError, "Invalid Currency: [#{currency}]" unless checked
+
+    @zeros ||= CurrencyRegistry.currencies.values.to_h { |currency| [currency, Mint::Money.send(:new, 0, currency)] }
+    @zeros[currency] ||= Money.send(:new, 0, currency)
+    @zeros[currency]
+  end
+
   #
   # @param code [String] the unique currency code
   # @param subunit [Integer] the decimal subunit precision, defaults to 0

data/lib/minting/mint/{parser.rb → parser/parser.rb}

@@ -35,44 +35,32 @@ module Mint
   private
 
   # Extracts a numeric value from input that should only contain an amount.
+  # @private
   def parse_amount(input)
+    accounting_negative = input.start_with?('(') && input.end_with?(')')
+
     # Remove any charater that is not a digit, comma or period
     numeric = input.scan(/[\d.,-]/).join
-    numeric = normalize_separators(numeric)
-    Rational(numeric)
-  end
-
-  # Converts locale-specific decimal/thousand separators into a plain decimal string.
-  def normalize_separators(numeric)
-    case [numeric.count(','), numeric.count('.')]
-    in [0, 0] | [0, 1] then numeric              # Nothing to normalize (e.g. "1500" or "34.21").
-    in [1, 0]          then numeric.tr(',', '.') # Only one comma: decimal (e.g. 19,99 or 1,234).
-    in [c, p] if c > 1 && p > 1 # Both separators appear multiple times
-      raise ArgumentError, "could not distinguish decimal and thousand separators in '#{numeric}'"
-    in [c, p] if c > 0 && p > 0 # Commas and dots: the rightmost one is the decimal separator.
-      if numeric.rindex(',') > numeric.rindex('.')
-        numeric.delete('.').tr(',', '.')
-      else
-        numeric.delete(',')
-      end
-    else # Multiple of the same separator only (e.g. 1,234,567) — all are thousands.
-      numeric.delete(',.')
-    end
+    amount = Rational(normalize_separators(numeric))
+    accounting_negative ? -amount : amount
   end
 
+  # Extracts currency from a string by matching ISO code or symbol.
+  #
+  # Scans all uppercase words and returns the first registered code, falling
+  # back to symbol matching. This correctly handles inputs like
+  # "MAX 10.00 USD" where the first uppercase word isn't a currency code.
+  # @private
   def parse_currency(input)
-    case input
-    when nil then return nil
-    when String
-      # Prefer an explicit ISO 4217 code (e.g. "USD 1,234.56") over symbol matching.
-      currency = Mint.currency(input[/\b([A-Z_]+)\b/, 1])
+    input.scan(/\b([A-Z_]+)\b/) do |(code)|
+      currency = Mint.currency(code)
       return currency if currency
+    end
 
-      # Fall back to registered symbols, longest first (HK$ before $).
-      CurrencyRegistry.currency_symbols.each do |symbol, currency|
-        return currency if input.include?(symbol)
-      end
+    CurrencyRegistry.currency_symbols.each do |symbol, currency|
+      return currency if input.include?(symbol)
     end
+
     raise ArgumentError, 'Currency could not be detected'
   end
 end

data/lib/minting/mint/parser/separators.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# Mint Money parsing
+module Mint
+  extend self
+
+  private
+
+  # Classifies the separator pattern in a numeric string.
+  # @private
+  def classify_separators(numeric)
+    case [numeric.count('.'), numeric.count(',')]
+    in [0, 1] if numeric[-4] == ',' then :thousands_comma  # Comma is a thousand separator
+    in [0, 1]                       then :decimal_comma    # Only one comma: decimal (e.g. 19,99 or 1,4 or 1,2345).
+    in [0, 0] | [1, 0]              then :decimal_period   # e.g. "1500" or "34.21".
+    in [p, c] if p > 1 && c > 1     then :ambiguous        # Both separators appear multiple times
+    in [p, c] if p > 0 && c > 0     then :mixed            # Commas and dots: the rightmost one is the decimal
+    else                                 :thousands        # Multiple of the same separator only (e.g. 1,234,567)
+    end
+  end
+
+  # Converts locale-specific decimal/thousand separators into a plain decimal string.
+  # @private
+  def normalize_separators(numeric)
+    case classify_separators(numeric)
+    when :decimal_period   then numeric # Nothing to normalize (e.g. "1500" or "34.21").
+    when :decimal_comma    then numeric.tr(',', '.') # Only one comma: decimal (e.g. 19,99 or 1,234).
+    when :thousands_comma  then numeric.delete(',')
+    when :thousands        then numeric.delete('.,')
+    when :ambiguous then   raise ArgumentError, "could not distinguish decimal and thousand separators in '#{numeric}'"
+    when :mixed # Commas and dots: the rightmost one is the decimal separator.
+      if numeric.rindex(',') > numeric.rindex('.')
+        numeric.delete('.').tr(',', '.')
+      else
+        numeric.delete(',')
+      end
+    end
+  end
+end

data/lib/minting/mint.rb

@@ -1,16 +1,27 @@
 # frozen_string_literal: true
 
-require 'minting/mint/currency/currency'
-require 'minting/mint/currency/currency_registry'
-require 'minting/mint/currency/world_currencies'
-require 'minting/mint/dsl'
+require 'minting/currency/currency'
+require 'minting/currency/currency_registry'
+require 'minting/currency/world_currencies'
+
+require 'minting/mint/dsl/numeric'
+require 'minting/mint/dsl/range'
+require 'minting/mint/dsl/string'
+require 'minting/mint/dsl/top_level'
+
 require 'minting/mint/mint'
-require 'minting/mint/parser'
-require 'minting/money/allocation'
-require 'minting/money/arithmetics'
+require 'minting/mint/parser/parser'
+require 'minting/mint/parser/separators'
+
+require 'minting/money/allocation/allocation'
+require 'minting/money/allocation/split'
+require 'minting/money/arithmetics/methods'
+require 'minting/money/arithmetics/operators'
+require 'minting/money/clamp'
 require 'minting/money/coercion'
 require 'minting/money/comparable'
 require 'minting/money/constructors'
 require 'minting/money/conversion'
-require 'minting/money/formatting'
+require 'minting/money/format/formatting'
+require 'minting/money/format/to_s'
 require 'minting/money/money'

data/lib/minting/money/allocation/allocation.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Mint
+  # Allocation and splitting
+  class Money
+    # Proportionally allocates the monetary amount among a list of ratios.
+    # Disperses any subunit rounding amounts across the initial slots
+    # @param proportions [Array<Numeric>] a list of numeric proportions/ratios to allocate by
+    # @return [Array<Money>] the list of newly allocated Money objects
+    # @raise [ArgumentError] if the proportions list is empty or sums to zero
+    #
+    # @example Proportional allocation
+    #   money = Mint.money(10.00, 'USD')
+    #   money.allocate([1, 2, 3]) #=> [[USD 1.67], [USD 3.33], [USD 5.00]]
+    def allocate(proportions)
+      whole = proportions.sum.to_r
+      raise ArgumentError, 'Need at least 1 proportion element' if proportions.empty?
+      raise ArgumentError, 'Proportions total must not be zero' if whole.zero?
+
+      subunit = currency.subunit
+      amounts = proportions.map { |rate| Rational(amount * rate, whole).round(subunit) }
+      allocate_left_over(amounts: amounts, left_over: amount - amounts.sum)
+    end
+  end
+end

data/lib/minting/money/allocation/split.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Mint
+  # Allocation and splitting
+  class Money
+    # Splits the monetary amount into a given quantity of equal parts.
+    # Disperses any fractional subunit rounding differences across the initial slots
+    # so that the sum is preserved.
+    #
+    # @param slices [Integer] the number of equal parts to divide the money into (must be > 0)
+    # @return [Array<Money>] the list of newly split Money objects
+    # @raise [ArgumentError] if quantity is not a positive integer
+    #
+    # @example Even split
+    #   money = Mint.money(10.00, 'USD')
+    #   money.split(3) #=> [[USD 3.34], [USD 3.33], [USD 3.33]]
+    def split(slices)
+      raise ArgumentError, 'Slices quantity must be an poitive integer' unless slices.positive? && slices.integer?
+
+      fraction = (amount / slices).round(currency.subunit)
+      allocate_left_over(amounts: Array.new(slices, fraction),
+                         left_over: amount - (fraction * slices))
+    end
+
+    private
+
+    # Distributes any leftover amount across the allocation slots by adjusting
+    # individual amounts by the currency's minimum unit, and converting to Money.
+    # Caution: amounts array is mutated by this method
+    # @private
+    def allocate_left_over(amounts:, left_over:)
+      if left_over.nonzero?
+        minimum = currency.minimum_amount
+        minimum = -minimum if left_over.negative?
+        slots_to_adjust = (left_over / minimum).to_i
+        (0...slots_to_adjust).each { |slot| amounts[slot] += minimum }
+      end
+      amounts.map! { |amount| Money.new(amount, currency) }
+    end
+  end
+end

data/lib/minting/money/arithmetics/methods.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Mint
+  # Money Arithmetics
+  class Money
+    # Returns the absolute value of the monetary amount as a new {Money} instance.
+    #
+    # @return [Money] the absolute value
+    def abs = mint(amount.abs)
+
+    # Returns true if the monetary amount is less than zero.
+    #
+    # @return [Boolean] true if negative, false otherwise
+    def negative? = amount.negative?
+
+    # Returns true if the monetary amount is greater than zero.
+    #
+    # @return [Boolean] true if positive, false otherwise
+    def positive? = amount.positive?
+
+    # Returns the successor of the Money instance by adding the minimum possible subunit amount.
+    # Enables standard ranges and stepping (e.g. `1.dollar..10.dollars`).
+    #
+    # @return [Money] successor Money instance
+    def succ = mint(amount + currency.minimum_amount)
+  end
+end

data/lib/minting/money/{arithmetics.rb → arithmetics/operators.rb}

@@ -3,27 +3,6 @@
 module Mint
   # Money Arithmetics
   class Money
-    # Returns the absolute value of the monetary amount as a new {Money} instance.
-    #
-    # @return [Money] the absolute value
-    def abs = mint(amount.abs)
-
-    # Returns true if the monetary amount is less than zero.
-    #
-    # @return [Boolean] true if negative, false otherwise
-    def negative? = amount.negative?
-
-    # Returns true if the monetary amount is greater than zero.
-    #
-    # @return [Boolean] true if positive, false otherwise
-    def positive? = amount.positive?
-
-    # Returns the successor of the Money instance by adding the minimum possible subunit amount.
-    # Enables standard ranges and stepping (e.g. `1.dollar..10.dollars`).
-    #
-    # @return [Money] successor Money instance
-    def succ = mint(amount + currency.minimum_amount)
-
     # Performs addition with another {Money} instance or standard zero Numeric.
     #
     # @param addend [Money, Numeric] the value to add
@@ -31,10 +10,10 @@ module Mint
     # @raise [TypeError] if addition involves a different currency or incompatible types
     def +(addend)
       case addend
-      when 0     then return self
-      when Money then return mint(amount + addend.amount) if same_currency?(addend)
+      in 0 then self
+      in Money if same_currency?(addend) then mint(amount + addend.amount)
+      else raise TypeError, "#{addend} can't be added to #{self}"
       end
-      raise TypeError, "#{addend} can't be added to #{self}"
     end
 
     # Performs subtraction with another {Money} instance or standard zero Numeric.
@@ -61,9 +40,9 @@ module Mint
     # @return [Money] the multiplied Money instance
     # @raise [TypeError] if multiplier is not Numeric or is a Money object
     def *(multiplicand)
-      return mint(amount * multiplicand) if multiplicand.is_a?(Numeric)
+      raise TypeError, "#{self} can't be multiplied by #{multiplicand}" unless multiplicand.is_a?(Numeric)
 
-      raise TypeError, "#{self} can't be multiplied by #{multiplicand}"
+      mint(amount * multiplicand)
     end
 
     # Performs division of the monetary value by a scalar Numeric or identical currency {Money}.

data/lib/minting/money/clamp.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Mint
+  # Money clamp
+  class Money
+    # Constrains +self+ to the inclusive range [+min+, +max+].
+    #
+    # Bounds may be:
+    # - nil meaning no boundary
+    # - same-currency {Money} or Range
+    # - Numeric amount, or Range
+    #
+    # Numeric is interpreted as an amount in +self+'s currency, so the common
+    # pricing idiom +price.clamp(0, 100)+ reads as "0 to 100 in the same
+    # currency as +price+".
+    #
+    # When +self+ is already in range the receiver is returned (no new object
+    # allocated). When out of range, the nearest bound is returned as a new
+    # frozen {Money} in +self+'s currency.
+    #
+    # @param min_or_range [Money, Numeric, Range, nil] lower bound (inclusive), or range
+    # @param max [Money, Numeric, nil] upper bound (inclusive)
+    # @return [Money] +self+ if in range, otherwise the nearer bound
+    # @raise [ArgumentError] if +min+ or +max+ is not a Money, Numeric or nil; if
+    #   a Money operand has a different currency; if +min+ > +max+;
+    #   if min is a Range, and max is not nil
+    #
+    # @example In range
+    #   Mint.money(5, 'USD').clamp(0, 10) #=> [USD 5.00]  (returns self)
+    #
+    # @example Out of range, with Numeric bounds
+    #   Mint.money(50, 'USD').clamp(0, 10) #=> [USD 10.00]
+    #
+    # @example Out of range, with Money bounds
+    #   loss  = Mint.money(-5, 'USD')
+    #   floor = Mint.money(0,  'USD')
+    #   ceil  = Mint.money(10, 'USD')
+    #   loss.clamp(floor, ceil) #=> [USD 0.00]
+    #
+    # @example Subunit-0 currency (JPY)
+    #   Mint.money(500, 'JPY').clamp(0, 100) #=> [JPY 100]
+    def clamp(min_or_range, max = nil)
+      if min_or_range.is_a?(Range)
+        raise(ArgumentError, "Either amount range alone or two amounts accepted: #{max}") if max
+
+        min, max = min_or_range.minmax
+      else
+        min = min_or_range
+      end
+      mint(amount.clamp(normalize_boundary(min), normalize_boundary(max)))
+    end
+
+    private
+
+    # Converts a clamp boundary to a numeric amount.
+    # @private
+    def normalize_boundary(boundary)
+      case boundary
+      in NilClass | Numeric                then boundary
+      in Money if same_currency?(boundary) then boundary.amount
+      in Money                             then raise ArgumentError, "oundary currency must be: #{currency_code}"
+      else                                 raise ArgumentError, "Boundary must be Numeric or Money #{boundary}"
+      end
+    end
+  end
+end

data/lib/minting/money/coercion.rb

@@ -4,13 +4,13 @@ module Mint
   # Implements the standard Ruby coercion protocol.
   class Money
     # Allows {Money} to interact seamlessly as the right-hand operand in Numeric arithmetic.
-    # This enables expressions like `5 + money` where `5` is a Numeric and `money` is a Money object.
+    # This enables expressions like `5 * money` where `5` is a Numeric and `money` is a Money object.
     #
     # @param other [Numeric] the left-hand operand to coerce
     # @return [Array(CoercedNumber, Money)] coerced operand array
     # @example
     #   price = Mint.money(10, 'USD')
-    #   5 + price  #=> [USD 15.00] (via coercion)
+    #   5 * price  #=> [USD 50.00] (via coercion)
     def coerce(other)
       [CoercedNumber.new(other), self]
     end
@@ -20,34 +20,41 @@ module Mint
     # @private
     class CoercedNumber
       # @private
-      def initialize(value)
-        @value = value
-      end
+      def initialize(value) = @value = value
 
       # @private
+      # Adds a CoercedNumber to a Money object.
+      # Only zero is a valid additive identity (returns the Money unchanged).
       def +(other)
-        return other if @value.zero?
+        raise_coercion_error(:+, other) unless @value.zero?
 
-        raise_coercion_error(:+, other)
+        other
       end
 
       # @private
+      # Subtracts a Money object from a CoercedNumber.
+      # Only zero is valid (returns the negated Money).
       def -(other)
-        return -other if @value.zero?
+        raise_coercion_error(:-, other) unless @value.zero?
 
-        raise_coercion_error(:-, other)
+        -other
       end
 
       # @private
+      # Multiplies a Money object by the wrapped numeric value.
+      # This is the standard coercion path for `Numeric * Money`.
       def *(other)
         other.mint(@value * other.amount)
       end
 
       # @private
+      # Divides a CoercedNumber by a Money object.
+      # Not a meaningful operation (what currency is the result?).
       def /(other)
         raise_coercion_error(:/, other)
       end
 
+      # @private
       # Only zero is dimensionless and comparable to Money.
       # e.g. 0 < price is meaningful; 0.5 < price is not (what currency is 0.5?).
       def <=>(other)
@@ -58,9 +65,9 @@ module Mint
 
       private
 
+      # Raises a TypeError with a descriptive message for unsupported coercions.
       def raise_coercion_error(operation, operand)
-        raise TypeError,
-              "#{@value} #{operation} #{operand} : incompatible operands"
+        raise TypeError, "#{@value} #{operation} #{operand} : incompatible operands"
       end
     end
     private_constant :CoercedNumber

data/lib/minting/money/comparable.rb

@@ -14,6 +14,10 @@ module Mint
       end
     end
 
+    # Strict equality — both amount and currency must match exactly.
+    # Unlike ==, does not treat zero as equivalent across currencies.
+    #
+    # @return [Boolean]
     def eql?(other)
       other.is_a?(Mint::Money) &&
         amount == other.amount &&
@@ -37,8 +41,10 @@ module Mint
       end
     end
 
+    # @return [self, nil] self if amount is non-zero, nil otherwise
     def nonzero? = amount.nonzero?
 
+    # @return [Boolean] true if amount is zero
     def zero? = amount.zero?
   end
 end