minting 1.7.3 → 1.8.1

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

@@ -6,29 +6,58 @@ module Mint
 
   # Parses a human-readable money string into a {Money} object.
   #
+  # Returns +nil+ when the input is invalid or currency cannot be determined.
+  #
   # @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
+  # @return [Money, nil]
   #
   # @example With explicit currency
-  #   Money.parse('19.99', 'USD')    #=> [USD 19.99]
-  #   Money.parse('1.234,56', 'EUR') #=> [EUR 1234.56]
+  #   Mint.parse('19.99', 'USD')    #=> [USD 19.99]
+  #   Mint.parse('garbage', 'USD')  #=> nil
   #
   # @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]
+  #   Mint.parse('$19.99')            #=> [USD 19.99]
+  #   Mint.parse('USD 1,234.56')    #=> [USD 1234.56]
   def parse(input, currency = nil)
+    return nil unless input.is_a?(String)
+
+    input = input.strip
+    return nil if input.empty?
+
+    currency = parse_currency(input, currency)
+    return nil unless currency
+
+    amount = parse_amount(input)
+    return nil unless amount
+
+    amount = currency.normalize_amount(amount)
+    Mint::Money.new(amount, currency)
+  end
+
+  # Like {.parse} but raises on failure.
+  #
+  # @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
+  #   Mint.parse!('19.99', 'USD')    #=> [USD 19.99]
+  #   Mint.parse!('garbage', 'USD')  #=> ArgumentError
+  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 = Currency.resolve(currency) || parse_currency(input)
-    raise ArgumentError, "Currency [#{currency}] not registered" unless currency
+    currency = parse_currency(input, currency)
+    raise ArgumentError, "Currency [#{currency}] not found" unless currency
+
+    amount = parse_amount(input)
+    raise ArgumentError, "Could not parse [#{input}]" unless amount
 
-    amount = currency.normalize_amount(parse_amount(input))
+    amount = currency.normalize_amount(amount)
     Mint::Money.new(amount, currency)
   end
 
@@ -40,8 +69,11 @@ module Mint
     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))
+    numeric_input = input.scan(/[\d.,-]/).join
+    numeric = parse_separators(numeric_input)
+    return nil unless numeric
+
+    amount = Rational(numeric)
     accounting_negative ? -amount : amount
   end
 
@@ -51,12 +83,15 @@ module Mint
   # 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)
+  def parse_currency(input, currency = nil)
+    currency = Currency.resolve(currency)
+    return currency if currency
+
     input.scan(/\b([A-Z_]+)\b/) do |(code)|
-      currency = Mint.currency_for_code(code)
+      currency = Currency.for_code(code)
       return currency if currency
     end
 
-    Registry.detect_currency(input) or raise ArgumentError, 'Currency could not be detected'
+    Registry.detect_currency(input)
   end
 end

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

@@ -10,24 +10,26 @@ module Mint
   # @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)
+    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 :invalid         # 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)
+  def parse_separators(numeric)
+    return nil unless numeric.match?(/\d/)
+
     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 :invalid          then nil
     when :mixed # Commas and dots: the rightmost one is the decimal separator.
       if numeric.rindex(',') > numeric.rindex('.')
         numeric.delete('.').tr(',', '.')

data/lib/minting/mint/registry/zeros.rb

@@ -9,9 +9,11 @@ module Mint
     # @return [Money] a frozen zero-Money
     # @api private
     def self.zero_for(currency)
+      raise ArgumentError, "Expect a Currency param. (#{currency})" unless currency.is_a?(Currency)
+
       MUTEX.synchronize do
         @zeros ||= {}
-        @zeros[currency] ||= Mint::Money.send(:new, 0, currency)
+        @zeros[currency] ||= Mint::Money.send(:new, 0r, currency)
       end
     end
   end

