minting 1.7.2 → 1.8.0

data/doc/index.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>

data/doc/method_list.html

@@ -135,6 +135,22 @@
   </li>
   
 
+  <li class="even ">
+    <div class="item">
+      <span class='object_link'><a href="Mint/Rounding.html#apply-class_method" title="Mint::Rounding.apply (method)">apply</a></span>
+      <small>Mint::Rounding</small>
+    </div>
+  </li>
+  
+
+  <li class="odd ">
+    <div class="item">
+      <span class='object_link'><a href="Mint/Money.html#change-instance_method" title="Mint::Money#change (method)">#change</a></span>
+      <small>Mint::Money</small>
+    </div>
+  </li>
+  
+
   <li class="even ">
     <div class="item">
       <span class='object_link'><a href="Mint/Money.html#clamp-instance_method" title="Mint::Money#clamp (method)">#clamp</a></span>
@@ -177,23 +193,23 @@
 
   <li class="odd ">
     <div class="item">
-      <span class='object_link'><a href="Mint/CurrencyRegistry.html#currencies-instance_method" title="Mint::CurrencyRegistry#currencies (method)">#currencies</a></span>
-      <small>Mint::CurrencyRegistry</small>
+      <span class='object_link'><a href="Mint/Registry.html#currencies-class_method" title="Mint::Registry.currencies (method)">currencies</a></span>
+      <small>Mint::Registry</small>
     </div>
   </li>
   
 
   <li class="even ">
     <div class="item">
-      <span class='object_link'><a href="Mint.html#currency-class_method" title="Mint.currency (method)">currency</a></span>
-      <small>Mint</small>
+      <span class='object_link'><a href="Mint/Money.html#currency-instance_method" title="Mint::Money#currency (method)">#currency</a></span>
+      <small>Mint::Money</small>
     </div>
   </li>
   
 
   <li class="odd ">
     <div class="item">
-      <span class='object_link'><a href="Mint/Money.html#currency-instance_method" title="Mint::Money#currency (method)">#currency</a></span>
+      <span class='object_link'><a href="Mint/Money.html#currency_code-instance_method" title="Mint::Money#currency_code (method)">#currency_code</a></span>
       <small>Mint::Money</small>
     </div>
   </li>
@@ -201,21 +217,29 @@
 
   <li class="even ">
     <div class="item">
-      <span class='object_link'><a href="Mint/Money.html#currency_code-instance_method" title="Mint::Money#currency_code (method)">#currency_code</a></span>
-      <small>Mint::Money</small>
+      <span class='object_link'><a href="Mint/Registry.html#currency_for_symbol-instance_method" title="Mint::Registry#currency_for_symbol (method)">#currency_for_symbol</a></span>
+      <small>Mint::Registry</small>
     </div>
   </li>
   
 
   <li class="odd ">
     <div class="item">
-      <span class='object_link'><a href="Mint/CurrencyRegistry.html#currency_symbols-instance_method" title="Mint::CurrencyRegistry#currency_symbols (method)">#currency_symbols</a></span>
-      <small>Mint::CurrencyRegistry</small>
+      <span class='object_link'><a href="Mint/Rounding.html#current_mode-class_method" title="Mint::Rounding.current_mode (method)">current_mode</a></span>
+      <small>Mint::Rounding</small>
     </div>
   </li>
   
 
   <li class="even ">
+    <div class="item">
+      <span class='object_link'><a href="Mint/Registry.html#detect_currency-instance_method" title="Mint::Registry#detect_currency (method)">#detect_currency</a></span>
+      <small>Mint::Registry</small>
+    </div>
+  </li>
+  
+
+  <li class="odd ">
     <div class="item">
       <span class='object_link'><a href="Mint/Money.html#eql%3F-instance_method" title="Mint::Money#eql? (method)">#eql?</a></span>
       <small>Mint::Money</small>
@@ -223,7 +247,23 @@
   </li>
   
 
+  <li class="even ">
+    <div class="item">
+      <span class='object_link'><a href="Mint/Currency.html#for_code-class_method" title="Mint::Currency.for_code (method)">for_code</a></span>
+      <small>Mint::Currency</small>
+    </div>
+  </li>
+  
+
   <li class="odd ">
+    <div class="item">
+      <span class='object_link'><a href="Mint/Currency.html#for_symbol-class_method" title="Mint::Currency.for_symbol (method)">for_symbol</a></span>
+      <small>Mint::Currency</small>
+    </div>
+  </li>
+  
+
+  <li class="even ">
     <div class="item">
       <span class='object_link'><a href="Mint/Money.html#fractional-instance_method" title="Mint::Money#fractional (method)">#fractional</a></span>
       <small>Mint::Money</small>
