minting 1.7.2 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 849f4b46ee6f731be672f7e6adb274174233294d7be293c8c875eaa0ace5b744
-  data.tar.gz: b3f3a822c55e7fd9fdddcfcf7be59069b66ea441d73ab61e2e202563173a8675
+  metadata.gz: a027eb400724db0164db62cc9d76ce371b73a538d4b5713f85a917b31c43330a
+  data.tar.gz: cf7bb6b476300f02f39992dab1e7ecbff9e7d14974dbf8c33fc89dd1c093e20e
 SHA512:
-  metadata.gz: 5f4d42d03f31c941fcd591e27c463341be2c31498c7d854c3b98f85445a8ca55dfa692c3124f187000c83b97b0abc21e6e7276ea5bb3cd1090e82619e6fcc451
-  data.tar.gz: '0854273f42d05dee2b2d91830110d9f59074821abd81c76a14860a0969c4bd2cd48c56164c5fd2b65fcdfe32f537860958b108cd53eadfc53a2c33215f35c5cd'
+  metadata.gz: 9274bdfeb0ffdb3a8e22366a71d02265008bdabcf18abdbc68ec70c4e92768e1c9fdbb58bd243c2f3ad8e3094f3e5cfc45e876756a9a93720a428cc0a42210a1
+  data.tar.gz: d0647ee4aa7e9f28dc5cc6d7698639830edabff5b4a0b14c108f55f4bd6a8004e603dccfdcb934c5d404a670f4baf7e2269440643a586bab1c6e2dc71314b7b7

data/README.md

@@ -172,17 +172,42 @@ Notes:
 - 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: `Mint.parse("MAX 10.00 USD")` yields `[USD 10.00]`.
 
+## Currency lookup
+
+```ruby
+# By ISO code (direct hash lookup, string only)
+Mint::Currency.for_code('USD')        #=> #<Currency code="USD" ...>
+
+# By display symbol (highest-priority currency for ambiguous symbols)
+Mint::Currency.for_symbol('$')        #=> #<Currency code="USD" ...>
+Mint::Currency.for_symbol('R$')       #=> #<Currency code="BRL" ...>
+Mint::Currency.for_symbol('€')        #=> #<Currency code="EUR" ...>
+
+```
+
 ## API notes
 
 **Exact amounts** — Amounts are stored as `Rational` and rounded to the currency subunit.
 
+**Rounding modes** — Wrap operations in `Mint.with_rounding(mode)` to change how amounts are rounded to the subunit:
+
+```ruby
+Mint.with_rounding(:half_down) { Mint.money(1.005, 'USD') }  #=> [USD 1.00]
+Mint.with_rounding(:ceil)      { Mint.money(1.001, 'USD') }  #=> [USD 1.01]
+Mint.with_rounding(:floor)     { Mint.parse('1.009', 'USD') } #=> [USD 1.00]
+```
+
+Modes: `:half_up` (default), `:half_down`, `:floor`, `:ceil`, `:truncate`, `:down`. Applies to construction, parsing, `change`, `split`, and `allocate`. Restores the previous mode when the block exits, even on exception.
+
 **Refinements** — `10.dollars` and similar helpers require `using Mint` in the current scope (see Usage above).
 
 **Division** — `money / 5` returns new `Money`; `money / other_money` returns a numeric ratio, not money.
 
 **Zero equality** — Any zero amount is considered equal across currencies and to numeric zero (`Mint.money(0, 'USD') == Mint.money(0, 'EUR')` is intentionally `true`). Non-zero amounts must match currency and value.
 
-**Registered currencies** — `Mint.register_currency`. Only registered currency codes and symbols are recognized by the parser.
+**Zero helper** — `Currency.zero('USD')` returns a frozen zero-Money, useful as a default value for discounts, totals, or counters.
+
+**Registered currencies** — `Currency.register(code:, subunit:, symbol:, priority:)` adds custom currencies. Only registered codes and symbols are recognized by the parser.
 
 **Built-in currencies** — 150+ ISO-4217 world currencies ship in `lib/minting/data/currencies.yaml` and load when the registry is first accessed.
 
@@ -201,11 +226,18 @@ Or at runtime:
 Minting.use_top_level_constants!
 ```
 
+For Rails applications, you can enable the top-level constants in an initializer:
+
+```ruby
+# config/initializers/minting.rb
+require "minting/dsl"
+```
+
 After opting in:
 
 ```ruby
-price = Money.create(10, "USD")     # equivalent to Mint::Money.create
-tax   = Money.money(2.50, "USD")
+price = Money.from(10, "USD")                   # equivalent to Mint::Money.from
+tax   = Money.from(2.50, "USD")
 cur   = Currency.new(code: "EUR", symbol: "€", subunit: 2, priority: 0)
 ```