minting 1.7.0 → 1.7.2

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

@@ -9,43 +9,56 @@ module Mint
     # iteration (+ / <=>) for non-numeric steps natively, so this patch is
     # only needed on older Rubies.
     module RangeStepPatch
-      def step(step_size = nil, &)
+      # 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_given?
-          each_money_step(step_size, &)
+        if block
+          each_money_step(step_size, &block)
           self
         else
-          Enumerator.new do |yielder|
-            each_money_step(step_size) { |v| yielder << v }
-          end
+          Enumerator.new { |yielder| each_money_step(step_size) { |value| yielder << value } }
         end
       end
 
       private
 
-      def each_money_step(step_amount)
+      # 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
-        last = self.end
-
-        unless last
-          loop do
-            yield current
-            current += step_amount
-          end
-          return
+        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?
 
-        ascending = step_amount.positive?
         loop do
-          break if ascending ? current > last : current < last
+          break if asc ? current > last : current < last
           break if exclude_end? && current == last
 
           yield current
-          current += step_amount
+          current += step
         end
       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/top_level.rb

@@ -2,6 +2,9 @@
 
 # Mint refinements
 module Mint
+  # 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

@@ -24,11 +24,25 @@ module Mint
     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/parser.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+# Mint Money parsing
+module Mint
+  extend self
+
+  # Parses a human-readable money string into a {Money} object.
+  #
+  # @param input [String] Amount input, optionally including a currency symbol or code
+  # @param currency [String, Symbol, Currency, nil] ISO code when not present in +input+
+  # @return [Money]
+  # @raise [ArgumentError] when +input+ is invalid or currency cannot be determined
+  #
+  # @example With explicit currency
+  #   Money.parse('19.99', 'USD')    #=> [USD 19.99]
+  #   Money.parse('1.234,56', 'EUR') #=> [EUR 1234.56]
+  #
+  # @example With symbol or code in the string
+  #   Money.parse('$19.99')            #=> [USD 19.99]
+  #   Money.parse('19,99 €')         #=> [EUR 19.99]
+  #   Money.parse('USD 1,234.56')    #=> [USD 1234.56]
+  def parse(input, currency = nil)
+    raise ArgumentError, 'input must be a String' unless input.is_a?(String)
+
+    input = input.strip
+    raise ArgumentError, 'input cannot be empty' if input.empty?
+
+    currency = Mint.currency(currency) || parse_currency(input)
+    raise ArgumentError, "Currency [#{currency}] not registered" unless currency
+
+    amount = currency.normalize_amount(parse_amount(input))
+    Mint::Money.new(amount, currency)
+  end
+
+  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
+    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)
+    input.scan(/\b([A-Z_]+)\b/) do |(code)|
+      currency = Mint.currency(code)
+      return currency if currency
+    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,18 +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/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/refinements'
+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.rb → allocation/split.rb}

@@ -3,25 +3,6 @@
 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
-
     # 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.
@@ -46,6 +27,7 @@ module Mint
     # 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

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

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

@@ -23,6 +23,8 @@ module Mint
       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)
         raise_coercion_error(:+, other) unless @value.zero?
 
@@ -30,6 +32,8 @@ module Mint
       end
 
       # @private
+      # Subtracts a Money object from a CoercedNumber.
+      # Only zero is valid (returns the negated Money).
       def -(other)
         raise_coercion_error(:-, other) unless @value.zero?
 
@@ -37,15 +41,20 @@ module Mint
       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)
@@ -56,6 +65,7 @@ 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"
       end

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

data/lib/minting/money/constructors.rb

@@ -13,7 +13,9 @@ module Mint
       checked_currency = Mint.currency(currency)
       raise ArgumentError, "Currency not found (#{currency})" unless checked_currency
 
-      new(checked_currency.normalize_amount(amount), checked_currency)
+      amount = checked_currency.normalize_amount(amount)
+
+      amount.zero? ? Mint.zero(checked_currency) : new(amount, checked_currency)
     end
 
     # Builds a Money from a fractional (smallest-unit) Integer amount.
@@ -41,7 +43,8 @@ module Mint
       raise ArgumentError, "Currency not found (#{currency})" unless checked_currency
 
       amount = Rational(fractional, checked_currency.fractional_multiplier)
-      new(amount, checked_currency)
+
+      amount.zero? ? Mint.zero(checked_currency) : new(amount, checked_currency)
     end
 
     # Returns a new Money object with the specified amount, or self if unchanged.
@@ -56,7 +59,14 @@ module Mint
     #   price.mint(10.00)  #=> [USD 10.00] (returns self)
     def mint(new_amount)
       new_amount = currency.normalize_amount(new_amount)
-      new_amount == amount ? self : Money.new(new_amount, currency)
+
+      if new_amount == amount
+        self
+      elsif new_amount.zero?
+        Mint.zero(currency)
+      else
+        Money.new(new_amount, currency)
+      end
     end
 
     private

data/lib/minting/money/format/formatting.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Mint
+  # Formatting functionality for Money objects
+  class Money
+    private
+
+    # Selects the appropriate format template and value based on the amount's sign.
+    # @private
+    def select_format(format)
+      negative_format = format[:negative]
+      zero_format = format[:zero]
+
+      if amount.negative? && negative_format
+        [negative_format, -amount]
+      elsif amount.zero? && zero_format
+        [zero_format,     amount]
+      else
+        [format[:positive], amount]
+      end
+    end
+
+    # Validates that format hash contains only known keys.
+    # @private
+    def validate_format_hash(format)
+      unknown = format.keys - %i[positive negative zero]
+
+      raise ArgumentError, "Unknown format parameter(s): #{unknown.inspect}. " unless unknown.empty?
+    end
+
+    # Applies a format template to produce a formatted string representation.
+    # @private
+    def format_amount(format)
+      format, value = select_format(format)
+      format ||= '%<symbol>s%<amount>f'
+      # Automatically adjust decimal places based on currency subunit if missing
+      format = format.gsub(/%<amount>(\s*\+?\d*)f/, "%<amount>\\1.#{currency.subunit}f")
+
+      refs = format.scan(/%<(\w+)>/).flatten.map(&:to_sym)
+      all_args = { amount: value, currency: currency_code, symbol: currency.symbol }
+      Kernel.format(format, **all_args.slice(*refs))
+    end
+  end
+end

data/lib/minting/money/{formatting.rb → format/to_s.rb}

@@ -63,37 +63,5 @@ module Mint
 
       width ? formatted.rjust(width) : formatted
     end
-
-    private
-
-    def select_format(format)
-      negative_format = format[:negative]
-      zero_format = format[:zero]
-
-      if amount.negative? && negative_format
-        [negative_format, -amount]
-      elsif amount.zero? && zero_format
-        [zero_format,     amount]
-      else
-        [format[:positive], amount]
-      end
-    end
-
-    def validate_format_hash(format)
-      unknown = format.keys - %i[positive negative zero]
-
-      raise ArgumentError, "Unknown format parameter(s): #{unknown.inspect}. " unless unknown.empty?
-    end
-
-    def format_amount(format)
-      format, value = select_format(format)
-      format ||= '%<symbol>s%<amount>f'
-      # Automatically adjust decimal places based on currency subunit if missing
-      format = format.gsub(/%<amount>(\s*\+?\d*)f/, "%<amount>\\1.#{currency.subunit}f")
-
-      refs = format.scan(/%<(\w+)>/).flatten.map(&:to_sym)
-      all_args = { amount: value, currency: currency_code, symbol: currency.symbol }
-      Kernel.format(format, **all_args.slice(*refs))
-    end
   end
 end