minting 2.1.1 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f1cb21299dcb5f2a07ce7ace30463640372647eca9fbbfdf8d667e5a8c12d86b
-  data.tar.gz: 90838c1838f18a3892cedbe2ea3583d1103356479eb04fe3d51b9214fa05ffa3
+  metadata.gz: 3af2c270bbab98102901e0f9c1aefb22966d916805cd04a7eab8e867fe9f59be
+  data.tar.gz: 109d647aceff1385f35135c91b1728237965e549de4744717ff28956f4e33659
 SHA512:
-  metadata.gz: db903188b6e59832572d8d7161672f38b293d34bdca45c3d1bfff6bd8906e4f2bfa471530067f31196e619ae0ef9465026f23e3d7e852d9fb1661c742d40c070
-  data.tar.gz: a27d66b6395e6e980ed22965dbe94abdf9b9ce23f3bfe186c03257e62721b274ebe50703173faa8c1b91ef87aaa8c8f7d35c71ca84f78a4e9c766de6a2614bd1
+  metadata.gz: 3ac0ee4402ad94a39aa256fdcefaa24333f89333de1ee216b7ca698e493fb2410d771115c8a7e694d7acec8228bb5301db8ba6643e1e277bf87aa2aaf132b65d
+  data.tar.gz: 41e8ff87efe32f54185a96fc7e9781c02304a9a24b3090bb50bd5f8532488ab581c08ccbf2be47d469d18d63fed9fda2cf74776bf066dc8aac48aca982bb90e7

data/README.md

@@ -12,7 +12,7 @@
 
 
 
-> **Status:** Minting 2.1 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]
@@ -57,25 +57,10 @@ shares = total.allocate([1, 2, 3]) # => [16.67, 33.33, 50.00]
 parts = total.split(3) # => [33.34, 33.33, 33.33]
 ```
 
-## What's New in 2.1
-
-### Breaking Changes
-- Rounding mode symbols renamed to match `Rational#round` `half:` parameter: `:half_up` → `:up`, `:half_down` → `:down`, `:half_even` → `:even`
-
-## What's New in 2.0
-
-### Breaking Changes
-- `Mint.parse` and `Mint.parse!` removed — use `Money.parse` and `Money.parse!`
-- `Mint.with_rounding` removed — use `Money.with_rounding`
-- `Mint.world_currencies` removed — use `Currency.world_currencies`
-- `Money#mint` removed — use `Money#copy_with`
-- `Money::Currency` is the canonical name to access the `Currency` class
-- `minting/mint/aliases` abbreviated to `minting/aliases`
-- `Money#format` `formatter_class:` kwarg removed — `Formatter` is now the sole formatter implementation
-- `Money#to_json` and `Money.from_json` — moved to `attribute-money` companion gem
+## What's new since 2.0
 
 ### New Features
-- **Crypto currency support**: Opt-in YAML-backed definitions for ~25 popular coins (BTC, ETH, SOL, ...). Use `Currency.register_crypto('BTC', 'ETH')` to register, or `Currency.crypto_currencies` to inspect available definitions.
+- **Crypto currency support**: Opt-in YAML-backed definitions for ~25 popular coins (BTC, ETH, SOL, ...). Use `Money::Currency.register_crypto('BTC', 'ETH')` to register, or `Money::Currency.crypto_currencies` to inspect available definitions.
 - `Currency.registered_currencies` — public access to all registered currencies (frozen hash)
 - `Money.from_hash(hash)` — deserializer symmetric with `to_hash`, accepts `{ currency:, amount: }`
 - `Money#integral` — returns the whole-unit part of the amount (complement to `#fractional`). `#to_i` is now an alias of `#integral`.
@@ -88,6 +73,17 @@ parts = total.split(3) # => [33.34, 33.33, 33.33]
 - `Money#fractional` now returns a signed value matching the amount's sign (previously always positive for negative amounts). The invariant `integral * multiplier + fractional == subunits` now holds for all amounts.
 - `Money#initialize` now calls `.to_r` on the amount, guaranteeing `@amount` is always a `Rational`. Fixes a hash/`eql?` contract violation for zero-subunit currencies and an `ArgumentError` in `Integer#to_d`.
 
