minting 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 851c39a123584b8a782ef0c610c5e271239e0f20b948963bf926daf11defa269
-  data.tar.gz: 9d9c5aab7a6acc499308b2850157f6e8d4eef8ad01f4b0db4aa75e89067162fb
+  metadata.gz: 4599b829514f80d36867c1ddd7afa3a00a6ea1a718883ce46ea250fc58f4deff
+  data.tar.gz: cabdea47ab90088ae53582ccacdf9695a6153230aff0f2e986af00191d8eeb05
 SHA512:
-  metadata.gz: d6cca508a6ec6690436d67f70720db03bcebabeb7b561a4769aca306d9350f1d40ba07af63500316c236094dca13b7a6c181d49b324729e7439deff05f69513a
-  data.tar.gz: 419ce736af2fd00d90834dc6b82e5459ff83873922871a40d89d62dda69603ce31a5456918fa61ba21564489019eba6c80b1589cefce19841410a6e328ee45fa
+  metadata.gz: a1bf6f69bb7513c6ec7b3a0b1e3838e0a87add33c57b82b652d8c4e8951539abfccdbd0cf3fa42220a9dc0efce6b64afb426aebd63c2c4ae3e10614d5245e4c5
+  data.tar.gz: 5e896ab547e87ed89c6d2e30252840b43bf5a4808ba49f82ce2b9dcb55a7d9ccaffe75d0f7ec6c228d7d1bad3c93b9bde3112553704a6d1d4e1dd43f636450ed

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.2 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)
@@ -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
@@ -218,6 +222,7 @@ Money.from(0.99, 'USD').format('%<integral>d dollars and %<fractional>02d cents'
 #=> "0 dollars and 99 cents"
 
 # 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 +269,14 @@ 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).
 - `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.
 - 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 +284,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 +318,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 +357,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,7 +382,7 @@ 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
@@ -386,21 +397,85 @@ 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, 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]]
+```
+
+**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:
+
+```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:)` 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.
 
 **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