minting 1.7.2 → 1.8.0

data/doc/Minting.html

@@ -116,7 +116,7 @@
 
 </div>
         </dt>
-        <dd><pre class="code"><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>1.7.1</span><span class='tstring_end'>&#39;</span></span></pre></dd>
+        <dd><pre class="code"><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>1.7.3</span><span class='tstring_end'>&#39;</span></span></pre></dd>
       
     </dl>
   
@@ -132,7 +132,7 @@
 </div>
 
       <div id="footer">
-  Generated on Sun Jun 14 21:57:01 2026 by
+  Generated on Tue Jun 16 20:22:19 2026 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.44 (ruby-4.0.5).
 </div>

data/doc/_index.html

@@ -89,13 +89,6 @@
                 
               </li>
             
-              <li>
-                <span class='object_link'><a href="Mint/CurrencyRegistry.html" title="Mint::CurrencyRegistry (module)">CurrencyRegistry</a></span>
-                
-                  <small>(Mint)</small>
-                
-              </li>
-            
           </ul>
         </ul>
       
@@ -136,6 +129,20 @@
                 
               </li>
             
+              <li>
+                <span class='object_link'><a href="Mint/Registry.html" title="Mint::Registry (module)">Registry</a></span>
+                
+                  <small>(Mint)</small>
+                
+              </li>
+            
+              <li>
+                <span class='object_link'><a href="Mint/Rounding.html" title="Mint::Rounding (module)">Rounding</a></span>
+                
+                  <small>(Mint)</small>
+                
+              </li>
+            
           </ul>
         </ul>
       
@@ -163,7 +170,7 @@
 </div>
 
       <div id="footer">
-  Generated on Sun Jun 14 21:57:00 2026 by
+  Generated on Tue Jun 16 20:22:19 2026 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.44 (ruby-4.0.5).
 </div>

data/doc/agents/api_review-2026-06-15.md