data/lib/minting/mint/rounding.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Mint
+  # Rounding-mode dispatch table and block-scoped context.
+  # @api private
+  module Rounding
+    # Maps mode symbols to their corresponding +Rational+ rounding lambdas.
+    # @return [Hash{Symbol => Proc}]
+    # @api private
+    MODES = {
+      half_up: ->(amount, ndigits) { amount.round(ndigits, half: :up) },
+      half_down: ->(amount, ndigits) { amount.round(ndigits, half: :down) },
+      floor: ->(amount, ndigits) { amount.floor(ndigits) },
+      ceil: ->(amount, ndigits) { amount.ceil(ndigits) },
+      truncate: ->(amount, ndigits) { amount.truncate(ndigits) },
+      down: ->(amount, ndigits) { amount.truncate(ndigits) }
+    }.freeze
+
+    # Returns the currently active rounding mode, falling back to +:half_up+.
+    # @api private
+    # @return [Symbol]
+    def self.current_mode
+      Thread.current[:minting_rounding_mode] || :half_up
+    end
+
+    # Rounds +amount+ to +ndigits+ using the currently scoped rounding mode.
+    # @api private
+    # @param amount [Numeric]
+    # @param ndigits [Integer]
+    # @return [Rational]
+    def self.apply(amount, ndigits)
+      MODES.fetch(current_mode).call(amount.to_r, ndigits)
+    end
+
+    # Sets a rounding mode for the duration of a block, restoring the
+    # previous mode on exit (even on exception).
+    # @api private
+    # @param mode [Symbol]
+    # @yield block to execute with the mode active
+    # @raise [ArgumentError] on unknown mode
+    def self.with_mode(mode)
+      raise ArgumentError, "Unknown rounding mode: #{mode}" unless MODES.key?(mode)
+
+      prev = Thread.current[:minting_rounding_mode]
+      Thread.current[:minting_rounding_mode] = mode
+      yield
+    ensure
+      Thread.current[:minting_rounding_mode] = prev
+    end
+  end
+end

data/lib/minting/mint.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'mint/rounding'
 require_relative 'currency/currency'
 
 require_relative 'mint/dsl/numeric'

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

@@ -17,8 +17,7 @@ module Mint
       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) }
+      amounts = proportions.map { |rate| currency.normalize_amount(Rational(amount * rate, whole)) }
       allocate_left_over(amounts: amounts, left_over: amount - amounts.sum)
     end
   end

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

@@ -17,7 +17,7 @@ module Mint
     def split(slices)
       raise ArgumentError, 'Slices quantity must be an poitive integer' unless slices.positive? && slices.integer?
 
-      fraction = (amount / slices).round(currency.subunit)
+      fraction = currency.normalize_amount(amount / slices)
       allocate_left_over(amounts: Array.new(slices, fraction),
                          left_over: amount - (fraction * slices))
     end

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

@@ -6,7 +6,7 @@ module Mint
     # Returns the absolute value of the monetary amount as a new {Money} instance.
     #
     # @return [Money] the absolute value
-    def abs = mint(amount.abs)
+    def abs = copy_with(amount: amount.abs)
 
     # Returns true if the monetary amount is less than zero.
     #
@@ -22,6 +22,6 @@ module Mint
     # Enables standard ranges and stepping (e.g. `1.dollar..10.dollars`).
     #
     # @return [Money] successor Money instance
-    def succ = mint(amount + currency.minimum_amount)
+    def succ = copy_with(amount: amount + currency.minimum_amount)
   end
 end

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

@@ -11,7 +11,7 @@ module Mint
     def +(addend)
       case addend
       in 0 then self
-      in Money if same_currency?(addend) then mint(amount + addend.amount)
+      in Money if same_currency?(addend) then copy_with(amount: amount + addend.amount)
       else raise TypeError, "#{addend} can't be added to #{self}"
       end
     end
@@ -24,7 +24,7 @@ module Mint
     def -(subtrahend)
       case subtrahend
       when 0     then return self
-      when Money then return mint(amount - subtrahend.amount) if same_currency?(subtrahend)
+      when Money then return copy_with(amount: amount - subtrahend.amount) if same_currency?(subtrahend)
       end
       raise TypeError, "#{subtrahend} can't be subtracted from #{self}"
     end
@@ -32,7 +32,7 @@ module Mint
     # Unary negation operator. Returns a new {Money} instance with the inverted sign.
     #
     # @return [Money] negated Money instance