@@ -231,7 +271,7 @@
   </li>
   
 
-  <li class="even ">
+  <li class="odd ">
     <div class="item">
       <span class='object_link'><a href="Mint/Currency.html#fractional_multiplier-instance_method" title="Mint::Currency#fractional_multiplier (method)">#fractional_multiplier</a></span>
       <small>Mint::Currency</small>
@@ -239,6 +279,14 @@
   </li>
   
 
+  <li class="even ">
+    <div class="item">
+      <span class='object_link'><a href="Mint/Money.html#from-class_method" title="Mint::Money.from (method)">from</a></span>
+      <small>Mint::Money</small>
+    </div>
+  </li>
+  
+
   <li class="odd ">
     <div class="item">
       <span class='object_link'><a href="Mint/Money.html#from_fractional-class_method" title="Mint::Money.from_fractional (method)">from_fractional</a></span>
@@ -265,21 +313,29 @@
 
   <li class="even ">
     <div class="item">
-      <span class='object_link'><a href="Mint/Currency.html#inspect-instance_method" title="Mint::Currency#inspect (method)">#inspect</a></span>
-      <small>Mint::Currency</small>
+      <span class='object_link'><a href="Mint/Money.html#inspect-instance_method" title="Mint::Money#inspect (method)">#inspect</a></span>
+      <small>Mint::Money</small>
     </div>
   </li>
   
 
   <li class="odd ">
     <div class="item">
-      <span class='object_link'><a href="Mint/Money.html#inspect-instance_method" title="Mint::Money#inspect (method)">#inspect</a></span>
-      <small>Mint::Money</small>
+      <span class='object_link'><a href="Mint/Currency.html#inspect-instance_method" title="Mint::Currency#inspect (method)">#inspect</a></span>
+      <small>Mint::Currency</small>
     </div>
   </li>
   
 
   <li class="even ">
+    <div class="item">
+      <span class='object_link'><a href="Mint.html#locale_backend-class_method" title="Mint.locale_backend (method)">locale_backend</a></span>
+      <small>Mint</small>
+    </div>
+  </li>
+  
+
+  <li class="odd ">
     <div class="item">
       <span class='object_link'><a href="Mint/Currency.html#minimum_amount-instance_method" title="Mint::Currency#minimum_amount (method)">#minimum_amount</a></span>
       <small>Mint::Currency</small>
@@ -287,7 +343,7 @@
   </li>
   
 
-  <li class="odd ">
+  <li class="even ">
     <div class="item">
       <span class='object_link'><a href="Mint/Money.html#mint-instance_method" title="Mint::Money#mint (method)">#mint</a></span>
       <small>Mint::Money</small>
@@ -295,7 +351,7 @@
   </li>
   
 
-  <li class="even ">
+  <li class="odd ">
     <div class="item">
       <span class='object_link'><a href="Mint.html#money-class_method" title="Mint.money (method)">money</a></span>
       <small>Mint</small>
@@ -303,7 +359,7 @@
   </li>
   
 
-  <li class="odd ">
+  <li class="even ">
     <div class="item">
       <span class='object_link'><a href="Mint/Currency.html#name-instance_method" title="Mint::Currency#name (method)">#name</a></span>
       <small>Mint::Currency</small>
@@ -311,7 +367,7 @@
   </li>
   
 
-  <li class="even ">
+  <li class="odd ">
     <div class="item">
       <span class='object_link'><a href="Mint/Money.html#negative%3F-instance_method" title="Mint::Money#negative? (method)">#negative?</a></span>
       <small>Mint::Money</small>
@@ -319,7 +375,7 @@
   </li>
   
 
-  <li class="odd ">
+  <li class="even ">
     <div class="item">
       <span class='object_link'><a href="Mint/Money.html#nonzero%3F-instance_method" title="Mint::Money#nonzero? (method)">#nonzero?</a></span>
       <small>Mint::Money</small>
@@ -327,7 +383,7 @@
   </li>
   
 
-  <li class="even ">
+  <li class="odd ">
     <div class="item">
       <span class='object_link'><a href="Mint/Currency.html#normalize_amount-instance_method" title="Mint::Currency#normalize_amount (method)">#normalize_amount</a></span>
       <small>Mint::Currency</small>
@@ -335,7 +391,7 @@
   </li>
   
 
-  <li class="odd ">
+  <li class="even ">
     <div class="item">
       <span class='object_link'><a href="Mint.html#parse-instance_method" title="Mint#parse (method)">#parse</a></span>
       <small>Mint</small>
@@ -343,6 +399,30 @@
   </li>
   
 
