minting 1.7.0 → 1.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +71 -118
  3. data/Rakefile +13 -1
  4. data/bin/bench_check +46 -0
  5. data/doc/Mint/Currency.html +178 -32
  6. data/doc/Mint/CurrencyRegistry.html +7 -7
  7. data/doc/Mint/Money.html +128 -125
  8. data/doc/Mint/RangeStepPatch.html +277 -0
  9. data/doc/Mint/UnknownCurrency.html +2 -2
  10. data/doc/Mint.html +47 -22
  11. data/doc/Minting.html +3 -3
  12. data/doc/_index.html +17 -2
  13. data/doc/class_list.html +1 -1
  14. data/doc/file.README.html +86 -89
  15. data/doc/index.html +86 -89
  16. data/doc/method_list.html +29 -21
  17. data/doc/top-level-namespace.html +13 -5
  18. data/lib/minting/{mint/currency → currency}/currency.rb +8 -0
  19. data/lib/minting/{mint/currency → currency}/world_currencies.rb +1 -1
  20. data/lib/minting/mint/aliases.rb +3 -0
  21. data/lib/minting/mint/dsl/{refinements.rb → numeric.rb} +6 -5
  22. data/lib/minting/mint/dsl/range.rb +31 -18
  23. data/lib/minting/mint/dsl/string.rb +12 -0
  24. data/lib/minting/mint/dsl/top_level.rb +3 -0
  25. data/lib/minting/mint/mint.rb +16 -2
  26. data/lib/minting/mint/parser/parser.rb +66 -0
  27. data/lib/minting/mint/parser/separators.rb +39 -0
  28. data/lib/minting/mint.rb +17 -8
  29. data/lib/minting/money/allocation/allocation.rb +25 -0
  30. data/lib/minting/money/{allocation.rb → allocation/split.rb} +1 -19
  31. data/lib/minting/money/arithmetics/methods.rb +27 -0
  32. data/lib/minting/money/{arithmetics.rb → arithmetics/operators.rb} +0 -21
  33. data/lib/minting/money/clamp.rb +66 -0
  34. data/lib/minting/money/coercion.rb +10 -0
  35. data/lib/minting/money/comparable.rb +6 -0
  36. data/lib/minting/money/constructors.rb +13 -3
  37. data/lib/minting/money/format/formatting.rb +44 -0
  38. data/lib/minting/money/{formatting.rb → format/to_s.rb} +0 -32
  39. data/lib/minting/money/money.rb +0 -58
  40. data/lib/minting/version.rb +1 -1
  41. metadata +19 -14
  42. data/lib/minting/mint/parser.rb +0 -85
  43. /data/lib/minting/{mint/currency → currency}/currency_registry.rb +0 -0
data/doc/file.README.html CHANGED
@@ -61,13 +61,11 @@
61
61
 
62
62
  <div id="content"><div id='filecontents'><h1 id="Minting">Minting</h1>
63
63
  <p>Fast, precise, and developer-friendly money handling for Ruby.</p>
