minting 2.2.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4599b829514f80d36867c1ddd7afa3a00a6ea1a718883ce46ea250fc58f4deff
-  data.tar.gz: cabdea47ab90088ae53582ccacdf9695a6153230aff0f2e986af00191d8eeb05
+  metadata.gz: 3af2c270bbab98102901e0f9c1aefb22966d916805cd04a7eab8e867fe9f59be
+  data.tar.gz: 109d647aceff1385f35135c91b1728237965e549de4744717ff28956f4e33659
 SHA512:
-  metadata.gz: a1bf6f69bb7513c6ec7b3a0b1e3838e0a87add33c57b82b652d8c4e8951539abfccdbd0cf3fa42220a9dc0efce6b64afb426aebd63c2c4ae3e10614d5245e4c5
-  data.tar.gz: 5e896ab547e87ed89c6d2e30252840b43bf5a4808ba49f82ce2b9dcb55a7d9ccaffe75d0f7ec6c228d7d1bad3c93b9bde3112553704a6d1d4e1dd43f636450ed
+  metadata.gz: 3ac0ee4402ad94a39aa256fdcefaa24333f89333de1ee216b7ca698e493fb2410d771115c8a7e694d7acec8228bb5301db8ba6643e1e277bf87aa2aaf132b65d
+  data.tar.gz: 41e8ff87efe32f54185a96fc7e9781c02304a9a24b3090bb50bd5f8532488ab581c08ccbf2be47d469d18d63fed9fda2cf74776bf066dc8aac48aca982bb90e7

data/README.md

@@ -12,7 +12,7 @@
 
 
 