-    def -@ = mint(-amount)
+    def -@ = copy_with(amount: -amount)
 
     # Performs multiplication of the monetary value by a standard scalar Numeric.
     #
@@ -42,7 +42,7 @@ module Mint
     def *(multiplicand)
       raise TypeError, "#{self} can't be multiplied by #{multiplicand}" unless multiplicand.is_a?(Numeric)
 
-      mint(amount * multiplicand)
+      copy_with(amount: amount * multiplicand)
     end
 
     # Performs division of the monetary value by a scalar Numeric or identical currency {Money}.
@@ -53,7 +53,7 @@ module Mint
     # @raise [ZeroDivisionError] if division by zero is attempted
     def /(divisor)
       case divisor
-      when Numeric then return mint(amount / divisor)
+      when Numeric then return copy_with(amount: amount / divisor)
       when Money   then return amount / divisor.amount if same_currency? divisor
       end
       raise TypeError, "#{self} can't be divided by #{divisor}"
@@ -65,7 +65,7 @@ module Mint
     # @return [Money] reult of amount ** exponent
     # @raise [TypeError] if exponent is not Numeric
     def **(exponent)
-      return mint(amount**exponent) if exponent.is_a?(Numeric)
+      return copy_with(amount: amount**exponent) if exponent.is_a?(Numeric)
 
       raise TypeError, "#{self} can't be powered by #{exponent}"
     end

data/lib/minting/money/clamp.rb

@@ -47,7 +47,7 @@ module Mint
       else
         min = min_or_range
       end
-      mint(amount.clamp(normalize_boundary(min), normalize_boundary(max)))
+      copy_with(amount: amount.clamp(normalize_boundary(min), normalize_boundary(max)))
     end
 
     private

data/lib/minting/money/coercion.rb

@@ -44,7 +44,7 @@ module Mint
       # 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)
+        other.copy_with(amount: @value * other.amount)
       end
 
       # @private

data/lib/minting/money/comparable.rb

@@ -44,6 +44,12 @@ module Mint
     # @return [self, nil] self if amount is non-zero, nil otherwise
     def nonzero? = amount.nonzero?
 
+    # Helper method to verify if another Money has the identical currency.
+    #
+    # @param other [Money] the target currency to compare
+    # @return [Boolean] true if currencies match, false otherwise
+    def same_currency?(other) = other.currency == currency
+
     # @return [Boolean] true if amount is zero
     def zero? = amount.zero?
   end

data/lib/minting/money/constructors.rb

@@ -7,13 +7,56 @@ module Mint
     # @param amount [Numeric] The monetary amount
     # @param currency [Currency, String] The currency code or currency object
     # @raise [ArgumentError] If amount is not numeric or currency is invalid
-    def self.create(amount, currency)
+    def self.from(amount, currency)
       raise ArgumentError, 'amount must be Numeric' unless amount.is_a?(Numeric)
 
       currency = Currency.resolve!(currency)
       amount = currency.normalize_amount(amount)
 
-      amount.zero? ? Mint.zero(currency) : new(amount, currency)
+      amount.zero? ? currency.zero : new(amount, currency)
+    end
+
+    # Parses a human-readable money string into a {Money} object.
+    #
+    # Returns +nil+ when the input is invalid or currency cannot be determined.
+    #
+    # @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, nil]
+    #
+    # @example With explicit currency
+    #   Money.parse('19.99', 'USD')    #=> [USD 19.99]
+    #   Money.parse('garbage', 'USD')  #=> nil
+    #
+    # @example With symbol or code in the string
+    #   Money.parse('$19.99')            #=> [USD 19.99]
+    #   Money.parse('USD 1,234.56')    #=> [USD 1234.56]
+    def self.parse(input, currency = nil) = Mint.parse(input, currency)
+
+    # Like {.parse} but raises on failure.
+    #
+    # @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
+    #   Money.parse!('19.99', 'USD')    #=> [USD 19.99]
+    #   Money.parse!('garbage', 'USD')  #=> ArgumentError
+    def self.parse!(input, currency = nil) = Mint.parse!(input, currency)
+
+    # Returns a frozen zero Money in the given currency.
+    #
+    # @param currency [String, Currency] a currency code or object
+    # @return [Money] a frozen zero-Money
+    # @raise [ArgumentError] if the currency can't be resolved
+    def self.zero(currency) = Currency.resolve!(currency).zero
+
+    # Backwards-compatible alias for previous API
+    # TODO: deprecate in a future major release
+    def self.create(amount, currency)
+      warn 'Money.create is now deprecated. Use Money.from'
+      from(amount, currency)
     end
 
     # Builds a Money from a fractional (smallest-unit) Integer amount.