@@ -0,0 +1,329 @@
+# Minting gem API review
+
+**Data:** 2026-06-15
+**Author:** Wave AI (via Wave Terminal assistant)
+
+## 1. Top-level API surface (Mint / Money / Currency)
+
+### What’s good
+
+- `Mint.money(10, 'USD')` is clear and discoverable.
+- Refinements (`10.dollars`, `4.to_money('USD')`) are modern and opt-in.
+- Optional `minting/dsl` with `Money` / `Currency` constants is a good compromise for ergonomics vs. gem conflicts.
+
+### Suggestions
+
+1. **Tighten constructor story (too many verbs)**  
+   Right now you have:
+   - `Mint.money(amount, code)`
+   - `Mint.zero(currency)`
+   - `Mint::Money.create(amount, currency)`
+   - `Mint::Money.from_fractional(fractional, currency)`
+   - `Money.create` / `Money.from_fractional` / `price.mint(new_amount)` (instance)
+
+   Consider a simpler, more opinionated set:
+
+   - **Class side:**
+     - `Money.from(amount, currency)` (instead of `create`)
+     - `Money.from_fractional(fractional, currency)`
+   - **Module side:**
+     - `Mint.money(amount, currency)` (delegates to `Money.from`)
+     - `Mint.from_fractional(fractional, currency)` (delegates to `Money.from_fractional`)
+     - `Mint.zero(currency)`
+
+   And **remove / de-emphasize** `Money.create` from public docs (keep as private alias if needed).
+
+2. **Rename `mint(new_amount)` → clearer “copy with” semantics**
+
+   `price.mint(15.00)` is cute but not self-describing. Consider:
+
+   - `price.with_amount(15.00)`
+   - or `price.change(amount: 15.00)`
+   - or `price.rebuild(15.00)` (less good, but at least indicates a copy)
+
+   And surface this in README (“Immutability helpers”).
+
+3. **Top-level constants: make the opt-in path prominent, but one-liner**
+
+   You already have:
+
+   ```ruby
+   require "minting"
+   require "minting/dsl"  # opt-in top‑level Money / Currency
+   ```
+
+   For Rails developers, you might recommend in README:
+
+   ```ruby
+   # config/initializers/minting.rb
+   require "minting/dsl"
+   ```
+
+   And add a short “Rails setup” snippet, since that’s what competing gems usually highlight first.
+
+---
+
+## 2. Money semantics & naming
+
+### Zero equality semantics
+
+You do something non-standard and powerful:
+
+```ruby
+Mint.money(0, 'USD') == Mint.money(0, 'EUR') # => true
+Mint.money(0, 'USD') == 0                    # => true
+```
+
+This is very nice for totals, but surprising vs. `money` gem.
+
+**Changes:**
+
+1. **Make this a named feature, with an escape hatch**
+
+   - Give it a name in docs: e.g. “currency-agnostic zero”.
+   - Provide an **explicit predicate or helper**:
+
+     ```ruby
+     price.zero?     # usual predicate
+     price.strictly_zero_in?('USD') # same_currency? + zero?
+     ```
+
+   - Consider a **config flag** or alternate comparator:
+
+     ```ruby
+     Mint.strict_zero_comparison = true
+     # or
+     price.eql_in_currency?(other_price)
+     ```
+
+2. **Docs: add a clear “Gotchas” section**  
+   Call out at the bottom of README “Behavior that differs from `money` gem”, starting with zero. This directly addresses “gap to competitors” and reduces surprises.
+
+### `same_currency?`
+
+Current doc:
+
+```ruby
+# @param other [Currency] the target currency to compare
+def same_currency?(other) = other.currency == currency
+```
+
+This is odd: the param type is a `Currency` in the docs, but you call `other.currency` which implies it’s actually `Money`.
+
+**Change:**
+
+- Decide on the intent; then:
+  - If it compares two `Money` objects, define:
+
+    ```ruby
+    # @param other [Money]
+    def same_currency?(other) = other.currency == currency
+    ```
+
+  - Or if you want both forms, accept either and update docs:
+
+    ```ruby
+    def same_currency?(other)
+      other_currency =
+        case other
+        when Mint::Money   then other.currency
+        when Mint::Currency then other
+        else
+          Currency.resolve!(other)
+        end
+
+      other_currency == currency
+    end
+    ```
+
+- Consider renaming to `same_currency_as?(other)` to better match Ruby predicate idioms and feel less “type-ish”.
+
+---
+
+## 3. Parsing API
+
+### Suggestions
+
+1. **Return type & error modes**
+
+   - Document explicitly that `Mint.parse` returns `Mint::Money`.
+   - Add **two modes**:
+     - `Mint.parse!(...)` – raises on failure.
+     - `Mint.parse(...)` – returns `nil` on failure or perhaps `Result` object in future, but nil is sufficient initially.
+
+3. **Quality-of-life alias**
+
+   - `Mint.money_from(str, currency_code = nil)`
+   - Or a class method: `Mint::Money.parse(str, currency: nil)`
+
+   That keeps “all money stuff under Money” for folks who avoid module functions.
+
+---
+
+## 4. Formatting API
+
+Current:
+
+- `to_s(format: '%<symbol>s%<amount>f')`
+- Hash format for per-sign: `{ negative: '(%<symbol>s%<amount>f)' }`
+
+This is powerful but low-level. Competing gems typically offer higher-level presets and localization.
+
+### Suggestions
+
+1. **Named formats / shortcuts**
+
+   Something like:
+
+   ```ruby
+   price.format          # same as to_s
+   price.format(:iso)    # "USD 9.99"
+   price.format(:symbol) # "$9.99"
+   price.format(:code)   # "9.99 USD"
+   ```
+
+   Internally, use a format registry:
+
+   ```ruby
+   Mint.formats.register(:iso, '%<currency>s %<amount>f')
+   ```
+
+2. **Accounting format shortcut**
+
+   You already support per-sign hash formats; expose a named helper:
+
+   ```ruby
+   price.to_accounting   # ($1,234.56) for negatives, 0.00 for zero
+   ```
+
+3. **JSON / Rails integration**
+
+   You have:
+
+   ```ruby
+   price.to_json  # => {"currency":"USD","amount":"9.99"}
+   price.to_hash  # => { currency: "USD", amount: "9.99" }
+   ```
+
+   For better Rails DX & parity:
+
+   - Add `as_json` delegating to `to_hash`.
+   - Mention in README: “Works with Rails serialization (`as_json` implemented).”
+
+---
+
+## 5. Currency API
+
+Current:
+
+- `Mint.currency_for_code('USD')`
+- `Mint.currency_for_symbol('$')`
+- `Mint.register_currency(...)`
+- `Mint.world_currencies` (+ internal `Registry`)
+
+### Suggestions
+
+1. **Consistent names & variants**
+
+   Consider:
+
+   - `Mint.currency('USD')` → primary lookup (by code; maybe symbol in future).
+   - Keep `currency_for_code` / `currency_for_symbol` as explicit variants, but guide people to the simple `currency`.
+
+2. **Clarify custom currency lifecycle**
+
+   Competitors often have quirks here; you can win on clarity:
+
+   - Are custom currencies persisted per process?
+   - Are they thread-safe?
+   - Are they ordered by `priority` in deterministic way?
+
+   Add a small “Custom currencies” section with examples and guarantees.
+
+3. **Expose the registry read-only**
+
+   Instead of `world_currencies` returning “the frozen world-currencies hash” (but you also have `Registry.currencies`), maybe have:
+
+   ```ruby
+   Mint.currencies # => { "USD" => <Currency>, ... } (frozen hash)
+   ```
+
+   And keep `Registry` private in docs.
+
+---
+
+## 6. Error types & clarity
+
+### UnknownCurrency
+
+```ruby
+# Unknown currency excpetion
+class UnknownCurrency < StandardError; end
+```
+
+- Typo in comment (“excpetion”).
+- Recommend renaming to `UnknownCurrencyError` for conventional Ruby style.
+- Ensure it’s actually raised from `Currency.resolve!` (and document that).
+
+### Validation errors
+
+You currently raise `ArgumentError` for several things (`amount must be Numeric`, `fractional must be an Integer`).
+
+Consider:
+
+- Keeping `ArgumentError` but **documenting all the failure cases** in YARD and README.
+- Or, for one level up in clarity, introduce:
+
+  ```ruby
+  class InvalidMoneyArgument < ArgumentError; end
+  ```
+
+  and use that everywhere. This is a small DX win in large apps.
+
+---
+
+## 7. Documentation structure (DX & competitiveness)
+
+Your README is already strong. To push it over the top vs. `money` gem and friends:
+
+1. **Add a “Comparison” section**
+
+   Not necessarily with names, but structurally:
+
+   - “What Minting does differently”
+     - Always-exact `Rational` amounts.
+     - Currency-agnostic zero.
+     - Faster formatting (link benchmarks).
+     - Separate `minting-rails` companion for clean Rails integration.
+
+2. **Add “Common tasks” cheatsheet**
+
+   Short, scannable table:
+
+   | Task                          | Code                              |
+   |------------------------------|-----------------------------------|
+   | New amount                   | `Mint.money(10, 'USD')`          |
+   | From cents                   | `Mint::Money.from_fractional(999, 'USD')` |
+   | Change amount immutably      | `price.with_amount(15)` (or `mint`) |
+   | Parse user input             | `Mint.parse('$19.99')`           |
+   | Serialize to JSON            | `price.to_hash` / `price.as_json` |
+   | Clamp to range               | `price.clamp(0, 100)`            |
+   | Split / allocate             | `ten.split(3)` / `ten.allocate([...])` |
+
+   This directly optimizes developer experience.
+
+3. **Prominent “Rails” heading**
+
+   Right now you just mention `minting-rails`. Make it a full section:
+
+   - How to add gem.
+   - Example migration / attribute definition (even if in the other repo, mirror one snippet here).
+
+---
+
+## 8. Minor polish
+
+- In `README` “Json serialization” → “JSON serialization”.
+- Make sure `Mint::Money`’s `inspect` and `to_s` are clearly differentiated in docs:
+  - `inspect` → developer/debugging (`[USD 10.00]`).
+  - `to_s` → user-facing, configurable formatting.