-> **Status:** Minting 2.2 is released. The core API (`Money`, `Currency`, formatting, parsing) is stable.
+> **Status:** Minting 2.3 is released. The core API (`Money`, `Currency`, formatting, parsing) is stable.
 
 ```ruby
 price = Money.from(19.99, 'USD')       #=> [USD 19.99]
@@ -119,7 +119,7 @@ What it's become along the way:
 
 - **Exact by construction** — amounts are `Rational` internally, rounded to the currency's subunit only when needed. No silent precision loss from repeated arithmetic.
 - **No Rails dependency** — Minting is a plain Ruby gem. Use it in a script, a Sinatra app, a background job runner, or a Rails app — your choice, not the gem's.
-- **Formatting that doesn't fight you** — `Kernel.format`-style templates, named presets (`:accounting`, `:european`), per-sign formats (parentheses for negatives), and a pluggable locale hook.
+- **Formatting that doesn't fight you** — `Kernel.format`-style templates, per-sign formats (parentheses for negatives), explicit sign and magnitude placeholders, and a pluggable locale hook.
 - **Built for real-world currency handling** — 150+ ISO-4217 currencies, correct subunit handling (JPY has none, KWD has three), proportional allocation/split that doesn't lose cents to rounding.
 - **Measured, not assumed, performance** — see the [Performance Guide](bench/BENCHMARKS.md) for actual benchmarks rather than claims.
 - **Rails-ready without being Rails-only** — pair with the companion [MoneyAttribute](https://github.com/gferraz/money-attribute) gem for `ActiveRecord` type casting, validators, and form helpers.
@@ -207,6 +207,7 @@ price.format('%<amount>d')            #=> "9"
 price.format('%<symbol>s%<amount>f')  #=> "$9.99"
 price.format('%<symbol>s%<amount>+f') #=> "$+9.99"
 (-price).format('%<amount>f')         #=> "-9.99"
+(-price).format('%<sign>s%<symbol>s%<magnitude>f') #=> "-$9.99"
 
 # Format with padding
 price_in_euros = Money.from(12.34, 'EUR')
@@ -220,6 +221,8 @@ price_in_euros.format('%<symbol>2s%<amount>+10f')    #=> " €    +12.34"
 price.format('%<integral>d %<fractional>d/100')        #=> "9 99/100"
 Money.from(0.99, 'USD').format('%<integral>d dollars and %<fractional>02d cents')
 #=> "0 dollars and 99 cents"
+(-Money.from(0.99, 'USD')).format('%<sign>s%<integral>d.%<fractional>02d')
+#=> "-0.99"
 
 # Per-sign Hash format (e.g. accounting parentheses for losses)
 loss = Money.from(-1234.56, 'USD')
@@ -269,7 +272,7 @@ Money.parse('USD 1,234.56')     #=> [USD 1234.56]
 
 Notes:
 - Pass a currency code when the string has no symbol or code.
-- The optional currency argument is a default, not an override: a code or symbol embedded in the string takes precedence (`Money.parse('10 EUR', 'USD')` returns EUR).
+- The optional `default_currency:` argument is a default, not an override: a code or symbol embedded in the string takes precedence (`Money.parse('10 EUR', default_currency: 'USD')` returns EUR). The positional currency argument is deprecated.
 - `1,234` means 1234, not 1.234, and `1,23` means 1.23, not 123.
 - `1,234.00` is unambiguous (thousands + decimal).
 - Parsing is separator-positional rather than locale-aware. For currencies
@@ -277,6 +280,16 @@ Notes:
   as a thousands separator: `Money.parse('KWD 861,949')` means 861949 KWD.
   Use a period decimal (`KWD 861.949`) or both separators (`KWD 1.234,567`)
   when the intended value has three fractional digits.
+- Pass the input source's decimal separator explicitly when a single separator
+  followed by three digits is ambiguous: `Money.parse('123,456', 'EUR',
+  decimal: ',')` means `123.456`, while `decimal: '.'` means `123456`. The
+  default currency can be passed positionally or as `default_currency: 'EUR'`. When
+  the input is an integer with grouping, pass `thousand:` explicitly instead:
+  `Money.parse('123,456', 'USD', thousand: ',')` means `123456`. When both
+  options are supplied, they define the roles independently, so a decimal
+  separator that is absent from the input is also valid:
+  `Money.parse('123,456', 'USD', decimal: ':', thousand: ',')` means `123456`.
+  When both options are omitted, the positional rules above remain in effect.
 - Accounting negatives like `($1.23)` or `(USD 10.00)` are supported — the parser detects parentheses and negates the amount.
 - Ambiguous symbols like `$` resolve by currency priority (currently USD).
 - The parser scans all uppercase words for registered codes, so spurious non-currency words before the real code are correctly ignored: `Money.parse("MAX 10.00 USD")` yields `[USD 10.00]`.
@@ -389,6 +402,18 @@ Money.from(9.99, 'BRL').format  #=> "R$9,99"
 
 **Exact amounts** — Amounts are stored as `Rational` and rounded to the currency subunit.
 
+**Sign and magnitude placeholders** — `%<amount>` retains its sign.
+`%<magnitude>` always renders the absolute value, while `%<sign>` renders `+`
+for positive values, `-` for negative values, and an empty string for zero.
+Use a width of `1` to reserve the sign column for zero values:
+
+```ruby
+format = '%<sign>1s%<symbol>s%<magnitude>f'
+Money.from(12.34, 'BRL').format(format, decimal: ',')  #=> "+R$12,34"
+Money.from(-12.34, 'BRL').format(format, decimal: ',') #=> "-R$12,34"
+Money.from(0, 'BRL').format(format, decimal: ',')      #=> " R$0,00"
+```
+
 **Rounding modes** — Wrap operations in `Money.with_rounding(mode)` to change how amounts are rounded to the subunit:
 
 ```ruby
@@ -444,17 +469,19 @@ price.clamp(Money.from(8, 'USD')..Money.from(12, 'USD')) #=> [USD 10.00]
 **Allocation** — `split(n)` requires a positive integer. `allocate(ratios)`
 requires a non-empty list whose total is non-zero. Both preserve the original
 amount after subunit rounding; any leftover smallest units go to the first
-slots. Ratios may be negative, but use them only when that distribution is
-intentional.
+slots. Ratios may be negative and produce signed allocations, but use them only
+when that distribution is intentional:
 
 ```ruby
 Money.from(10, 'USD').split(3)       #=> [[USD 3.34], [USD 3.33], [USD 3.33]]
 Money.from(10, 'USD').allocate([1, 2, 3]) #=> [[USD 1.67], [USD 3.33], [USD 5.00]]
+Money.from(10, 'USD').allocate([-1, 2])   #=> [[USD -10.00], [USD 20.00]]
 ```
 
 **Conversions and serialization** — `to_r` is exact, `to_d` returns a
 BigDecimal, and `to_f` can lose precision. `to_hash` and `from_hash` provide a
