minting 1.8.2 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 531ae60785c01288f3c5b6ffe222c86582c49e368770e8ac1dc89bfae675f279
-  data.tar.gz: 3fd0d185d01ed315ea0bd5e89f8c923d5d1712ec571041cd678a7749fbf3ab44
+  metadata.gz: 84b163ccea567387ace107bbb07ff1089217eade0bccc9b5272f53727c302220
+  data.tar.gz: 646e33a6fe8cdb75e6b50cee77954413f9e074788fbc316eb08cba3f4d9d6591
 SHA512:
-  metadata.gz: e0799f5c93aac8f065d1b213e848d4ec650278b93e475431ca7c6f71cc69cece2525c51fa4b7d2a54e6317f27befb68cfbf362b3c74960ce51a962cd0178d86c
-  data.tar.gz: ae2121c6b9d7115b3ef40dbef4761ac0257cfea1770141543c87c741c0c49f8e5d60ef95970042dffe895ec948cc5c1dbf6ccf644aa34f401407003303c10744
+  metadata.gz: 9813ca14235c64e1893ec13dbd2b911450ab034084f93fbd02a19cac6d6c9b94e1e43c718724b6557b08f8a11bae855ae51f082c59b76432e60a9e069d075d2f
+  data.tar.gz: 9f56372568a9b0004115181abd47ab2efc0ffc35723bf1037a579ce5830cb88ed0bd10d5bf17a65b26bc323697d38944b997eafc33bae6b6b94c7e238499ec09

data/README.md