data/doc/agents/copilot-instructions.md

@@ -21,10 +21,6 @@ Build, test and lint commands
 - Run a single test method by name (Minitest -n regexp):
   - ruby -Ilib:test -r ./test/test_helper.rb test/money/money_test.rb -n /test_creation/
 
-- Performance suites:
-  - rake bench:performance
-  - rake bench:competitive
-  - rake bench:regression
 
 - Linting:
   - bundle exec rake cop
@@ -56,7 +52,6 @@ Key conventions and repo-specific rules
 - Currency registration: use Mint.register_currency for idempotent registration; Mint.register_currency! raises on duplicates. Codes must match /^[A-Z_]+$/.
 - Symbol parsing: parser resolves symbols by longest match then currency priority (see Mint.currency_symbols sorting).
 - Tests: test_helper.rb configures coverage (SimpleCov) and loads minitest; when running tests outside rake, require test_helper (-r ./test/test_helper.rb).
-- Benchmarks: set to enable benchmark-heavy tasks; benchmarks use Minitest::Benchmark patterns.
 - Formatting: Money.to_s uses Kernel.format patterns; take care with %<amount>f vs %<amount>d depending on desired rounding/formatting.
 
 Files and places to check first during edits

data/doc/agents/expired/copilot-instructions.md

@@ -0,0 +1,75 @@
+Repository overview
+
+- Language: Ruby gem (minting)
+- Location of main code: lib/minting and its subfolders (mint/, money/)
+- Public API surface: Mint (factory/helpers), Mint::Money, Mint::Currency
+- Data: built-in currencies in lib/minting/data/currencies.yaml
+- Tests: Minitest (unit) + performance benchmarks under test/performance
+
+Build, test and lint commands
+
+- Install dependencies:
+  - bundle install
+
+- Run full test suite (default task):
+  - bundle exec rake
+  - or simply: rake
+
+- Run a single test file (recommended when iterating):
+  - ruby -Ilib:test -r ./test/test_helper.rb test/money/money_test.rb
+
+- Run a single test method by name (Minitest -n regexp):
+  - ruby -Ilib:test -r ./test/test_helper.rb test/money/money_test.rb -n /test_creation/
+
+- Performance suites:
+  - rake bench:performance
+  - rake bench:competitive
+  - rake bench:regression
+
+- Linting:
+  - bundle exec rake cop
+  - or: bundle exec rubocop
+
+- Build gem package:
+  - gem build minting.gemspec
+
+- Documentation:
+  - bundle exec rake yard
+
+- README verification:
+  - README examples are exercised by `test/minting_test.rb#test_readme_usage`.
+  - Prefer the README as the authoritative usage guide for feature behavior and examples.
+
+High-level architecture (big picture)
+
+- Top-level: lib/minting.rb requires the Mint module and Money implementation.
+- Mint module: currency registry and factory helpers live in lib/minting/mint/*. Registry loads lib/minting/data/currencies.yaml on first access.
+- Currency: lightweight value object (code, subunit, symbol, priority, minimum_amount).
+- Money: immutable value object stored as Rational and rounded to currency.subunit. Core concerns split across lib/minting/money/* (arithmetics, formatting, conversion, coercion, allocation, parsing, comparable).
+- Refinements: Numeric/String/Refinements in lib/minting/mint/refinements.rb expose helpers like 10.dollars, 4.to_money('USD'), and require `using Mint` in scope.
+- Performance tests: separate bench tasks under Rake; test/performance holds benchmark suites.
+
+Key conventions and repo-specific rules
+
+- Exactness: amounts are stored as Rational and rounded to the currency subunit. Prefer rationals or decimal strings (e.g., '19.99'.to_r or 1999/100r) when precision is needed.
+- Zero equality: zeros are equal across currencies (Mint.money(0,'USD') == Mint.money(0,'EUR') == 0). Non-zero comparisons require identical currency and amount.
+- Currency registration: use Mint.register_currency for idempotent registration; Mint.register_currency! raises on duplicates. Codes must match /^[A-Z_]+$/.
+- Symbol parsing: parser resolves symbols by longest match then currency priority (see Mint.currency_symbols sorting).
+- Tests: test_helper.rb configures coverage (SimpleCov) and loads minitest; when running tests outside rake, require test_helper (-r ./test/test_helper.rb).
+- Benchmarks: set to enable benchmark-heavy tasks; benchmarks use Minitest::Benchmark patterns.
+- Formatting: Money.to_s uses Kernel.format patterns; take care with %<amount>f vs %<amount>d depending on desired rounding/formatting.
+
+Files and places to check first during edits
+
+- lib/minting/money - core behavior and arithmetic
+- lib/minting/mint - currency registry, refinements, and factory API
+- lib/minting/data/currencies.yaml - canonical currency definitions
+- test/ - unit tests; test/performance - benchmark suites
+
+Notes for Copilot sessions
+
+- Prefer making atomic changes and run the unit test(s) covering the changed area. Use the single-file test invocation above when iterating rapidly.
+- When changing numeric/rounding behavior, run both unit tests and relevant performance benchmarks.
+- Respect zero-equality semantics and currency code validation when modifying equality/hash logic.
+
+If you want, update this file with project-specific conventions to capture workflow choices (e.g., backport policy, DI patterns).

data/doc/class_list.html

@@ -46,7 +46,7 @@
 
       <ul id="full_list" class="class">
         <li id="object_" class="odd"><div class="item" style="padding-left:30px"><span class='object_link'><a href="top-level-namespace.html" title="Top Level Namespace (root)">Top Level Namespace</a></span></div></li>
-<li id='object_Mint' class='even'><div class='item' style='padding-left:30px'><a tabindex='0' class='toggle' role='button' aria-label='Mint child nodes' aria-expanded='false' aria-controls='object_Mint'></a> <span class='object_link'><a href="Mint.html" title="Mint (module)">Mint</a></span><small class='search_info'>Top Level Namespace</small></div><div aria-labelledby='object_Mint'><ul><li id='object_Mint::Currency' class='collapsed odd'><div class='item' style='padding-left:45px'><span class='object_link'><a href="Mint/Currency.html" title="Mint::Currency (class)">Currency</a></span> &lt; Data<small class='search_info'>Mint</small></div></li><li id='object_Mint::CurrencyRegistry' class='collapsed even'><div class='item' style='padding-left:45px'><span class='object_link'><a href="Mint/CurrencyRegistry.html" title="Mint::CurrencyRegistry (module)">CurrencyRegistry</a></span><small class='search_info'>Mint</small></div></li><li id='object_Mint::Money' class='collapsed odd'><div class='item' style='padding-left:45px'><span class='object_link'><a href="Mint/Money.html" title="Mint::Money (class)">Money</a></span> &lt; Object<small class='search_info'>Mint</small></div></li><li id='object_Mint::RangeStepPatch' class='collapsed even'><div class='item' style='padding-left:45px'><span class='object_link'><a href="Mint/RangeStepPatch.html" title="Mint::RangeStepPatch (module)">RangeStepPatch</a></span><small class='search_info'>Mint</small></div></li><li id='object_Mint::UnknownCurrency' class='collapsed odd'><div class='item' style='padding-left:45px'><span class='object_link'><a href="Mint/UnknownCurrency.html" title="Mint::UnknownCurrency (class)">UnknownCurrency</a></span> &lt; StandardError<small class='search_info'>Mint</small></div></li></ul></div></li><li id='object_Minting' class='even'><div class='item' style='padding-left:30px'><span class='object_link'><a href="Minting.html" title="Minting (module)">Minting</a></span><small class='search_info'>Top Level Namespace</small></div></li>
+<li id='object_Mint' class='even'><div class='item' style='padding-left:30px'><a tabindex='0' class='toggle' role='button' aria-label='Mint child nodes' aria-expanded='false' aria-controls='object_Mint'></a> <span class='object_link'><a href="Mint.html" title="Mint (module)">Mint</a></span><small class='search_info'>Top Level Namespace</small></div><div aria-labelledby='object_Mint'><ul><li id='object_Mint::Currency' class='collapsed odd'><div class='item' style='padding-left:45px'><span class='object_link'><a href="Mint/Currency.html" title="Mint::Currency (class)">Currency</a></span> &lt; Data<small class='search_info'>Mint</small></div></li><li id='object_Mint::Money' class='collapsed even'><div class='item' style='padding-left:45px'><span class='object_link'><a href="Mint/Money.html" title="Mint::Money (class)">Money</a></span> &lt; Object<small class='search_info'>Mint</small></div></li><li id='object_Mint::RangeStepPatch' class='collapsed odd'><div class='item' style='padding-left:45px'><span class='object_link'><a href="Mint/RangeStepPatch.html" title="Mint::RangeStepPatch (module)">RangeStepPatch</a></span><small class='search_info'>Mint</small></div></li><li id='object_Mint::Registry' class='collapsed even'><div class='item' style='padding-left:45px'><span class='object_link'><a href="Mint/Registry.html" title="Mint::Registry (module)">Registry</a></span><small class='search_info'>Mint</small></div></li><li id='object_Mint::Rounding' class='collapsed odd'><div class='item' style='padding-left:45px'><span class='object_link'><a href="Mint/Rounding.html" title="Mint::Rounding (module)">Rounding</a></span><small class='search_info'>Mint</small></div></li><li id='object_Mint::UnknownCurrency' class='collapsed even'><div class='item' style='padding-left:45px'><span class='object_link'><a href="Mint/UnknownCurrency.html" title="Mint::UnknownCurrency (class)">UnknownCurrency</a></span> &lt; StandardError<small class='search_info'>Mint</small></div></li></ul></div></li><li id='object_Minting' class='odd'><div class='item' style='padding-left:30px'><span class='object_link'><a href="Minting.html" title="Minting (module)">Minting</a></span><small class='search_info'>Top Level Namespace</small></div></li>
 
       </ul>
     </div>

data/doc/file.README.html

@@ -234,12 +234,29 @@
 <li>Ambiguous symbols like <code>$</code> resolve by currency priority (currently USD).</li>
 <li>The parser scans all uppercase words for registered codes, so spurious non-currency words before the real code are correctly ignored: <code>Mint.parse(&quot;MAX 10.00 USD&quot;)</code> yields <code>[USD 10.00]</code>.</li>
 </ul>
+<h2 id="Currency_lookup">Currency lookup</h2>
+<pre class="code ruby"><code class="ruby"><span class='comment'># By ISO code (direct hash lookup, string only)
+</span><span class='const'><span class='object_link'><a href="Mint.html" title="Mint (module)">Mint</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Mint/Currency.html" title="Mint::Currency (class)">Currency</a></span></span><span class='period'>.</span><span class='id identifier rubyid_for_code'><span class='object_link'><a href="Mint/Currency.html#for_code-class_method" title="Mint::Currency.for_code (method)">for_code</a></span></span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>USD</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>        <span class='comment'>#=&gt; #&lt;Currency code=&quot;USD&quot; ...&gt;
+</span>
+<span class='comment'># By display symbol (highest-priority currency for ambiguous symbols)
+</span><span class='const'><span class='object_link'><a href="Mint.html" title="Mint (module)">Mint</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Mint/Currency.html" title="Mint::Currency (class)">Currency</a></span></span><span class='period'>.</span><span class='id identifier rubyid_for_symbol'><span class='object_link'><a href="Mint/Currency.html#for_symbol-class_method" title="Mint::Currency.for_symbol (method)">for_symbol</a></span></span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>$</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>        <span class='comment'>#=&gt; #&lt;Currency code=&quot;USD&quot; ...&gt;
+</span><span class='const'><span class='object_link'><a href="Mint.html" title="Mint (module)">Mint</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Mint/Currency.html" title="Mint::Currency (class)">Currency</a></span></span><span class='period'>.</span><span class='id identifier rubyid_for_symbol'><span class='object_link'><a href="Mint/Currency.html#for_symbol-class_method" title="Mint::Currency.for_symbol (method)">for_symbol</a></span></span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>R$</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>       <span class='comment'>#=&gt; #&lt;Currency code=&quot;BRL&quot; ...&gt;
+</span><span class='const'><span class='object_link'><a href="Mint.html" title="Mint (module)">Mint</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Mint/Currency.html" title="Mint::Currency (class)">Currency</a></span></span><span class='period'>.</span><span class='id identifier rubyid_for_symbol'><span class='object_link'><a href="Mint/Currency.html#for_symbol-class_method" title="Mint::Currency.for_symbol (method)">for_symbol</a></span></span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>€</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>        <span class='comment'>#=&gt; #&lt;Currency code=&quot;EUR&quot; ...&gt;
+</span>
+</code></pre>
 <h2 id="API_notes">API notes</h2>
 <p><strong>Exact amounts</strong> — Amounts are stored as <code>Rational</code> and rounded to the currency subunit.</p>
+<p><strong>Rounding modes</strong> — Wrap operations in <code>Mint.with_rounding(mode)</code> to change how amounts are rounded to the subunit:</p>
+<pre class="code ruby"><code class="ruby"><span class='const'><span class='object_link'><a href="Mint.html" title="Mint (module)">Mint</a></span></span><span class='period'>.</span><span class='id identifier rubyid_with_rounding'><span class='object_link'><a href="Mint.html#with_rounding-class_method" title="Mint.with_rounding (method)">with_rounding</a></span></span><span class='lparen'>(</span><span class='symbol'>:half_down</span><span class='rparen'>)</span> <span class='lbrace'>{</span> <span class='const'><span class='object_link'><a href="Mint.html" title="Mint (module)">Mint</a></span></span><span class='period'>.</span><span class='id identifier rubyid_money'><span class='object_link'><a href="Mint.html#money-class_method" title="Mint.money (method)">money</a></span></span><span class='lparen'>(</span><span class='float'>1.005</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>USD</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span> <span class='rbrace'>}</span>  <span class='comment'>#=&gt; [USD 1.00]
+</span><span class='const'><span class='object_link'><a href="Mint.html" title="Mint (module)">Mint</a></span></span><span class='period'>.</span><span class='id identifier rubyid_with_rounding'><span class='object_link'><a href="Mint.html#with_rounding-class_method" title="Mint.with_rounding (method)">with_rounding</a></span></span><span class='lparen'>(</span><span class='symbol'>:ceil</span><span class='rparen'>)</span>      <span class='lbrace'>{</span> <span class='const'><span class='object_link'><a href="Mint.html" title="Mint (module)">Mint</a></span></span><span class='period'>.</span><span class='id identifier rubyid_money'><span class='object_link'><a href="Mint.html#money-class_method" title="Mint.money (method)">money</a></span></span><span class='lparen'>(</span><span class='float'>1.001</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>USD</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span> <span class='rbrace'>}</span>  <span class='comment'>#=&gt; [USD 1.01]
+</span><span class='const'><span class='object_link'><a href="Mint.html" title="Mint (module)">Mint</a></span></span><span class='period'>.</span><span class='id identifier rubyid_with_rounding'><span class='object_link'><a href="Mint.html#with_rounding-class_method" title="Mint.with_rounding (method)">with_rounding</a></span></span><span class='lparen'>(</span><span class='symbol'>:floor</span><span class='rparen'>)</span>     <span class='lbrace'>{</span> <span class='const'><span class='object_link'><a href="Mint.html" title="Mint (module)">Mint</a></span></span><span class='period'>.</span><span class='id identifier rubyid_parse'><span class='object_link'><a href="Mint.html#parse-instance_method" title="Mint#parse (method)">parse</a></span></span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>1.009</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>USD</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span> <span class='rbrace'>}</span> <span class='comment'>#=&gt; [USD 1.00]
+</span></code></pre>
+<p>Modes: <code>:half_up</code> (default), <code>:half_down</code>, <code>:floor</code>, <code>:ceil</code>, <code>:truncate</code>, <code>:down</code>. Applies to construction, parsing, <code>change</code>, <code>split</code>, and <code>allocate</code>. Restores the previous mode when the block exits, even on exception.</p>
 <p><strong>Refinements</strong> — <code>10.dollars</code> and similar helpers require <code>using Mint</code> in the current scope (see Usage above).</p>
 <p><strong>Division</strong> — <code>money / 5</code> returns new <code>Money</code>; <code>money / other_money</code> returns a numeric ratio, not money.</p>
 <p><strong>Zero equality</strong> — Any zero amount is considered equal across currencies and to numeric zero (<code>Mint.money(0, 'USD') == Mint.money(0, 'EUR')</code> is intentionally <code>true</code>). Non-zero amounts must match currency and value.</p>
-<p><strong>Registered currencies</strong> — <code>Mint.register_currency</code>. Only registered currency codes and symbols are recognized by the parser.</p>
+<p><strong>Zero helper</strong> — <code>Currency.zero('USD')</code> returns a frozen zero-Money, useful as a default value for discounts, totals, or counters.</p>
+<p><strong>Registered currencies</strong> — <code>Currency.register(code:, subunit:, symbol:, priority:)</code> adds custom currencies. Only registered codes and symbols are recognized by the parser.</p>
 <p><strong>Built-in currencies</strong> — 150+ ISO-4217 world currencies ship in <code>lib/minting/data/currencies.yaml</code> and load when the registry is first accessed.</p>
 <h2 id="Optional_top_level__Money__and__Currency_">Optional top-level <code>Money</code> and <code>Currency</code></h2>
 <p>By default, Minting keeps everything namespaced under <code>Mint</code> to coexist nicely with other gems. If you prefer shorter constants, opt in:</p>
@@ -249,9 +266,13 @@
 <p>Or at runtime:</p>
 <pre class="code ruby"><code class="ruby"><span class='const'><span class='object_link'><a href="Minting.html" title="Minting (module)">Minting</a></span></span><span class='period'>.</span><span class='id identifier rubyid_use_top_level_constants!'>use_top_level_constants!</span>
 </code></pre>
+<p>For Rails applications, you can enable the top-level constants in an initializer:</p>
+<pre class="code ruby"><code class="ruby"><span class='comment'># config/initializers/minting.rb
+</span><span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>minting/dsl</span><span class='tstring_end'>&quot;</span></span>
+</code></pre>
 <p>After opting in:</p>
-<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_price'>price</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="top-level-namespace.html#Money-constant" title="Money (constant)">Money</a></span></span><span class='period'>.</span><span class='id identifier rubyid_create'>create</span><span class='lparen'>(</span><span class='int'>10</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>USD</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>     <span class='comment'># equivalent to Mint::Money.create
-</span><span class='id identifier rubyid_tax'>tax</span>   <span class='op'>=</span> <span class='const'><span class='object_link'><a href="top-level-namespace.html#Money-constant" title="Money (constant)">Money</a></span></span><span class='period'>.</span><span class='id identifier rubyid_money'>money</span><span class='lparen'>(</span><span class='float'>2.50</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>USD</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>
+<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_price'>price</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="top-level-namespace.html#Money-constant" title="Money (constant)">Money</a></span></span><span class='period'>.</span><span class='id identifier rubyid_from'>from</span><span class='lparen'>(</span><span class='int'>10</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>USD</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>                   <span class='comment'># equivalent to Mint::Money.from
+</span><span class='id identifier rubyid_tax'>tax</span>   <span class='op'>=</span> <span class='const'><span class='object_link'><a href="top-level-namespace.html#Money-constant" title="Money (constant)">Money</a></span></span><span class='period'>.</span><span class='id identifier rubyid_from'>from</span><span class='lparen'>(</span><span class='float'>2.50</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>USD</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>
 <span class='id identifier rubyid_cur'>cur</span>   <span class='op'>=</span> <span class='const'><span class='object_link'><a href="top-level-namespace.html#Currency-constant" title="Currency (constant)">Currency</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='lparen'>(</span><span class='label'>code:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>EUR</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='label'>symbol:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>€</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='label'>subunit:</span> <span class='int'>2</span><span class='comma'>,</span> <span class='label'>priority:</span> <span class='int'>0</span><span class='rparen'>)</span>
 </code></pre>
 <p><strong>Good fit:</strong> Application code, especially Rails apps.
@@ -265,7 +286,7 @@
 <p>MIT</p></div></div>
 
       <div id="footer">
-  Generated on Sun Jun 14 21:57:00 2026 by
+  Generated on Tue Jun 16 20:22:19 2026 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.44 (ruby-4.0.5).
 </div>