-string-safe round trip:
+string-safe round trip. JSON and Rails `as_json` integration belong to the
+`money_attribute` companion gem, not the core Minting gem:
 
 ```ruby
 money = Money.from(9.99, 'USD')
@@ -471,7 +498,7 @@ older supported Rubies.
 
 
 
-**Registered currencies** — `Money::Currency.register(code:, subunit:, symbol:, priority:)` adds custom currencies. Only registered codes and symbols are recognized by the parser or searches. You don't need to register a currency to use it with most features.
+**Registered currencies** — `Money::Currency.register(code:, subunit:, symbol:, priority:, country:, name:, disambiguate_symbol:)` adds custom currencies. `country`, `name`, and `disambiguate_symbol` are optional metadata fields; `disambiguate_symbol` is also used by `%<dsymbol>s` and symbol parsing. Only registered codes and symbols are recognized by the parser or searches. You don't need to register a currency to use it with most features.
 
 **Built-in currencies** — 150+ ISO-4217 world currencies ship in `lib/minting/data/world-currencies.yaml` and are preloaded at gem initialization.
 

data/doc/agents/AGENTS.md

@@ -191,7 +191,10 @@ formatting fast path; call `format` or `to_fs` for custom output.
 
 Format strings use `Kernel.format` named-reference syntax:
 `%<symbol>s`, `%<amount>f`, `%<amount>d`, `%<currency>s`, `%<integral>d`,
-`%<fractional>d`. The `%<amount>f` specifier has the currency's subunit
+`%<fractional>d`. `%<amount>` is signed, `%<magnitude>` and `%<fractional>` are
+non-negative, and `%<sign>` exposes `+`, `-`, or an empty string for zero. Use
+`%<sign>` for explicit sign placement, especially for amounts between -1 and 1.
+The `%<amount>f` and `%<magnitude>f` specifiers have the currency's subunit
 precision **injected at runtime** (e.g. `%<amount>f` → `%<amount>.2f` for
 USD) by a gsub in `format/formatter.rb`. For zero-subunit currencies (JPY),
 `%<fractional>d` receives zero.
@@ -204,6 +207,9 @@ Compiled formatters are retained in a thread-safe, copy-on-write cache capped
 at 256 configurations. Once full, new configurations are compiled for the
 call but not retained. Do not assume `Formatter.cache` is mutable.
 
+Minting's core serialization API is `to_hash`/`from_hash`; JSON and Rails
+`as_json` integration are provided by the `money_attribute` companion gem.
+
 `Mint.locale_backend=` (a callable or Hash returning
 `{ decimal:, thousand:, format: }`) supplies defaults when the corresponding
 kwarg is nil. This is how `attribute-money` wires I18n. See

data/lib/minting/currency/currency.rb

@@ -89,13 +89,7 @@ module Mint
     #   usd.normalize_amount("5.25")  #=> (21/4)
     #
     # @see Money.with_rounding Custom rounding modes via {Money.with_rounding}
-    def normalize_amount(amount)
-      if Currency.custom_rounding_active?
-        amount.to_r.round(subunit, half: Thread.current[Currency::ROUNDING_THREAD_KEY])
-      else
-        amount.to_r.round(subunit)
-      end
-    end
+    def normalize_amount(amount) = amount.to_r.round(subunit)
 
     # Returns the cached frozen zero-Money for this currency.
     #

data/lib/minting/currency/registry.rb

@@ -32,11 +32,15 @@ module Mint
   # @param subunit [Integer] the decimal subunit precision, defaults to 0
   # @param symbol [String] the display symbol
   # @param priority [Integer] parser precedence priority
+  # @param country [String, nil] associated country code
+  # @param name [String, nil] currency name
+  # @param disambiguate_symbol [String, nil] symbol variant for disambiguation
   # @return [Currency] the newly registered Currency instance
   # @raise [ArgumentError] if the code contains invalid characters
   # @raise [KeyError] if the currency code is already registered
-  def Currency.register(code:, subunit: 0, symbol: '', priority: 0)
-    Registry.register(code:, subunit:, symbol:, priority:)
+  def Currency.register(code:, subunit: 0, symbol: '', priority: 0, country: nil, name: nil,
+                        disambiguate_symbol: nil)
+    Registry.register(code:, subunit:, symbol:, priority:, country:, name:, disambiguate_symbol:)
   end
 
   # Registers all built-in crypto currencies at once.

data/lib/minting/currency/rounding.rb

@@ -4,6 +4,14 @@
 module Mint
   # :nodoc:
   class Currency
+    # Replaces the default normalization method after custom rounding is first
+    # requested, keeping the default path free of dispatch and thread checks.
+    module CustomRounding
+      def normalize_amount(amount)
+        amount.to_r.round(subunit, half: Thread.current[Currency::ROUNDING_THREAD_KEY] || :up)
+      end
+    end
+
     # @api private
     VALID_ROUNDING_MODES = %i[up down even].freeze
 
@@ -17,7 +25,12 @@ module Mint
     # Activates the custom rounding dispatch path in {#normalize_amount}.
     # Once called, this cannot be reversed for the lifetime of the process.
     # @api private
-    def self.activate_custom_rounding! = @custom_rounding_active = true
+    def self.activate_custom_rounding!
+      return if @custom_rounding_active
+
+      @custom_rounding_active = true
+      prepend(CustomRounding)
+    end
 
     # Returns the currently active rounding mode, falling back to +:up+.
     # @api private

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

@@ -6,5 +6,5 @@ class String
   #
   # @param currency [String, Currency] default currency when self has no currency marker
   # @return [Money]
-  def to_money(currency = nil) = Mint::Money.parse(self, currency)
+  def to_money(currency = nil) = Mint::Money.parse(self, default_currency: currency)
 end

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

@@ -42,7 +42,8 @@ module Mint
 
       codes.map do |code|
         c = entries[index[code]]
-        Currency.register(code:, subunit: c.subunit, symbol: c.symbol, priority: c.priority)
+        Currency.register(code:, subunit: c.subunit, symbol: c.symbol, priority: c.priority,
+                          country: c.country, name: c.name, disambiguate_symbol: c.disambiguate_symbol)
       end
     end
 
@@ -54,7 +55,8 @@ module Mint
     # @return [Array<Currency>] the newly registered Currency objects
     def self.register_all_crypto
       crypto_currencies.map do |c|
-        Currency.register(code: c.code, subunit: c.subunit, symbol: c.symbol, priority: c.priority)
+        Currency.register(code: c.code, subunit: c.subunit, symbol: c.symbol, priority: c.priority,
+                          country: c.country, name: c.name, disambiguate_symbol: c.disambiguate_symbol)
       end
     end
   end

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

@@ -9,10 +9,14 @@ module Mint
     # @param subunit [Integer] the decimal subunit precision, defaults to 0
     # @param symbol [String] the display symbol
     # @param priority [Integer] parser precedence priority
+    # @param country [String, nil] associated country code
+    # @param name [String, nil] currency name
+    # @param disambiguate_symbol [String, nil] symbol variant for disambiguation
     # @return [Currency] the newly registered Currency instance
     # @raise [ArgumentError] if the code contains invalid characters
     # @raise [KeyError] if the currency code is already registered
-    def self.register(code:, subunit: 0, symbol: '', priority: 0)
+    def self.register(code:, subunit: 0, symbol: '', priority: 0, country: nil, name: nil,
+                      disambiguate_symbol: nil)
       raise ArgumentError, 'Currency code must be String' unless code.is_a? String
       unless code.match?(/^[A-Z_]+$/)
         raise ArgumentError,
@@ -22,7 +26,7 @@ module Mint
       MUTEX.synchronize do
         raise KeyError, "Currency: #{code} already registered" if currencies[code]
 
-        currency = Currency.new(code:, subunit:, symbol:, priority:)
+        currency = Currency.new(code:, subunit:, symbol:, priority:, country:, name:, disambiguate_symbol:)
         @currencies = @currencies.merge(code => currency).freeze
         @symbols_list = nil
         currency

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

@@ -5,13 +5,18 @@ module Mint
   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
+    # @param proportions [Array<Numeric>] a list of numeric proportions/ratios to allocate by.
+    #   Negative ratios produce signed allocations and should be used only when
+    #   that distribution is intentional.
     # @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 = Money.from(10.00, 'USD')
     #   money.allocate([1, 2, 3]) #=> [[USD 1.67], [USD 3.33], [USD 5.00]]
+    #
+    # @example Signed allocation
+    #   money.allocate([-1, 2]) #=> [[USD -10.00], [USD 20.00]]
     def allocate(proportions)
       whole = proportions.sum.to_r
       raise ArgumentError, 'Need at least 1 proportion element' if proportions.empty?

data/lib/minting/money/conversion.rb

@@ -57,6 +57,9 @@ module Mint
     # @example Round-trip
     #   m = Money.from(134120, "BRL")
     #   Money.from_hash(m.to_hash) == m  #=> true
+    #
+    # JSON and Rails `as_json` integration are provided by the
+    # +money_attribute+ companion gem rather than the core Minting gem.
     def self.from_hash(hash)
       currency = Currency.resolve!(hash[:currency] || hash['currency'])
       amount = currency.normalize_amount(Rational(hash[:amount] || hash['amount']))

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

@@ -7,7 +7,12 @@ module Mint
     # and decimal separator.
     #
     # @param template [String, Hash, nil] Either a format string with placeholders
-    #   (%<symbol>s, %<amount>f, %<currency>s, %<integral>d, %<fractional>d, %<dsymbol>s),
+    #   (%<symbol>s, %<amount>f, %<magnitude>f, %<sign>s, %<currency>s,
+    #   %<integral>d, %<fractional>d, %<dsymbol>s),
+    #   `%<amount>` is signed; `%<magnitude>` is always non-negative; `%<fractional>`
+    #   is the non-negative fractional component; and `%<sign>` is `+`, `-`, or
+    #   an empty string for zero. Use `%<sign>` when the sign needs explicit
+    #   placement, especially for amounts between -1 and 1.
     #   or a Hash with per-sign keys (:positive, :negative, :zero) each
     #   holding a format string. A Hash is convenient for sign-aware formats
     #   such as accounting parentheses:
@@ -44,12 +49,16 @@ module Mint
     #   money.format('%<currency>s %<amount>f')                 #=> "USD 1234.56"
     #   money.format('%<amount>f %<symbol>s')                   #=> "1234.56 $"
     #   money.format('%<symbol>s%<amount>+f')                   #=> "$+1234.56"
+    #   money.format('%<sign>s%<symbol>s%<magnitude>f')          #=> "+$1234.56"
     #
     # @example Integral & fractional parts
     #   money.format('%<integral>d.%<fractional>02d')            #=> "1234.56"
     #   price = Money.from(0.99, 'USD')
     #   price.format('%<integral>d dollars and %<fractional>02d cents')
     #   #=> "0 dollars and 99 cents"
+    #   loss = Money.from(-0.99, 'USD')
+    #   loss.format('%<sign>s%<integral>d.%<fractional>02d')
+    #   #=> "-0.99"
     #
     # @example Per-sign Hash format (accounting parentheses)
     #   loss = Money.from(-1234.56, 'USD')

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

@@ -52,12 +52,11 @@ module Mint
       end
 
       def initialize(format, decimal, thousand)
-        @format = format
         @decimal = decimal
-        @thousand = thousand
-        compile
+        compile(format:, thousand:)
       end
 
+      SIGNS = { -1 => '-', 0 => '', 1 => '+' }.freeze
       SUBUNIT_PLACEHOLDER = "\uE000"
       # Matches a digit followed by groups of exactly 3 digits that terminate
       # at a non-digit or end-of-string. Used to insert thousand separators.
@@ -70,9 +69,12 @@ module Mint
 
         templates = @has_placeholder ? @templates_by_subunit[currency.subunit] : @templates
 
-        template = templates[amount <=> 0] || templates[1]
+        cmp = amount <=> 0
+        template = templates[cmp] || templates[1]
+        sign = SIGNS[cmp]
 
-        display_amount = @has_negative_template && amount < 0 ? -amount : amount
+        magnitude = amount.abs
+        display_amount = @has_negative_template ? magnitude : amount
         integral = display_amount.to_i
 
         result = Kernel.format(template,
@@ -80,6 +82,8 @@ module Mint
                                dsymbol: @needs_dsymbol && currency.dsymbol,
                                symbol: currency.symbol,
                                amount: display_amount,
+                               magnitude:,
+                               sign:,
                                integral: integral,
                                fractional: @needs_fractional ? money.fractional.abs : 0)
         apply_separators(result, integral)
@@ -100,25 +104,27 @@ module Mint
         result
       end
 
-      def compile
-        @templates = { -1 => @format[:negative], 0 => @format[:zero], 1 => @format[:positive] || Money::DEFAULT_FORMAT }
+      def compile(format:, thousand:)
+        @templates = { -1 => format[:negative], 0 => format[:zero], 1 => format[:positive] || Money::DEFAULT_FORMAT }
         @templates.compact!
-        # Inject subunit precision into %<amount>f specs that lack an explicit
-        # precision. Matches "%<amount>f" or "%+10<amount>f" (with optional
-        # flags/width before the named ref) and appends a placeholder for the
-        # currency subunit digits — e.g. "%<amount>f" → "%<amount>\uE000f".
+
+        # Inject subunit precision into amount and magnitude f specs that lack
+        # an explicit precision. Matches "%<amount>f" or "%<magnitude>f" and
+        # appends a placeholder for the currency subunit digits.
         # The placeholder is later replaced with the actual subunit count at
         # format time (e.g. "\uE000" → "2" for USD, "0" for JPY).
-        @templates.transform_values! { |f| f.gsub(/%<amount>(\s*\+?\d*)f/, "%<amount>\\1.#{SUBUNIT_PLACEHOLDER}f") }
+        @templates.transform_values! do |f|
+          f.gsub(/%<(amount|magnitude)>(\s*\+?\d*)f/, "%<\\1>\\2.#{SUBUNIT_PLACEHOLDER}f")
+        end
         @has_negative_template = @templates.key?(-1)
-
         joined = @templates.values.join
         @needs_fractional = joined.include?('%<fractional>')
         @needs_dsymbol = joined.include?('%<dsymbol>')
-
-        @needs_thousand_substitution = @thousand && !@thousand.empty? &&
-                                       (joined.include?('%<amount>') || joined.include?('%<integral>'))
-        @thousand_replacement = "\\1#{@thousand}" if @needs_thousand_substitution
+        @needs_thousand_substitution = thousand && !thousand.empty? &&
+                                       (joined.include?('%<amount>') ||
+                                        joined.include?('%<magnitude>') ||
+                                        joined.include?('%<integral>'))
+        @thousand_replacement = "\\1#{thousand}" if @needs_thousand_substitution
 
         @has_placeholder = joined.include?(SUBUNIT_PLACEHOLDER)
         return unless @has_placeholder

data/lib/minting/money/money.rb

@@ -52,7 +52,8 @@ module Mint
 
     alias to_i integral
 
-    # Returns the fractional part of the amount.
+    # Returns the signed fractional part of the amount. Formatting templates
+    # expose this value as a magnitude through `%<fractional>d`.
     # @example
     #   Money.from(1234.56, 'USD').fractional  #=> 56
     #   Money.from(1000, 'JPY').fractional     #=> 0

data/lib/minting/money/parse/separator_parser.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Mint
+  class Money
+    # Parses numeric input when the decimal separator is explicitly known.
+    # @api private
+    module SeparatorParser
+      module_function
+
+      def parse(numeric, decimal, thousand)
+        decimal, thousand = separators(decimal, thousand)
+        return nil unless decimal && thousand && decimal != thousand
+
+        sign = numeric.start_with?('-', '+') ? numeric[0] : ''
+        unsigned = numeric.delete_prefix(sign)
+        return nil if unsigned.count(decimal) > 1
+
+        return parse_decimal(sign, unsigned, decimal, thousand) if unsigned.include?(decimal)
+        return parse_thousands(sign, unsigned, thousand) if unsigned.include?(thousand)
+        return "#{sign}#{unsigned}" if unsigned.match?(/\A\d+\z/)
+
+        nil
+      end
+
+      def separators(decimal, thousand)
+        return [decimal, thousand] if decimal && thousand
+        return [decimal, decimal == ',' ? '.' : ','] if %w[. ,].include?(decimal)
+        return [thousand == ',' ? '.' : ',', thousand] if %w[. ,].include?(thousand)
+
+        nil
+      end
+      private_class_method :separators
+
+      def parse_decimal(sign, unsigned, decimal, thousand)
+        integral, fractional = unsigned.split(decimal, 2)
+        return nil unless valid_integer_part?(integral, thousand) && fractional.match?(/\A\d+\z/)
+
+        "#{sign}#{integral.delete(thousand)}.#{fractional}"
+      end
+      private_class_method :parse_decimal
+
+      def parse_thousands(sign, unsigned, thousand)
+        return nil unless valid_integer_part?(unsigned, thousand)
+
+        "#{sign}#{unsigned.delete(thousand)}"
+      end
+      private_class_method :parse_thousands
+
+      def valid_integer_part?(integer, thousand)
+        return integer.match?(/\A\d+\z/) unless integer.include?(thousand)
+
+        groups = integer.split(thousand)
+        groups.first.match?(/\A\d{1,3}\z/) && groups.drop(1).all? { |group| group.match?(/\A\d{3}\z/) }
+      end
+      private_class_method :valid_integer_part?
+    end
+
+    private_constant :SeparatorParser
+  end
+end

data/lib/minting/money/parse.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'parse/separator_parser'
+
 module Mint
   # :nodoc:
   class Money
@@ -8,8 +10,15 @@ module Mint
     # 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, Currency, nil] default currency when none is present in +input+
+    # @param positional_currency [String, Currency, nil] deprecated positional
+    #   fallback currency when none is present in +input+
+    # @param default_currency [String, Currency, nil] fallback currency when none is present in +input+
     #   An embedded currency code or symbol takes precedence over this argument.
+    #   The positional form is deprecated; use +default_currency:+ instead.
+    # @param decimal [String, nil] decimal separator used by the input source.
+    #   When omitted, it is inferred from +thousand:+ or separator positions.
+    # @param thousand [String, nil] thousands separator used by the input source.
+    #   When omitted, it is inferred from +decimal:+ or separator positions.
     # @return [Money, nil]
     #
     # @example With explicit currency
@@ -19,16 +28,23 @@ module Mint
     # @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)
+    #   Money.parse('123,456', 'EUR', decimal: ',') #=> [EUR 123.46]
+    #   Money.parse('123,456', 'USD', thousand: ',') #=> [USD 123456.00]
+    # @deprecated Pass the fallback currency as +default_currency:+.
+    def self.parse(input, positional_currency = nil, default_currency: nil, decimal: nil, thousand: nil)
+      if positional_currency
+        warn 'DEPRECATION: Money.parse positional currency is deprecated; use default_currency: instead.', uplevel: 1
+      end
       return nil unless input.is_a?(String)
 
       input = input.strip
       return nil if input.empty?
 
+      currency = default_currency || positional_currency
       currency = parse_currency(input, currency)
       return nil unless currency
 
-      amount = parse_amount(input, currency)
+      amount = parse_amount(input, currency, decimal:, thousand:)
       return nil unless amount
 
       amount = currency.normalize_amount(amount)
@@ -38,24 +54,36 @@ module Mint
     # Like {.parse} but raises on failure.
     #
     # @param input [String] Amount input, optionally including a currency symbol or code
-    # @param currency [String, Currency, nil] default currency when none is present in +input+
+    # @param positional_currency [String, Currency, nil] deprecated positional
+    #   fallback currency when none is present in +input+
+    # @param default_currency [String, Currency, nil] fallback currency when none is present in +input+
     #   An embedded currency code or symbol takes precedence over this argument.
+    #   The positional form is deprecated; use +default_currency:+ instead.
+    # @param decimal [String, nil] decimal separator used by the input source.
+    #   When omitted, it is inferred from +thousand:+ or separator positions.
+    # @param thousand [String, nil] thousands separator used by the input source.
+    #   When omitted, it is inferred from +decimal:+ or separator positions.
     # @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)
+    # @deprecated Pass the fallback currency as +default_currency:+.
+    def self.parse!(input, positional_currency = nil, default_currency: nil, decimal: nil, thousand: nil)
+      if positional_currency
+        warn 'DEPRECATION: Money.parse! positional currency is deprecated; use default_currency: instead.', uplevel: 1
+      end
       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 = default_currency || positional_currency
       currency = parse_currency(input, currency)
       raise ArgumentError, "Currency [#{currency}] not found" unless currency
 
-      amount = parse_amount(input, currency)
+      amount = parse_amount(input, currency, decimal:, thousand:)
       raise ArgumentError, "Could not parse [#{input}]" unless amount
 
       amount = currency.normalize_amount(amount)
@@ -67,7 +95,7 @@ module Mint
 
       # Extracts one valid numeric value, allowing surrounding currency markers
       # and uppercase annotation words (for example, "MAX 10.00 USD").
-      def parse_amount(input, currency)
+      def parse_amount(input, currency, decimal: nil, thousand: nil)
         accounting_negative = input.start_with?('(') && input.end_with?(')')
         return nil if (input.include?('(') || input.include?(')')) && !accounting_negative
 
@@ -77,7 +105,7 @@ module Mint
         numeric_input.sub!(/\A([+-])\s+/, '\\1')
         return nil unless numeric_input.match?(/\A[+-]?\d[\d.,]*\z/)
 
-        numeric = parse_separators(numeric_input)
+        numeric = parse_separators(numeric_input, decimal:, thousand:)
         return nil unless numeric
 
         amount = Rational(numeric)
@@ -106,8 +134,15 @@ module Mint
         Currency.resolve(currency)
       end
 
-      # Converts locale-specific decimal/thousand separators into a plain decimal string.
-      def parse_separators(numeric)
+      # Converts decimal/thousand separators into a plain decimal string.
+      # An explicit decimal separator resolves otherwise ambiguous values.
+      def parse_separators(numeric, decimal: nil, thousand: nil)
+        return SeparatorParser.parse(numeric, decimal, thousand) if decimal || thousand
+
+        parse_heuristic_separators(numeric)
+      end
+
+      def parse_heuristic_separators(numeric)
         return nil unless numeric.match?(/\d/)
         return nil unless valid_numeric_syntax?(numeric)
 

data/lib/minting/money/rounding.rb

@@ -9,11 +9,10 @@ module Mint
     # Restores the previous mode (or default) when the block exits, even on
     # exception.
     #
-    # Rounding-mode support is activated on first call. Once activated,
-    # +Currency#normalize_amount+ dispatches through +Currency.rounding_mode+,
-    # adding ~10–35&ns of overhead to every money creation or mutation.
-    # When rounding modes are never used (the common case), the fast path
-    # incurs zero overhead.
+    # Rounding-mode support is activated on first call. Before activation,
+    # +Currency#normalize_amount+ uses a direct +Rational#round+ fast path with
+    # no thread-local lookup. Once activated, normalization reads the
+    # thread-local mode so custom rounding remains isolated per thread.
     #
     # @param mode [Symbol] one of: +:up+, +:down+, +:even+
     # @yield block to execute with the rounding mode active

data/lib/minting/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: minting
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.3.0
 platform: ruby
 authors:
 - Gilson Ferraz
@@ -79,6 +79,7 @@ files:
 - lib/minting/money/format/validator.rb
 - lib/minting/money/money.rb
 - lib/minting/money/parse.rb
+- lib/minting/money/parse/separator_parser.rb
 - lib/minting/money/rounding.rb
 - lib/minting/version.rb
 - minting.gemspec