@@ -39,31 +82,36 @@ module Mint
 
       currency = Currency.resolve!(currency)
       amount = Rational(fractional, currency.fractional_multiplier)
-      amount.zero? ? Mint.zero(currency) : new(amount, currency)
+      amount.zero? ? currency.zero : new(amount, currency)
     end
 
     # Returns a new Money object with the specified amount, or self if unchanged.
     # This is the primary method for creating a modified copy of a Money instance
     # while preserving immutability.
     #
-    # @param new_amount [Numeric] The new monetary amount
+    # @param amount [Numeric] The new monetary amount
     # @return [Money] A new Money object with the new amount, or self if the amount is unchanged
     # @example
     #   price = Mint.money(10.00, 'USD')
-    #   price.mint(15.00)  #=> [USD 15.00]
-    #   price.mint(10.00)  #=> [USD 10.00] (returns self)
-    def mint(new_amount)
-      new_amount = currency.normalize_amount(new_amount)
+    #   price.copy_with(amount: 15.00)  #=> [USD 15.00]
+    #   price.copy_with(amount: 10.00)  #=> [USD 10.00] (returns self)
+    def copy_with(amount:)
+      amount = currency.normalize_amount(amount)
 
-      if new_amount == amount
+      if amount == self.amount
         self
-      elsif new_amount.zero?
-        Mint.zero(currency)
+      elsif amount.zero?
+        currency.zero
       else
-        Money.new(new_amount, currency)
+        Money.new(amount, currency)
       end
     end
 
+    def mint(new_amount)
+      warn 'Money#mint is now deprecated and will be removed in v2'
+      copy_with(amount: new_amount)
+    end
+
     private
 
     # Initializes a new Money object with the given amount and currency.

data/lib/minting/money/money.rb

@@ -49,11 +49,5 @@ module Mint
     def inspect
       Kernel.format "[#{currency_code} %0.#{currency.subunit}f]", amount
     end
-
-    # Helper method to verify if another object has the identical currency.
-    #
-    # @param other [Currency] the target currency to compare
-    # @return [Boolean] true if currencies match, false otherwise
-    def same_currency?(other) = other.currency == currency
   end
 end

data/lib/minting/version.rb

@@ -3,5 +3,5 @@
 # Root namespace for the Minting library.
 module Minting
   # Current version of the Minting gem.
-  VERSION = '1.7.3'
+  VERSION = '1.8.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: minting
 version: !ruby/object:Gem::Version
-  version: 1.7.3
+  version: 1.8.1
 platform: ruby
 authors:
 - Gilson Ferraz
@@ -42,10 +42,12 @@ files:
 - doc/Mint/Money.html
 - doc/Mint/RangeStepPatch.html
 - doc/Mint/Registry.html
+- doc/Mint/Rounding.html
 - doc/Mint/UnknownCurrency.html
 - doc/Minting.html
 - doc/_index.html
 - doc/agents/api_review-2026-06-15.md
+- doc/agents/copilot-instructions.md
 - doc/agents/expired/AGENTS.md
 - doc/agents/expired/copilot-instructions.md
 - doc/agents/expired/gemini_gem_evaluation.md
@@ -81,6 +83,7 @@ files:
 - lib/minting/mint/registry/registry.rb
 - lib/minting/mint/registry/symbols.rb
 - lib/minting/mint/registry/zeros.rb
+- lib/minting/mint/rounding.rb
 - lib/minting/money/allocation/allocation.rb
 - lib/minting/money/allocation/split.rb
 - lib/minting/money/arithmetics/methods.rb