64
- <p><a href="https://badge.fury.io/rb/minting"><img src="https://badge.fury.io/rb/minting.svg" alt="Gem Version" /></a></p>
65
- <h2 id="Why_Minting_">Why Minting?</h2>
66
- <p><strong>Tired of floating-point errors in financial calculations?</strong> Minting uses Rational numbers for perfect precision.</p>
67
- <p><strong>Need performance?</strong> Minting is 2× faster than alternatives for high-volume operations (often 10×+ for formatting). See the <a href="https://github.com/gferraz/minting/blob/master/test/performance/README.md">Performance</a> section for full benchmarks.</p>
68
- <p><strong>Want a clean API?</strong> Minting provides an intuitive interface with helpful error messages.</p>
69
- <p><strong>Looking for a proven alternative?</strong> Check out the established <a href="https://github.com/RubyMoney/money">Money gem</a> with thousands of stars on GitHub.</p>
70
- <p><strong>Rails</strong>? Use the <a href="https://github.com/gferraz/minting-rails">minting-rails</a> companion gem</p>
64
+ <p><a href="https://badge.fury.io/rb/minting"><img src="https://badge.fury.io/rb/minting.svg" alt="Gem Version" /></a>
65
+ <a href="https://github.com/gferraz/minting/actions/workflows/ci.yml"><img src="https://github.com/gferraz/minting/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
66
+ <a href="https://github.com/gferraz/minting"><img src="https://img.shields.io/badge/coverage-100%25-brightgreen" alt="Test Coverage" /></a>
67
+ [![RubyCritic](<a href="https://img.shields.io/badge/RubyCritic-94gem">https://img.shields.io/badge/RubyCritic-94gem</a> /100-brightgreen)](<a href="https://github.com/gferraz/minting">https://github.com/gferraz/minting</a>)
68
+ <a href="https://www.rubydoc.info/gems/minting/frames"><img src="https://img.shields.io/badge/docs-rubydoc.info-blue" alt="Documentation" /></a></p>
71
69
  <h2 id="Quick_start">Quick start</h2>
72
70
  <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>minting</span><span class='tstring_end'>&#39;</span></span>
73
71
 
@@ -78,17 +76,57 @@
78
76
  <span class='id identifier rubyid_total'>total</span><span class='period'>.</span><span class='id identifier rubyid_to_s'>to_s</span> <span class='comment'>#=&gt; &quot;$21.59&quot;
79
77
  </span><span class='id identifier rubyid_total'>total</span><span class='period'>.</span><span class='id identifier rubyid_currency_code'>currency_code</span> <span class='comment'>#=&gt; &quot;USD&quot;
80
78
  </span></code></pre>
81
- <h2 id="Features">Features</h2>
79
+ <h2 id="Why_Minting_">Why Minting?</h2>
80
+ <table>
81
+ <thead>
82
+ <tr>
83
+ <th></th>
84
+ <th>Minting</th>
85
+ </tr>
86
+ </thead>
87
+ <tbody>
88
+ <tr>
89
+ <td><strong>Precision</strong></td>
90
+ <td>Rational-based, zero floating-point error</td>
91
+ </tr>
92
+ <tr>
93
+ <td><strong>Performance</strong></td>
94
+ <td><strong>2× faster</strong> (10×+ formatting)</td>
95
+ </tr>
96
+ <tr>
97
+ <td><strong>Ruby support</strong></td>
98
+ <td>3.3+ (including Ruby 4.0)</td>
99
+ </tr>
100
+ <tr>
101
+ <td><strong>Rails</strong></td>
102
+ <td>Dedicated companion gem</td>
103
+ </tr>
104
+ <tr>
105
+ <td><strong>Code quality</strong></td>
106
+ <td>100% coverage, 93/100 RubyCritic</td>
107
+ </tr>
108
+ </tbody>
109
+ </table>
110
+ <h3 id="__Exact_precision">🎯 Exact precision</h3>
111
+ <p>Amounts are stored as <code>Rational</code> and rounded to the currency subunit. No floating-point surprises, ever.</p>
112
+ <h3 id="__Blazing_performance">⚡ Blazing performance</h3>
113
+ <p>Minting is <strong>2× faster</strong> than the Money gem for everyday operations and <strong>over 10× faster for formatting</strong>. See full benchmarks in the <a href="test/performance/README.md">Performance Guide</a>.</p>
114
+ <h3 id="__Clean__modern_API">🧼 Clean, modern API</h3>
115
+ <p>Intuitive interface, descriptive error messages, and sensible defaults. Works the way you expect.</p>
116
+ <h3 id="__Rails_ready">🚆 Rails-ready</h3>
117
+ <p>Use with the <a href="https://github.com/gferraz/minting-rails">minting-rails</a> companion gem for drop-in ActiveRecord type casting, validators, and form helpers.</p>
118
+ <h3 id="__Quality_you_can_trust">🏆 Quality you can trust</h3>
82
119
  <ul>
83
- <li>Arithmetic: <code>+ - * /</code>, unary minus, <code>abs</code></li>
84
- <li>Comparisons: <code>==</code>, <code>&lt;=&gt;</code>, <code>zero?</code>, <code>nonzero?</code>, <code>positive?</code>, <code>negative?</code></li>
85
- <li>Formatting: <code>to_s</code> with custom formats, thousand delimiters and decimal separators</li>
86
- <li>Serialization: <code>to_json</code>, <code>to_i</code>, <code>to_f</code>, <code>to_r</code>, <code>to_d</code></li>
87
- <li>Allocation utilities: <code>split(quantity)</code>, <code>allocate([ratios])</code>,</li>
88
- <li>Utilities: <code>clamp(min, max)</code></li>
89
- <li>Numeric Refinements for ergonomics: <code>10.dollars</code>, <code>3.euros</code>, <code>4.to_money('USD')</code></li>
90
- <li>Currency registry with 117+ currencies and custom registration</li>
120
+ <li><strong>100% test coverage</strong> — every line exercised</li>
121
+ <li><strong>93/100 RubyCritic score</strong> — clean, maintainable code</li>
122
+ <li><strong>CI-tested on Ruby 3.3 and 4.0</strong></li>
91
123
  </ul>
124
+ <h2 id="Installation">Installation</h2>
125
+ <pre class="code shell"><code class="shell">bundle add minting
126
+ </code></pre>
127
+ <p>Or add to your Gemfile:</p>
128
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_gem'>gem</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>minting</span><span class='tstring_end'>&#39;</span></span>
129
+ </code></pre>
92
130
  <h2 id="Usage">Usage</h2>
93
131
  <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>minting</span><span class='tstring_end'>&#39;</span></span>
94
132
 
@@ -108,16 +146,15 @@
108
146
  </span><span class='id identifier rubyid_ten'>ten</span> <span class='op'>&gt;</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'>9.99</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='comment'>#=&gt; true
109
147
  </span>
110
148
  <span class='comment'># Zero equality semantics
111
- </span><span class='comment'># Any zero amount is treated as equal, regardless of currency
112
- </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='int'>0</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='op'>==</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='int'>0</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>EUR</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span> <span class='comment'>#=&gt; true
149
+ </span><span class='comment'># Any zero amount is treated as equal, regardless of currency
150
+ </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='int'>0</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='op'>==</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='int'>0</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>EUR</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span> <span class='comment'>#=&gt; true
113
151
  </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='int'>0</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='op'>==</span> <span class='int'>0</span> <span class='comment'>#=&gt; true
114
152
  </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='int'>0</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='op'>==</span> <span class='float'>0.0</span> <span class='comment'>#=&gt; true
115
- </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='int'>0</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='op'>==</span> <span class='rational'>0r</span> <span class='comment'>#=&gt; true
116
153
  </span>
117
154
  <span class='comment'># Non-zero numerics are not equal to Money objects
118
155
  </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='int'>10</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='op'>==</span> <span class='int'>10</span> <span class='comment'>#=&gt; false
119
156
  </span>
120
- <span class='comment'># Format (uses Kernel.format internally)
157
+ <span class='comment'># Format (uses Kernel.format syntax)
121
158
  </span><span class='id identifier rubyid_price'>price</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='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'>9.99</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>
122
159
 
123
160
  <span class='id identifier rubyid_price'>price</span><span class='period'>.</span><span class='id identifier rubyid_to_s'>to_s</span> <span class='comment'>#=&gt; &quot;$9.99&quot;,
@@ -182,95 +219,55 @@
182
219
  </span><span class='lparen'>(</span><span class='int'>1</span><span class='period'>.</span><span class='id identifier rubyid_dollar'>dollar</span><span class='op'>..</span><span class='int'>3</span><span class='period'>.</span><span class='id identifier rubyid_dollars'>dollars</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_step'>step</span><span class='lparen'>(</span><span class='int'>1</span><span class='period'>.</span><span class='id identifier rubyid_dollar'>dollar</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_to_a'>to_a</span> <span class='comment'>#=&gt; [[USD 1.00], [USD 2.00], [USD 3.00]]
183
220
  </span>
184
221
  </code></pre>
222
+ <h2 id="Parsing_strings">Parsing strings</h2>
223
+ <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_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'>$19.99</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span> <span class='comment'>#=&gt; [USD 19.99]
224
+ </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'>19,99 €</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span> <span class='comment'>#=&gt; [EUR 19.99]
225
+ </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.234,56</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'>EUR</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span> <span class='comment'>#=&gt; [EUR 1234.56]
226
+ </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'>USD 1,234.56</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span> <span class='comment'>#=&gt; [USD 1234.56]
227
+ </span></code></pre>
228
+ <p>Notes:</p>
229
+ <ul>
230
+ <li>Pass a currency code when the string has no symbol or code.</li>
231
+ <li><code>1,234</code> means 1234, not 1.234 and <code>1,23</code> means 1.23, not 123</li>
232
+ <li><code>1,234.00</code> is unambiguous (thousands + decimal).</li>
233
+ <li>Accounting negatives like <code>($1.23)</code> are unsupported for now.</li>
234
+ <li>Ambiguous symbols like <code>$</code> resolve by currency priority (currently USD).</li>
235
+ <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>
236
+ </ul>
185
237
  <h2 id="API_notes">API notes</h2>
186
- <p><strong>Module names</strong> — Require the <code>minting</code> gem; the public API lives under <code>Mint</code>.</p>
187
238
  <p><strong>Exact amounts</strong> — Amounts are stored as <code>Rational</code> and rounded to the currency subunit.</p>
188
239
  <p><strong>Refinements</strong> — <code>10.dollars</code> and similar helpers require <code>using Mint</code> in the current scope (see Usage above).</p>
189
240
  <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>
190
- <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>
191
- <p><strong>Custom currencies</strong> — <code>Mint.register_currency</code>, Only registered currency codes and symbolos are recoginized by the parser.</p>
192
- <p><strong>Built-in currencies</strong> — ISO-style codes ship in <code>lib/minting/data/currencies.yaml</code> and load when the registry is first accessed.</p>
193
- <h2 id="Installation">Installation</h2>
194
- <p>Option 1: Via bundler command</p>
195
- <pre class="code shell"><code class="shell">bundle add minting
196
- bundle install
197
- </code></pre>
198
- <p>Option 2: add the line below to your application's Gemfile:</p>
199
- <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_gem'>gem</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>minting</span><span class='tstring_end'>&#39;</span></span>
200
- </code></pre>
201
- <p>or, if you want latest development version from Github</p>
202
- <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_gem'>gem</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>minting</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span> <span class='label'>git:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>https://github.com/gferraz/minting.git</span><span class='tstring_end'>&#39;</span></span>
203
- </code></pre>
204
- <p>and execute:</p>
205
- <pre class="code shell"><code class="shell">bundle install
206
- </code></pre>
207
- <p>Option 3: Install it yourself with:</p>
208
- <pre class="code shell"><code class="shell">gem install minting
209
- </code></pre>
210
- <h2 id="Configuration">Configuration</h2>
211
- <h3 id="Optional_top_level__Money__and__Currency_">Optional top‑level <code>Money</code> and <code>Currency</code></h3>
212
- <p>By default, Minting keeps everything namespaced under <code>Mint</code>:</p>
213
- <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="Mint.html" title="Mint (module)">Mint</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Mint/Money.html" title="Mint::Money (class)">Money</a></span></span><span class='period'>.</span><span class='id identifier rubyid_create'><span class='object_link'><a href="Mint/Money.html#create-class_method" title="Mint::Money.create (method)">create</a></span></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>
214
- <span class='id identifier rubyid_currency'>currency</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="Mint/Currency.html" title="Mint::Currency (class)">Currency</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="Mint/Currency.html#initialize-instance_method" title="Mint::Currency#initialize (method)">new</a></span></span><span class='lparen'>(</span><span class='label'>code:</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='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>
215
- </code></pre>
216
- <p>To avoid polluting the global namespace (and to coexist nicely with other gems), <strong>Minting dont automatically defines <code>Money</code> or <code>Currency</code> at the top level automatically</strong>.</p>
217
- <p>If you prefer the shorter <code>Money</code> / <code>Currency</code> constants in your application code, you can opt in explicitly.</p>
218
- <p>There are two ways to enable shorter constants:</p>
219
- <ol>
220
- <li>Require dsl in your app</li>
221
- </ol>
241
+ <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>
242
+ <p><strong>Registered currencies</strong> — <code>Mint.register_currency</code>. Only registered currency codes and symbols are recognized by the parser.</p>
243
+ <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>
244
+ <h2 id="Optional_top_level__Money__and__Currency_">Optional top-level <code>Money</code> and <code>Currency</code></h2>
245
+ <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>
222
246
  <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>minting</span><span class='tstring_end'>&quot;</span></span>
223
247
  <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> <span class='comment'># opt‑in top‑level Money / Currency
224
248
  </span></code></pre>
225
- <ol start="2">
226
- <li>Call a configuration method</li>
227
- </ol>
249
+ <p>Or at runtime:</p>
228
250
  <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>
229
251
  </code></pre>
230
- <p>After this, you can use:</p>
252
+ <p>After opting in:</p>
231
253
  <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
232
- </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> <span class='comment'># via Mint.money, still available
233
- </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>
254
+ </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>
255
+ <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>
234
256
  </code></pre>
235
- <h4 id="When_to_use_this">When to use this</h4>
236
- <ul>
237
- <li><strong>Good fit:</strong> application code, especially in Rails apps, where <code>Money</code> reads nicely in models and views.</li>
238
- <li><strong>Not recommended:</strong> reusable gems/libraries. In that case, stick to the namespaced API (<code>Mint::Money</code>, <code>Mint::Currency</code>) to avoid conflicts with other libraries.</li>
239
- </ul>
240
- <h2 id="Parsing_strings">Parsing strings</h2>
241
- <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_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'>$19.99</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span> <span class='comment'>#=&gt; [USD 19.99]
242
- </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'>19,99 €</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span> <span class='comment'>#=&gt; [EUR 19.99]
243
- </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.234,56</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'>EUR</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span> <span class='comment'>#=&gt; [EUR 1234.56]
244
- </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'>USD 1,234.56</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span> <span class='comment'>#=&gt; [USD 1234.56]
245
- </span></code></pre>
246
- <ul>
247
- <li>Pass a currency code when the string has no symbol or code.</li>
248
- <li>1,234 means 1.234, not 1234, because one comma is treated as decimal.</li>
249
- <li>1,234.00 is unambiguous thousands-plus-decimal.</li>
250
- <li>accounting negatives like ($1.23) are unsupported.</li>
251
- <li>ambiguous symbols like $ resolve by priority, currently USD.</li>
252
- </ul>
257
+ <p><strong>Good fit:</strong> Application code, especially Rails apps.
258
+ <strong>Not recommended:</strong> Reusable gems/libraries — stick to <code>Mint::Money</code> to avoid conflicts.</p>
253
259
  <h2 id="Roadmap">Roadmap</h2>
254
260
  <ul>
255
- <li>Improve formatting features</li>
256
261
  <li>Localization (I18n-aware formatting)</li>
257
- <li>Basic exchange-rate conversions</li>
262
+ <li>Exchange-rate conversion infrastructure</li>
258
263
  </ul>
259
- <h2 id="Contributing">Contributing</h2>
260
- <p>Bug reports and pull requests are welcome on GitHub at <a href="https://github.com/gferraz/minting">https://github.com/gferraz/minting</a>.</p>
261
- <ol>
262
- <li>Fork and create a feature branch</li>
263
- <li>Run the test suite: <code>rake</code></li>
264
- <li>Run performance suites as needed: <code>rake bench:performance</code></li>
265
- <li>Open a PR with a clear description and benchmarks if relevant</li>
266
- </ol>
267
264
  <h2 id="License">License</h2>
268
265
  <p>MIT</p></div></div>
269
266
 
270
267
  <div id="footer">
271
- Generated on Wed Jun 10 01:35:30 2026 by
268
+ Generated on Sun Jun 14 21:57:00 2026 by
272
269
  <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
273
- 0.9.44 (ruby-4.0.1).
270
+ 0.9.44 (ruby-4.0.5).
274
271
  </div>
275
272
 
276
273
  </div>