+  <li class="odd ">
+    <div class="item">
+      <span class='object_link'><a href="Mint/Money.html#parse-class_method" title="Mint::Money.parse (method)">parse</a></span>
+      <small>Mint::Money</small>
+    </div>
+  </li>
+  
+
+  <li class="even ">
+    <div class="item">
+      <span class='object_link'><a href="Mint/Money.html#parse!-class_method" title="Mint::Money.parse! (method)">parse!</a></span>
+      <small>Mint::Money</small>
+    </div>
+  </li>
+  
+
+  <li class="odd ">
+    <div class="item">
+      <span class='object_link'><a href="Mint.html#parse!-instance_method" title="Mint#parse! (method)">#parse!</a></span>
+      <small>Mint</small>
+    </div>
+  </li>
+  
+
   <li class="even ">
     <div class="item">
       <span class='object_link'><a href="Mint/Money.html#positive%3F-instance_method" title="Mint::Money#positive? (method)">#positive?</a></span>
@@ -361,16 +441,32 @@
 
   <li class="even ">
     <div class="item">
-      <span class='object_link'><a href="Mint/CurrencyRegistry.html#register-instance_method" title="Mint::CurrencyRegistry#register (method)">#register</a></span>
-      <small>Mint::CurrencyRegistry</small>
+      <span class='object_link'><a href="Mint/Registry.html#register-class_method" title="Mint::Registry.register (method)">register</a></span>
+      <small>Mint::Registry</small>
     </div>
   </li>
   
 
   <li class="odd ">
     <div class="item">
-      <span class='object_link'><a href="Mint.html#register_currency-class_method" title="Mint.register_currency (method)">register_currency</a></span>
-      <small>Mint</small>
+      <span class='object_link'><a href="Mint/Currency.html#register-class_method" title="Mint::Currency.register (method)">register</a></span>
+      <small>Mint::Currency</small>
+    </div>
+  </li>
+  
+
+  <li class="even ">
+    <div class="item">
+      <span class='object_link'><a href="Mint/Currency.html#resolve-class_method" title="Mint::Currency.resolve (method)">resolve</a></span>
+      <small>Mint::Currency</small>
+    </div>
+  </li>
+  
+
+  <li class="odd ">
+    <div class="item">
+      <span class='object_link'><a href="Mint/Currency.html#resolve!-class_method" title="Mint::Currency.resolve! (method)">resolve!</a></span>
+      <small>Mint::Currency</small>
     </div>
   </li>
   
@@ -495,6 +591,22 @@
   </li>
   
 
+  <li class="odd ">
+    <div class="item">
+      <span class='object_link'><a href="Mint/Rounding.html#with_mode-class_method" title="Mint::Rounding.with_mode (method)">with_mode</a></span>
+      <small>Mint::Rounding</small>
+    </div>
+  </li>
+  
+
+  <li class="even ">
+    <div class="item">
+      <span class='object_link'><a href="Mint.html#with_rounding-class_method" title="Mint.with_rounding (method)">with_rounding</a></span>
+      <small>Mint</small>
+    </div>
+  </li>
+  
+
   <li class="odd ">
     <div class="item">
       <span class='object_link'><a href="Mint.html#world_currencies-class_method" title="Mint.world_currencies (method)">world_currencies</a></span>
@@ -503,6 +615,38 @@
   </li>
   
 
+  <li class="even ">
+    <div class="item">
+      <span class='object_link'><a href="Mint/Registry.html#world_currencies-class_method" title="Mint::Registry.world_currencies (method)">world_currencies</a></span>
+      <small>Mint::Registry</small>
+    </div>
+  </li>
+  
+
+  <li class="odd ">
+    <div class="item">
+      <span class='object_link'><a href="Mint/Money.html#zero-class_method" title="Mint::Money.zero (method)">zero</a></span>
+      <small>Mint::Money</small>
+    </div>
+  </li>
+  
+
+  <li class="even ">
+    <div class="item">
+      <span class='object_link'><a href="Mint/Currency.html#zero-class_method" title="Mint::Currency.zero (method)">zero</a></span>
+      <small>Mint::Currency</small>
+    </div>
+  </li>
+  
+
+  <li class="odd ">
+    <div class="item">
+      <span class='object_link'><a href="Mint/Currency.html#zero-instance_method" title="Mint::Currency#zero (method)">#zero</a></span>
+      <small>Mint::Currency</small>
+    </div>
+  </li>
+  
+
   <li class="even ">
     <div class="item">
       <span class='object_link'><a href="Mint/Money.html#zero%3F-instance_method" title="Mint::Money#zero? (method)">#zero?</a></span>
@@ -511,6 +655,14 @@
   </li>
   
 
+  <li class="odd ">
+    <div class="item">
+      <span class='object_link'><a href="Mint/Registry.html#zero_for-class_method" title="Mint::Registry.zero_for (method)">zero_for</a></span>
+      <small>Mint::Registry</small>
+    </div>
+  </li>
+  
+
 
       </ul>
     </div>