@@ -5,7 +5,6 @@ Fast, precise, and developer-friendly money handling for Ruby.
 [![Gem Version](https://badge.fury.io/rb/minting.svg)](https://badge.fury.io/rb/minting)
 [![CI](https://github.com/gferraz/minting/actions/workflows/ci.yml/badge.svg)](https://github.com/gferraz/minting/actions/workflows/ci.yml)
 [![Test Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/gferraz/minting)
-[![RubyCritic](https://img.shields.io/badge/RubyCritic-94gem /100-brightgreen)](https://github.com/gferraz/minting)
 [![Documentation](https://img.shields.io/badge/docs-rubydoc.info-blue)](https://www.rubydoc.info/gems/minting/frames)
 
 ## Quick start
@@ -25,7 +24,7 @@ total.currency_code                    #=> "USD"
 Amounts are stored as `Rational` and rounded to the currency subunit. No floating-point surprises, ever.
 
 ### Blazing performance
-Minting is faster than the Money gem for everyday operations and **over 10× faster for formatting**. See full benchmarks in the [Performance Guide](test/performance/README.md).
+Minting is faster than the Money gem for everyday operations and **over 10× faster for formatting**. See full benchmarks in the [Performance Guide](test/performance/BENCHMARKS.md).
 
 ### Clean, modern API
 Intuitive interface, descriptive error messages, and sensible defaults. Works the way you expect.
@@ -35,7 +34,7 @@ Use with the [minting-rails](https://github.com/gferraz/minting-rails) companion
 
 ### Quality code
 - **100% test coverage** — every line exercised
-- **93/100 RubyCritic score** — clean, maintainable code
+- **94/100 RubyCritic score** — clean, maintainable code
 - **CI-tested on Ruby 3.3 and 4.0**
 
 ## Installation
@@ -81,7 +80,19 @@ Mint.money(10, 'USD') == 10                    #=> false
 
 # Format (uses Kernel.format syntax)
 price = Mint.money(9.99, 'USD')
+loss  = Mint.money(-1234.56, 'USD')
 
+# Built-in named presets
+loss.to_s(:accounting)                      #=> "($1,234.56)"
+Mint.money(1234.56, 'EUR').to_s(:european)  #=> "1.234,56 €"
+price.to_s(:amount)                         #=> "9.99"
+price.to_s(:currency)                       #=> "USD 9.99"
+
+# Presets can be overridden with explicit kwargs
+Mint.money(1234.56, 'EUR').to_s(:european, format: '%<amount>f %<currency>s')
+#=> "1.234,56 EUR"
+
+# Or use direct format strings
 price.to_s                                  #=> "$9.99",
 price.to_s(format: '%<amount>d')            #=> "9",
 price.to_s(format: '%<symbol>s%<amount>f')  #=> "$9.99",
@@ -97,6 +108,11 @@ price.to_s(format: '  %<amount>10f %<currency>s') #=> "        9.99 USD"
 
 price_in_euros.to_s(format: '%<symbol>2s%<amount>+10f')    #=> " €    +12.34"
 
+# Integral & fractional parts
+price.to_s(format: '%<integral>d %<fractional>d/100')        #=> "9 99/100"
+Mint.money(0.99, 'USD').to_s(format: '%<integral>d dollars and %<fractional>02d cents')
+#=> "0 dollars and 99 cents"
+
 # Per-sign Hash format (e.g. accounting parentheses for losses)
 loss = Mint.money(-1234.56, 'USD')
 loss.to_s(format: { negative: '(%<symbol>s%<amount>f)' })  #=> "($1,234.56)"
@@ -116,9 +132,9 @@ price.to_hash #=> {currency: "USD", amount: "9.99"}
 
 # Fractional units (inverse of #fractional) - exact integer arithmetic
 
-price.fractional                        #=> 999
-Mint::Money.from_fractional(999, 'USD') #=> [USD 9.99]
-Mint::Money.from_fractional(1234, 'JPY') #=> [JPY 1234]  # subunit 0 -> no scaling
+price.subunits                        #=> 999
+Mint::Money.from_subunits(999, 'USD') #=> [USD 9.99]
+Mint::Money.from_subunits(1234, 'JPY') #=> [JPY 1234]  # subunit 0 -> no scaling
 
 
 # No currency (ISO 4217 XXX)
@@ -164,7 +180,7 @@ Notes:
 - Pass a currency code when the string has no symbol or code.
 - `1,234` means 1234, not 1.234 and `1,23` means 1.23, not 123
 - `1,234.00` is unambiguous (thousands + decimal).
-- Accounting negatives like `($1.23)` are unsupported for now.
+- 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: `Mint.parse("MAX 10.00 USD")` yields `[USD 10.00]`.
 
@@ -195,6 +211,8 @@ 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.
 
+> **Performance note:** Rounding-mode support is not loaded by default — `require 'minting'` uses the fastest possible rounding (equivalent to `:half_up`) with zero dispatch overhead. The first call to `Mint.with_rounding` loads the rounding module and patches `Currency#normalize_amount`, adding ~10–35 ns per money creation or mutation. If your application never uses custom rounding modes (the common case), there is **no performance cost**.
+
 **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.
@@ -203,7 +221,7 @@ Modes: `:half_up` (default), `:half_down`, `:floor`, `:ceil`, `:truncate`, `:dow
 
 **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.
+**Registered currencies** — `Currency.register(code:, subunit:, symbol:, priority:)` adds custom currencies. Only registered codes and symbols are recognized by the parser or searches. Nonetheless, you don't need to register a currency to use it with most of the features.
 
 **Built-in currencies** — 150+ ISO-4217 world currencies ship in `lib/minting/data/currencies.yaml` and load when the registry is first accessed.
 
@@ -242,7 +260,6 @@ cur   = Currency.new(code: "EUR", symbol: "€", subunit: 2, priority: 0)
 
 ## Roadmap
 
-- Localization (I18n-aware formatting)
 - Exchange-rate conversion infrastructure
 
 ## License

data/bin/bench_check

@@ -24,15 +24,26 @@ end
 
 current = JSON.parse(File.read(current_json.path))
 
+MODES = %w[no_rounding half_down].freeze
+
+all_ratios = []
 failures = []
-baseline['results'].each do |key, b|
-  c = current.dig('results', key)
-  next unless c
-
-  ratio = c['ips'].to_f / b['ips']
-  if ratio < threshold
-    failures << format('%<key>-15s baseline: %<b>10d ips  current: %<c>10d ips  ratio: %<ratio>5.1f%%',
-                       key:, b: b['ips'], c: c['ips'], ratio: ratio * 100)
+MODES.each do |mode|
+  b_mode = baseline.dig('results', mode)
+  c_mode = current.dig('results', mode)
+  next unless b_mode && c_mode
+
+  b_mode.each do |key, b|
+    c = c_mode[key]
+    next unless c
+
+    ratio = c['ips'].to_f / b['ips']
+    all_ratios << { mode:, key:, ratio:, b: b['ips'], c: c['ips'] }
+
+    if ratio < threshold
+      failures << format('%<mode>s %<key>-15s baseline: %<b>10d ips  current: %<c>10d ips  ratio: %<ratio>5.1f%%',
+                         mode:, key:, b: b['ips'], c: c['ips'], ratio: ratio * 100)
+    end
   end
 end
 
@@ -42,5 +53,19 @@ if failures.empty?
 else
   puts 'Regressions detected:'
   failures.each { |f| puts "  FAIL  #{f}" }
-  exit 1
 end
+
+puts "\n--- Best vs Worst vs Baseline ---"
+MODES.each do |mode|
+  entries = all_ratios.select { |r| r[:mode] == mode }
+  next if entries.empty?
+
+  best = entries.max_by { |r| r[:ratio] }
+  worst = entries.min_by { |r| r[:ratio] }
+
+  puts "#{mode}:"
+  puts "  Best:        #{format('%<key>-15s ratio: %<ratio>5.1f%%  baseline: %<b>10d ips  current: %<c>10d ips', key: best[:key], ratio: best[:ratio] * 100, b: best[:b], c: best[:c])}"
+  puts "  Worst:       #{format('%<key>-15s ratio: %<ratio>5.1f%%  baseline: %<b>10d ips  current: %<c>10d ips', key: worst[:key], ratio: worst[:ratio] * 100, b: worst[:b], c: worst[:c])}"
+end
+
+exit 1 unless failures.empty?

data/doc/Mint/Currency.html

@@ -566,7 +566,7 @@ including its subunit precision, display symbol, and formatting rules.</p>
         <li class="public ">
   <span class="summary_signature">
     
-      <a href="#zero-instance_method" title="#zero (instance method)">#<strong>zero</strong>  &#x21d2; Object </a>
+      <a href="#zero-instance_method" title="#zero (instance method)">#<strong>zero</strong>  &#x21d2; Money </a>
     
 
     
@@ -580,7 +580,7 @@ including its subunit precision, display symbol, and formatting rules.</p>
   
 
   
-    <span class="summary_desc"><div class='inline'></div></span>
+    <span class="summary_desc"><div class='inline'><p>Returns the cached frozen zero-Money for this currency.</p></div></span>
   
 </li>
 
@@ -1205,12 +1205,12 @@ including its subunit precision, display symbol, and formatting rules.</p>
       <pre class="lines">
 
 
-95
-96
-97</pre>
+100
+101
+102</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/minting/currency/currency.rb', line 95</span>
+      <pre class="code"><span class="info file"># File 'lib/minting/currency/currency.rb', line 100</span>
 
 <span class='kw'>def</span> <span class='const'><span class='object_link'><a href="" title="Mint::Currency (class)">Currency</a></span></span><span class='period'>.</span><span class='id identifier rubyid_for_code'>for_code</span><span class='lparen'>(</span><span class='id identifier rubyid_code'>code</span><span class='rparen'>)</span>
   <span class='const'><span class='object_link'><a href="Registry.html" title="Mint::Registry (module)">Registry</a></span></span><span class='period'>.</span><span class='id identifier rubyid_currencies'><span class='object_link'><a href="Registry.html#currencies-class_method" title="Mint::Registry.currencies (method)">currencies</a></span></span><span class='lbracket'>[</span><span class='id identifier rubyid_code'>code</span><span class='rbracket'>]</span>
@@ -1278,12 +1278,12 @@ including its subunit precision, display symbol, and formatting rules.</p>
       <pre class="lines">
 
 
-103
-104
-105</pre>
+108
+109
+110</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/minting/currency/currency.rb', line 103</span>
+      <pre class="code"><span class="info file"># File 'lib/minting/currency/currency.rb', line 108</span>
 
 <span class='kw'>def</span> <span class='const'><span class='object_link'><a href="" title="Mint::Currency (class)">Currency</a></span></span><span class='period'>.</span><span class='id identifier rubyid_for_symbol'>for_symbol</span><span class='lparen'>(</span><span class='id identifier rubyid_symbol'>symbol</span><span class='rparen'>)</span>
   <span class='const'><span class='object_link'><a href="Registry.html" title="Mint::Registry (module)">Registry</a></span></span><span class='period'>.</span><span class='id identifier rubyid_currency_for_symbol'><span class='object_link'><a href="Registry.html#currency_for_symbol-instance_method" title="Mint::Registry#currency_for_symbol (method)">currency_for_symbol</a></span></span><span class='lparen'>(</span><span class='id identifier rubyid_symbol'>symbol</span><span class='rparen'>)</span>
@@ -1427,12 +1427,12 @@ including its subunit precision, display symbol, and formatting rules.</p>
       <pre class="lines">
 
 
-57
-58
-59</pre>
+62
+63
+64</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/minting/currency/currency.rb', line 57</span>
+      <pre class="code"><span class="info file"># File 'lib/minting/currency/currency.rb', line 62</span>
 
 <span class='kw'>def</span> <span class='const'><span class='object_link'><a href="" title="Mint::Currency (class)">Currency</a></span></span><span class='period'>.</span><span class='id identifier rubyid_register'>register</span><span class='lparen'>(</span><span class='label'>code:</span><span class='comma'>,</span> <span class='label'>subunit:</span> <span class='int'>0</span><span class='comma'>,</span> <span class='label'>symbol:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span> <span class='label'>priority:</span> <span class='int'>0</span><span class='rparen'>)</span>
   <span class='const'><span class='object_link'><a href="Registry.html" title="Mint::Registry (module)">Registry</a></span></span><span class='period'>.</span><span class='id identifier rubyid_register'><span class='object_link'><a href="Registry.html#register-class_method" title="Mint::Registry.register (method)">register</a></span></span><span class='lparen'>(</span><span class='label'>code:</span><span class='comma'>,</span> <span class='label'>subunit:</span><span class='comma'>,</span> <span class='label'>symbol:</span><span class='comma'>,</span> <span class='label'>priority:</span><span class='rparen'>)</span>
@@ -1519,18 +1519,18 @@ or the code is not registered</p></div>
       <pre class="lines">
 
 
-70
-71
-72
-73
-74
 75
 76
 77
-78</pre>
+78
+79
+80
+81
+82
+83</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/minting/currency/currency.rb', line 70</span>
+      <pre class="code"><span class="info file"># File 'lib/minting/currency/currency.rb', line 75</span>
 
 <span class='kw'>def</span> <span class='const'><span class='object_link'><a href="" title="Mint::Currency (class)">Currency</a></span></span><span class='period'>.</span><span class='id identifier rubyid_resolve'>resolve</span><span class='lparen'>(</span><span class='id identifier rubyid_object'>object</span><span class='rparen'>)</span>
   <span class='kw'>case</span> <span class='id identifier rubyid_object'>object</span>
@@ -1621,12 +1621,12 @@ or the code is not registered</p></div>
       <pre class="lines">
 
 
-87
-88
-89</pre>
+92
+93
+94</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/minting/currency/currency.rb', line 87</span>
+      <pre class="code"><span class="info file"># File 'lib/minting/currency/currency.rb', line 92</span>
 
 <span class='kw'>def</span> <span class='const'><span class='object_link'><a href="" title="Mint::Currency (class)">Currency</a></span></span><span class='period'>.</span><span class='id identifier rubyid_resolve!'>resolve!</span><span class='lparen'>(</span><span class='id identifier rubyid_object'>object</span><span class='rparen'>)</span>
   <span class='id identifier rubyid_resolve'>resolve</span><span class='lparen'>(</span><span class='id identifier rubyid_object'>object</span><span class='rparen'>)</span> <span class='kw'>or</span> <span class='id identifier rubyid_raise'>raise</span> <span class='const'>ArgumentError</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Could not resolve (</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_object'>object</span><span class='embexpr_end'>}</span><span class='tstring_content'>) into a currency</span><span class='tstring_end'>&quot;</span></span>
@@ -1711,10 +1711,10 @@ for discounts, totals, or placeholders.</p>
       <pre class="lines">
 
 
-113</pre>
+118</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/minting/currency/currency.rb', line 113</span>
+      <pre class="code"><span class="info file"># File 'lib/minting/currency/currency.rb', line 118</span>
 
 <span class='kw'>def</span> <span class='const'><span class='object_link'><a href="" title="Mint::Currency (class)">Currency</a></span></span><span class='period'>.</span><span class='id identifier rubyid_zero'>zero</span><span class='lparen'>(</span><span class='id identifier rubyid_currency'>currency</span><span class='rparen'>)</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="Registry.html" title="Mint::Registry (module)">Registry</a></span></span><span class='period'>.</span><span class='id identifier rubyid_zero_for'><span class='object_link'><a href="Registry.html#zero_for-class_method" title="Mint::Registry.zero_for (method)">zero_for</a></span></span><span class='lparen'>(</span><span class='const'><span class='object_link'><a href="" title="Mint::Currency (class)">Currency</a></span></span><span class='period'>.</span><span class='id identifier rubyid_resolve!'><span class='object_link'><a href="#resolve!-class_method" title="Mint::Currency.resolve! (method)">resolve!</a></span></span><span class='lparen'>(</span><span class='id identifier rubyid_currency'>currency</span><span class='rparen'>)</span><span class='rparen'>)</span></pre>
     </td>
@@ -1863,7 +1863,7 @@ for discounts, totals, or placeholders.</p>
     <td>
       <pre class="code"><span class="info file"># File 'lib/minting/currency/currency.rb', line 43</span>
 
-<span class='kw'>def</span> <span class='id identifier rubyid_normalize_amount'>normalize_amount</span><span class='lparen'>(</span><span class='id identifier rubyid_amount'>amount</span><span class='rparen'>)</span> <span class='op'>=</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="Rounding.html" title="Mint::Rounding (module)">Rounding</a></span></span><span class='period'>.</span><span class='id identifier rubyid_apply'><span class='object_link'><a href="Rounding.html#apply-class_method" title="Mint::Rounding.apply (method)">apply</a></span></span><span class='lparen'>(</span><span class='id identifier rubyid_amount'>amount</span><span class='comma'>,</span> <span class='id identifier rubyid_subunit'>subunit</span><span class='rparen'>)</span></pre>
+<span class='kw'>def</span> <span class='id identifier rubyid_normalize_amount'>normalize_amount</span><span class='lparen'>(</span><span class='id identifier rubyid_amount'>amount</span><span class='rparen'>)</span> <span class='op'>=</span> <span class='id identifier rubyid_amount'>amount</span><span class='period'>.</span><span class='id identifier rubyid_to_r'>to_r</span><span class='period'>.</span><span class='id identifier rubyid_round'>round</span><span class='lparen'>(</span><span class='id identifier rubyid_subunit'>subunit</span><span class='rparen'>)</span></pre>
     </td>
   </tr>
 </table>
@@ -1872,22 +1872,55 @@ for discounts, totals, or placeholders.</p>
       <div class="method_details ">
   <h3 class="signature " id="zero-instance_method">
   
-    #<strong>zero</strong>  &#x21d2; <tt>Object</tt> 
+    #<strong>zero</strong>  &#x21d2; <tt><span class='object_link'><a href="Money.html" title="Mint::Money (class)">Money</a></span></tt> 
   
 
   
 
   
-</h3><table class="source_code">
+</h3><div class="docstring">
+  <div class="discussion">
+    <p>Returns the cached frozen zero-Money for this currency.</p>
+
+  </div>
+</div>
+<div class="tags">
+  
+  <div class="examples">
+    <h4 class="tag_title">Examples:</h4>
+    
+      
+      <pre class="example code"><code><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="" 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="#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='period'>.</span><span class='id identifier rubyid_zero'><span class='object_link'><a href="#zero-class_method" title="Mint::Currency.zero (method)">zero</a></span></span>  <span class='comment'>#=&gt; [USD 0.00]</span></code></pre>
+    
+  </div>
+
+<p class="tag_title">Returns:</p>
+<ul class="return">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt><span class='object_link'><a href="Money.html" title="Mint::Money (class)">Money</a></span></tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'><p>a frozen zero-Money instance</p></div>
+      
+    </li>
+  
+</ul>
+
+</div><table class="source_code">
   <tr>
     <td>
       <pre class="lines">
 
 
-45</pre>
+50</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/minting/currency/currency.rb', line 45</span>
+      <pre class="code"><span class="info file"># File 'lib/minting/currency/currency.rb', line 50</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_zero'>zero</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="Registry.html" title="Mint::Registry (module)">Registry</a></span></span><span class='period'>.</span><span class='id identifier rubyid_zero_for'><span class='object_link'><a href="Registry.html#zero_for-class_method" title="Mint::Registry.zero_for (method)">zero_for</a></span></span><span class='lparen'>(</span><span class='kw'>self</span><span class='rparen'>)</span></pre>
     </td>
@@ -1900,7 +1933,7 @@ for discounts, totals, or placeholders.</p>
 </div>
 
       <div id="footer">
-  Generated on Tue Jun 16 20:22:19 2026 by
+  Generated on Mon Jun 22 16:47:02 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>