+### Breaking Changes
+- `Money#clamp` no longer accepts `Numeric` bounds — only `Money` or `nil`. Previously `price.clamp(0, 100)` was silently accepted; now it raises `ArgumentError`. Use `price.clamp(0.dollars, 100.dollars)` instead. This prevents accidental misuse where a bare number is passed as a variable.
+- Rounding mode symbols renamed to match `Rational#round` `half:` parameter: `:half_up` → `:up`, `:half_down` → `:down`, `:half_even` → `:even`
+- `Mint.parse` and `Mint.parse!` removed — use `Money.parse` and `Money.parse!`
+- `Mint.with_rounding` removed — use `Money.with_rounding`
+- `Mint.world_currencies` removed — use `Currency.world_currencies`
+- `Money#mint` removed — use `Money#copy_with`
+- `Money::Currency` is the canonical name to access the `Currency` class
+- `Money#format` `formatter_class:` kwarg removed — `Formatter` is now the sole formatter implementation
+- `Money#to_json` and `Money.from_json` — moved to `attribute-money` companion gem
+
 ### Removed
 - `Money::Formatter2` — removed; `Formatter` is the sole implementation
 - `Money#to_json` and `Money.from_json` — moved to `attribute-money` companion gem
@@ -98,8 +94,7 @@ Amounts are stored as `Rational`, so there's no floating-point drift — `0.1 +
 
 - [Quickstart](#quickstart)
 - [Why Minting](#why-minting)
-- [What's New in 2.1](#whats-new-in-21)
-- [What's New in 2.0](#whats-new-in-20)
+- [What's new since 2.0](#whats-new-since-20)
 - [How it compares](#how-it-compares)
 - [Installation](#installation)
 - [Usage](#usage)
@@ -124,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.
@@ -156,6 +151,14 @@ gem 'minting'
 
 ### Creating & comparing money
 
+`Money.from` is the canonical constructor. The older `Mint.money` factory and
+`Numeric#mint` shortcut are deprecated; use `Money.from` and `Numeric#to_money`
+instead. Named shortcuts such as `dollars`, `euros`, and `reais` remain
+available.
+
+Currency arguments accept currency code strings or `Currency` objects. Symbols
+such as `:USD` are not supported.
+
 ```ruby
 require 'minting'
 
@@ -187,9 +190,10 @@ Money.from(10, 'USD') == 10                    #=> false
 price = Money.from(50, 'USD')
 min_price = Money.from(75, 'USD')
 
-price.clamp(0, 100)          #=> [USD 50.00]  (returns self, no new object)
-price.clamp(0, 25)           #=> [USD 25.00]  (clamped to max)
-price.clamp(min_price, 100)  #=> [USD 75.00]  (clamped to min, Money or Numeric bounds both work)
+price.clamp(price, Money.from(100, 'USD'))  #=> [USD 50.00]  (returns self, no new object)
+price.clamp(0.dollars, 25.dollars)           #=> [USD 25.00]  (clamped to max)
+price.clamp(min_price, 100.dollars)          #=> [USD 75.00]  (clamped to min)
+
 ```
 
 ### Formatting
@@ -203,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')
@@ -216,8 +221,11 @@ 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')
 loss.format( { negative: '(%<symbol>s%<amount>f)' })  #=> "($1,234.56)"
 Money.from(0, 'BRL').format( { zero: '--' })          #=> "--"
 fmt = { positive: '%<symbol>s%<amount>f', negative: '(%<symbol>s%<amount>f)', zero: '--' }
@@ -264,8 +272,24 @@ Money.parse('USD 1,234.56')     #=> [USD 1234.56]
 
 Notes:
 - Pass a currency code when the string has no symbol or code.
+- 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
+  with three decimal places, a single comma followed by three digits is read
+  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]`.
@@ -273,12 +297,12 @@ Notes:
 ### Currency lookup
 
 ```ruby
-# All registered currencies (150+ ISO 4217 + custom)
+# All registered currencies (currently 164 built-in ISO 4217 + custom)
 Money::Currency.registered_currencies.size                 #=> 164
 Money::Currency.registered_currencies.each { |code, c| puts "#{code}: #{c.name}" }
 
 # Built-in ISO 4217 currencies (before custom registrations)
-Money::Currency.world_currencies.size    #=> 154
+Money::Currency.world_currencies.size    #=> 164
 
 # By ISO code (direct hash lookup, string only)
 Money::Currency.for_code('USD')        #=> #<Currency code="USD" ...>
@@ -307,16 +331,16 @@ Money::Currency.resolve!(Product.new) # raises Mint::UnknownCurrency if code is
 Minting ships with opt-in definitions for ~25 popular crypto currencies (BTC, ETH, SOL, ...). They are not registered by default — use `register_crypto` to enable them:
 
 ```ruby
-Currency.register_crypto('BTC', 'ETH', 'SOL')
+Money::Currency.register_crypto('BTC', 'ETH', 'SOL')
 
 Money.parse("0.01 BTC")    #=> [BTC 0.01000000]
-Mint.money(1, 'ETH')      #=> [ETH 1.000000000000000000]
+Money.from(1, 'ETH')      #=> [ETH 1.000000000000000000]
 ```
 
-`Currency.crypto_currencies` lists all available definitions without registering:
+`Money::Currency.crypto_currencies` lists all available definitions without registering:
 
 ```ruby
-Currency.crypto_currencies.each { |c| puts "#{c.code}: #{c.name}" }
+Money::Currency.crypto_currencies.each { |c| puts "#{c.code}: #{c.name}" }
 # BTC: Bitcoin
 # ETH: Ethereum
 # SOL: Solana
@@ -346,11 +370,11 @@ LOCALE_DATA = {
 
 Mint.locale_backend = ->(locale) { LOCALE_DATA[locale.to_s] || {} }
 
-Mint.money(1234.56, 'USD').format(locale: :en)  #=> "$1,234.56"
-Mint.money(9.99, 'BRL').format(locale: 'pt')    #=> "R$9,99"
-Mint.money(9.99, 'EUR').format(locale: :de)     #=> "9,99 EUR"
-Mint.money(9.99, 'EUR').format(locale: 'fr')    #=> "9,99 €"
-Mint.money(9.99, 'USD').format(locale: :ja)     #=> "$9.99"
+Money.from(1234.56, 'USD').format(locale: :en)  #=> "$1,234.56"
+Money.from(9.99, 'BRL').format(locale: 'pt')    #=> "R$9,99"
+Money.from(9.99, 'EUR').format(locale: :de)     #=> "9,99 EUR"
+Money.from(9.99, 'EUR').format(locale: 'fr')    #=> "9,99 €"
+Money.from(9.99, 'USD').format(locale: :ja)     #=> "$9.99"
 ```
 
 Pass `locale:` as a keyword to `format` / `to_fs`. Accepts both symbols (`:en`, `:'pt-BR'`) and strings (`'pt-BR'`, `'en-US'`) — passed through as-is, matching Rails' `I18n.locale` convention. The backend returns a hash with `:decimal`, `:thousand`, and optionally `:format` (defaults to `'%<symbol>s%<amount>f'`). String and symbol keys are interchangeable. Return `{}` or `nil` for unknown locales — defaults apply.
@@ -371,13 +395,25 @@ Arity-0 callables (`-> { ... }`) are called without arguments and work unchanged
 
 ```ruby
 Mint.locale_backend = -> { { decimal: ',', thousand: '.' } }
-Mint.money(9.99, 'BRL').format  #=> "R$9,99"
+Money.from(9.99, 'BRL').format  #=> "R$9,99"
 ```
 
 ## API notes
 
 **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
@@ -386,21 +422,87 @@ Money.with_rounding(:even) { Money.from(1.015, 'USD') }   #=> [USD 1.02]
 Money.with_rounding(:up)   { Money.from(1.005, 'USD') }   #=> [USD 1.01]
 ```
 
-Modes: `:up` (default), `:down`, `:even`. Applies to construction, parsing, `change`, `split`, and `allocate`. Restores the previous mode when the block exits, even on exception.
+Modes: `:up` (default), `:down`, `:even`. Applies to construction, parsing,
+`copy_with`, `split`, and `allocate`. Restores the previous mode when the block
+exits, even on exception.
 
 > **Performance note:** Rounding-mode support is not loaded by default — `require 'minting'` uses the fastest possible rounding (equivalent to `:up`) with zero dispatch overhead. The first call to `Money.with_rounding` activates the rounding dispatch in `Currency#normalize_amount`, adding ~10–35 ns per money creation or mutation. If your application never uses custom rounding modes, there is **no performance cost**.
 
-**Division** — `money / 5` returns new `Money`; `money / other_money` returns a numeric ratio, not money.
+### Common API workflows
+
+**Parsing failures** — `Money.parse` returns `nil` for invalid input or an
+unresolved currency. `Money.parse!` raises `ArgumentError` instead:
+
+```ruby
+Money.parse('bad', 'USD')       #=> nil
+Money.parse!('bad', 'USD')      #=> raises ArgumentError
+```
+
+The optional currency argument is a default. Embedded currency information wins:
+
+```ruby
+Money.parse('10', 'USD')        #=> [USD 10.00]
+Money.parse('10 EUR', 'USD')    #=> [EUR 10.00]
+```
+
+**Arithmetic and division** — Money can be added or subtracted only with the
+same currency. Multiplication and scalar division return Money; dividing by
+same-currency Money returns a numeric ratio. Non-zero cross-currency operations
+and reverse numeric division raise `TypeError`.
+
+```ruby
+price = Money.from(10, 'USD')
+price + Money.from(2, 'USD')   #=> [USD 12.00]
+price * 1.5                    #=> [USD 15.00]
+price / 2                      #=> [USD 5.00]
+price / Money.from(5, 'USD')   #=> (2/1)
+```
+
+**Clamping** — Bounds must be Money objects in the same currency or `nil`.
+An inclusive Range can be passed as the only argument:
+
+```ruby
+price.clamp(Money.from(0, 'USD'), Money.from(8, 'USD')) #=> [USD 8.00]
+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 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. 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')
+money.to_r                         #=> (999/100)
+money.to_f                         #=> 9.99
+Money.from_hash(money.to_hash)     #=> [USD 9.99]
+```
+
+**Money ranges** — Money ranges use `succ` and a Money step. Ruby 4.0 supports
+non-numeric steps natively; Minting patches `Range#step` for Money only on
+older supported Rubies.
 
 **Zero equality** — Any zero amount is considered equal across currencies and to numeric zero (`Money.from(0, 'USD') == Money.from(0, 'EUR')` is intentionally `true`). Non-zero amounts must match currency and value.
 
 
 
-**Registered currencies** — `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.
 
-## Optional top-level `Money` (opt-out) and `Currency` (opt-in)
+## Top-level aliases
 
 By default, `require "minting"` exposes `Mint::Money` as the top-level `Money` constant, so you can write `Money.from(10, "USD")` directly:
 ```ruby

data/Rakefile

@@ -13,12 +13,7 @@ Rake::TestTask.new(:test) do |t|
   t.ruby_opts << '-rtest_helper.rb'
 end
 
-Rake::TestTask.new('bench:all') do |t|
-  t.libs = %w[lib bench]
-  t.pattern = 'bench/{core,memory,regression}/*_benchmark.rb'
-end
-
-Rake::TestTask.new('bench:core') do |t|
+Rake::TestTask.new('bench:parse') do |t|
   t.libs = %w[lib bench]
   t.pattern = 'bench/core/parse_benchmark.rb'
 end
@@ -49,7 +44,7 @@ desc 'Run core benchmarks and update the baseline'
 task 'bench:baseline' do
   platform = RUBY_PLATFORM
   baseline = "bench/check/results/baseline-#{platform}.json"
-  sh "bundle exec ruby bench/check/runner.rb #{baseline}"
+  ruby "bench/check/runner.rb #{baseline}"
   puts "Baseline updated for #{platform}."
 end