data/doc/top-level-namespace.html

@@ -141,7 +141,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/lib/minting/currency/currency.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# :nodoc:
 module Mint
   # Represents a specific currency unit, identified by ISO 4217 alphabetic code.
   # Currency objects are immutable and define the properties of a monetary unit
@@ -39,6 +40,75 @@ module Mint
     # Normalizes numeric amounts for this currency
     # 1. Converts to Rational
     # 2. Rounds to respect currency subunit
-    def normalize_amount(amount) = amount.to_r.round(subunit)
+    def normalize_amount(amount) = Mint::Rounding.apply(amount, subunit)
+
+    def zero = Registry.zero_for(self)
+  end
+
+  # Registers a new currency, raising a KeyError if already registered.
+  #
+  # @param code [String] the unique currency code
+  # @param subunit [Integer] the decimal subunit precision, defaults to 0
+  # @param symbol [String] the display symbol
+  # @param priority [Integer] parser precedence priority
+  # @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:)
   end
+
+  # Resolves an object into a {Currency}, returning +nil+ when it can't.
+  #
+  # Accepts +nil+, +String+, {Currency}, or {Money}.
+  # Passing a {Money} extracts its currency
+  #
+  # @param object [String, Currency, Money, nil] a currency code, object, or +nil+
+  # @return [Currency, nil] the resolved Currency, or +nil+ if +object+ is +nil+
+  #   or the code is not registered
+  # @raise [ArgumentError] if +object+ is an unsupported type (e.g. +Integer+)
+  def Currency.resolve(object)
+    case object
+    when NilClass then nil
+    when Currency then object
+    when Money    then object.currency
+    when String   then Currency.for_code object
+    else          raise ArgumentError, "currency must be [Currency], [Money], [String] or nil (#{object})"
+    end
+  end
+
+  # Resolves an object into a {Currency}, raising on failure.
+  #
+  # Like {.resolve} but raises when the result would be +nil+.
+  #
+  # @param object [String, Currency, Money, nil] a currency code, object, or +nil+
+  # @return [Currency] the resolved Currency
+  # @raise [ArgumentError] if +object+ cannot be resolved into a registered currency
+  def Currency.resolve!(object)
+    resolve(object) or raise ArgumentError, "Could not resolve (#{object}) into a currency"
+  end
+
+  # Looks up a registered currency by its alpha code.
+  #
+  # @param code [String] the currency code
+  # @return [Currency, nil] the registered Currency, or +nil+ if not found
+  def Currency.for_code(code)
+    Registry.currencies[code]
+  end
+
+  # Looks up a currency by its display symbol.
+  #
+  # @param symbol [String] the display symbol (e.g. "$", "R$")
+  # @return [Currency, nil] the highest-priority currency for the symbol
+  def Currency.for_symbol(symbol)
+    Registry.currency_for_symbol(symbol)
+  end
+
+  # Returns a zero {Money} in the given currency, useful as a default value
+  # for discounts, totals, or placeholders.
+  #
+  # @param currency [String, Currency] a currency code or object
+  # @return [Money] a frozen zero-Money
+  # @raise [ArgumentError] if the currency can't be resolved
+  def Currency.zero(currency) = Registry.zero_for(Currency.resolve!(currency))
 end

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

@@ -62,6 +62,7 @@ module Mint
         end
       end
     end
+
     Range.prepend(Mint::RangeStepPatch)
   end
 end

data/lib/minting/mint/locale_backend.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# :nodoc:
+module Mint
+  class << self
+    # Optional callable that returns a Hash with locale-aware formatting defaults.
+    #
+    # The callable receives no arguments and returns a Hash with these keys:
+    #   [+:decimal+]   Decimal separator (e.g. +","+)
+    #   [+:thousand+]  Thousands delimiter (e.g. +"."+)
+    #   [+:format+]    Format template string (e.g. +"%<amount>f %<symbol>s"+)
+    #
+    # When set, +#to_s+ and +#format+ use these values as fallbacks when the
+    # corresponding parameter is not explicitly provided.
+    #
+    # @example Rails I18n integration (in minting-rails railtie)
+    #   Mint.locale_backend = -> {
+    #     fmt = I18n.t('number.currency.format')
+    #     {
+    #       decimal: fmt[:separator],
+    #       thousand: fmt[:delimiter],
+    #       format: fmt[:format] == '%n %u' ? '%<amount>f %<symbol>s' : '%<symbol>s%<amount>f'
+    #     }
+    #   }
+    #
+    # @return [Proc, #call, nil]
+    attr_accessor :locale_backend
+  end
+end