minting 1.9.6 → 2.0.0

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 (64) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +244 -121
  3. data/Rakefile +17 -26
  4. data/bin/bench_check +2 -2
  5. data/doc/agents/api_review-2026-06-15.md +1 -1
  6. data/doc/agents/copilot-instructions.md +5 -5
  7. data/doc/agents/expired/copilot-instructions.md +2 -2
  8. data/doc/agents/expired/gemini_gem_evaluation.md +2 -2
  9. data/lib/minting/aliases.rb +22 -0
  10. data/lib/minting/currency/currency.rb +87 -12
  11. data/lib/minting/data/crypto-currencies.yaml +126 -0
  12. data/lib/minting/data/world-currencies.yaml +75 -23
  13. data/lib/minting/mint/i18n.rb +79 -29
  14. data/lib/minting/mint/mint.rb +1 -26
  15. data/lib/minting/mint/registry/crypto.rb +59 -0
  16. data/lib/minting/mint/registry/registration.rb +1 -2
  17. data/lib/minting/mint/registry/symbols.rb +37 -30
  18. data/lib/minting/mint/rounding.rb +10 -7
  19. data/lib/minting/mint.rb +1 -2
  20. data/lib/minting/money/allocation/allocation.rb +2 -2
  21. data/lib/minting/money/allocation/split.rb +1 -1
  22. data/lib/minting/money/arithmetics/operators.rb +10 -13
  23. data/lib/minting/money/clamp.rb +6 -6
  24. data/lib/minting/money/coercion.rb +1 -1
  25. data/lib/minting/money/comparable.rb +3 -3
  26. data/lib/minting/money/constructors.rb +3 -42
  27. data/lib/minting/money/conversion.rb +23 -18
  28. data/lib/minting/money/format/format.rb +100 -0
  29. data/lib/minting/money/format/formatter.rb +102 -0
  30. data/lib/minting/money/format/to_s.rb +34 -99
  31. data/lib/minting/money/format/validator.rb +34 -0
  32. data/lib/minting/money/money.rb +25 -13
  33. data/lib/minting/money/parse.rb +127 -0
  34. data/lib/minting/money/rounding.rb +27 -0
  35. data/lib/minting/version.rb +1 -1
  36. data/lib/minting.rb +17 -8
  37. metadata +9 -28
  38. data/doc/Mint/Currency.html +0 -1943
  39. data/doc/Mint/CurrencyRegistry.html +0 -511
  40. data/doc/Mint/Money.html +0 -4607
  41. data/doc/Mint/RangeStepPatch.html +0 -277
  42. data/doc/Mint/Registry.html +0 -863
  43. data/doc/Mint/Rounding.html +0 -506
  44. data/doc/Mint/UnknownCurrency.html +0 -136
  45. data/doc/Mint.html +0 -1004
  46. data/doc/Minting.html +0 -142
  47. data/doc/_index.html +0 -180
  48. data/doc/class_list.html +0 -54
  49. data/doc/css/common.css +0 -1
  50. data/doc/css/full_list.css +0 -206
  51. data/doc/css/style.css +0 -1089
  52. data/doc/file.README.html +0 -277
  53. data/doc/file_list.html +0 -59
  54. data/doc/frames.html +0 -22
  55. data/doc/index.html +0 -277
  56. data/doc/js/app.js +0 -801
  57. data/doc/js/full_list.js +0 -334
  58. data/doc/js/jquery.js +0 -4
  59. data/doc/method_list.html +0 -686
  60. data/doc/top-level-namespace.html +0 -151
  61. data/lib/minting/mint/aliases.rb +0 -16
  62. data/lib/minting/mint/parser/parser.rb +0 -97
  63. data/lib/minting/mint/parser/separators.rb +0 -41
  64. data/lib/minting/money/format/formatting.rb +0 -97
data/doc/index.html DELETED
@@ -1,277 +0,0 @@
1
- <!DOCTYPE html>
2
- <html>
3
- <head>
4
- <meta charset="UTF-8">
5
- <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
- <title>
7
- File: README
8
-
9
- &mdash; Documentation by YARD 0.9.44
10
-
11
- </title>
12
-
13
- <link rel="stylesheet" href="css/style.css" type="text/css">
14
-
15
- <link rel="stylesheet" href="css/common.css" type="text/css">
16
-
17
- <script type="text/javascript">
18
- pathId = "README";
19
- relpath = '';
20
- </script>
21
-
22
-
23
- <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
24
-
25
- <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
26
-
27
-
28
- </head>
29
- <body>
30
- <div id="main_progress" aria-hidden="true"></div>
31
-
32
- <div class="nav_wrap">
33
- <iframe id="nav" src="class_list.html?1"></iframe>
34
- <div id="resizer"></div>
35
- </div>
36
-
37
- <div id="main" tabindex="-1">
38
- <div id="header">
39
- <div id="menu">
40
-
41
- <a href="_index.html">Index</a> &raquo;
42
- <span class="title">File: README</span>
43
-
44
- </div>
45
-
46
- <div id="search">
47
-
48
- <a class="full_list_link" id="class_list_link"
49
- href="class_list.html">
50
-
51
- <svg width="24" height="24">
52
- <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
53
- <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
54
- <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
55
- </svg>
56
- </a>
57
-
58
- </div>
59
- <div class="clear"></div>
60
- </div>
61
-
62
- <div id="content"><div id='filecontents'><h1 id="Minting">Minting</h1>
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>
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
- <a href="https://www.rubydoc.info/gems/minting/frames"><img src="https://img.shields.io/badge/docs-rubydoc.info-blue" alt="Documentation" /></a></p>
68
- <h2 id="Quick_start">Quick start</h2>
69
- <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>
70
-
71
- <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'>19.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; [USD 19.99]
72
- </span><span class='id identifier rubyid_tax'>tax</span> <span class='op'>=</span> <span class='id identifier rubyid_price'>price</span> <span class='op'>*</span> <span class='float'>0.08</span> <span class='comment'>#=&gt; [USD 1.60]
73
- </span><span class='id identifier rubyid_total'>total</span> <span class='op'>=</span> <span class='id identifier rubyid_price'>price</span> <span class='op'>+</span> <span class='id identifier rubyid_tax'>tax</span> <span class='comment'>#=&gt; [USD 21.59]
74
- </span>
75
- <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;
76
- </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;
77
- </span></code></pre>
78
- <h3 id="Exact_precision">Exact precision</h3>
79
- <p>Amounts are stored as <code>Rational</code> and rounded to the currency subunit. No floating-point surprises, ever.</p>
80
- <h3 id="Blazing_performance">Blazing performance</h3>
81
- <p>Minting is faster 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>
82
- <h3 id="Clean__modern_API">Clean, modern API</h3>
83
- <p>Intuitive interface, descriptive error messages, and sensible defaults. Works the way you expect.</p>
84
- <h3 id="Rails_ready">Rails-ready</h3>
85
- <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>
86
- <h3 id="Quality_code">Quality code</h3>
87
- <ul>
88
- <li><strong>100% test coverage</strong> — every line exercised</li>
89
- <li><strong>94/100 RubyCritic score</strong> — clean, maintainable code</li>
90
- <li><strong>CI-tested on Ruby 3.3 and 4.0</strong></li>
91
- </ul>
92
- <h2 id="Installation">Installation</h2>
93
- <pre class="code shell"><code class="shell">bundle add minting
94
- </code></pre>
95
- <p>Or add to your Gemfile:</p>
96
- <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>
97
- </code></pre>
98
- <h2 id="Usage">Usage</h2>
99
- <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>
100
-
101
- <span class='comment'># Create money
102
- </span><span class='id identifier rubyid_ten'>ten</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'>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='comment'>#=&gt; [USD 10.00]
103
- </span>
104
- <span class='comment'># Create money using Numeric refinements
105
- </span><span class='id identifier rubyid_using'>using</span> <span class='const'><span class='object_link'><a href="Mint.html" title="Mint (module)">Mint</a></span></span>
106
-
107
- <span class='int'>1</span><span class='period'>.</span><span class='id identifier rubyid_dollar'>dollar</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'>1</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
108
- </span><span class='id identifier rubyid_ten'>ten</span> <span class='op'>=</span> <span class='int'>10</span><span class='period'>.</span><span class='id identifier rubyid_dollars'>dollars</span> <span class='comment'>#=&gt; [USD 10.00]
109
- </span><span class='int'>4</span><span class='period'>.</span><span class='id identifier rubyid_to_money'>to_money</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; [USD 4.00]
110
- </span>
111
- <span class='comment'># Comparisons
112
- </span><span class='id identifier rubyid_ten'>ten</span> <span class='op'>==</span> <span class='int'>10</span><span class='period'>.</span><span class='id identifier rubyid_dollars'>dollars</span> <span class='comment'>#=&gt; true
113
- </span><span class='id identifier rubyid_ten'>ten</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'>10</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; false
114
- </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
115
- </span>
116
- <span class='comment'># Zero equality semantics
117
- </span><span class='comment'># Any zero amount is treated as equal, regardless of currency
118
- </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
119
- </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
120
- </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
121
- </span>
122
- <span class='comment'># Non-zero numerics are not equal to Money objects
123
- </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
124
- </span>
125
- <span class='comment'># Format (uses Kernel.format syntax)
126
- </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>
127
-
128
- <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;,
129
- </span><span class='id identifier rubyid_price'>price</span><span class='period'>.</span><span class='id identifier rubyid_to_s'>to_s</span><span class='lparen'>(</span><span class='label'>format:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>%&lt;amount&gt;d</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span> <span class='comment'>#=&gt; &quot;9&quot;,
130
- </span><span class='id identifier rubyid_price'>price</span><span class='period'>.</span><span class='id identifier rubyid_to_s'>to_s</span><span class='lparen'>(</span><span class='label'>format:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>%&lt;symbol&gt;s%&lt;amount&gt;f</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span> <span class='comment'>#=&gt; &quot;$9.99&quot;,
131
- </span><span class='id identifier rubyid_price'>price</span><span class='period'>.</span><span class='id identifier rubyid_to_s'>to_s</span><span class='lparen'>(</span><span class='label'>format:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>%&lt;symbol&gt;s%&lt;amount&gt;+f</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span> <span class='comment'>#=&gt; &quot;$+9.99&quot;,
132
- </span><span class='lparen'>(</span><span class='op'>-</span><span class='id identifier rubyid_price'>price</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_to_s'>to_s</span><span class='lparen'>(</span><span class='label'>format:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>%&lt;amount&gt;f</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span> <span class='comment'>#=&gt; &quot;-9.99&quot;,
133
- </span>
134
- <span class='comment'># Format with padding
135
- </span><span class='id identifier rubyid_price_in_euros'>price_in_euros</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'>12.34</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>
136
-
137
- <span class='id identifier rubyid_price'>price</span><span class='period'>.</span><span class='id identifier rubyid_to_s'>to_s</span><span class='lparen'>(</span><span class='label'>format:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>--%&lt;amount&gt;7d</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span> <span class='comment'>#=&gt; &quot;-- 9&quot;
138
- </span><span class='id identifier rubyid_price'>price</span><span class='period'>.</span><span class='id identifier rubyid_to_s'>to_s</span><span class='lparen'>(</span><span class='label'>format:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'> %&lt;amount&gt;10f %&lt;currency&gt;s</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span> <span class='comment'>#=&gt; &quot; 9.99 USD&quot;
139
- </span><span class='lparen'>(</span><span class='op'>-</span><span class='id identifier rubyid_price'>price</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_to_s'>to_s</span><span class='lparen'>(</span><span class='label'>format:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'> %&lt;amount&gt;10f</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span> <span class='comment'>#=&gt; &quot; -9.99&quot;
140
- </span>
141
- <span class='id identifier rubyid_price_in_euros'>price_in_euros</span><span class='period'>.</span><span class='id identifier rubyid_to_s'>to_s</span><span class='lparen'>(</span><span class='label'>format:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>%&lt;symbol&gt;2s%&lt;amount&gt;+10f</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span> <span class='comment'>#=&gt; &quot; € +12.34&quot;
142
- </span>
143
- <span class='comment'># Integral &amp; fractional parts
144
- </span><span class='id identifier rubyid_price'>price</span><span class='period'>.</span><span class='id identifier rubyid_to_s'>to_s</span><span class='lparen'>(</span><span class='label'>format:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>%&lt;integral&gt;d %&lt;fractional&gt;d/100</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span> <span class='comment'>#=&gt; &quot;9 99/100&quot;
145
- </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'>0.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='period'>.</span><span class='id identifier rubyid_to_s'><span class='object_link'><a href="Mint/Money.html#to_s-instance_method" title="Mint::Money#to_s (method)">to_s</a></span></span><span class='lparen'>(</span><span class='label'>format:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>%&lt;integral&gt;d dollars and %&lt;fractional&gt;02d cents</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
146
- <span class='comment'>#=&gt; &quot;0 dollars and 99 cents&quot;
147
- </span>
148
- <span class='comment'># Per-sign Hash format (e.g. accounting parentheses for losses)
149
- </span><span class='id identifier rubyid_loss'>loss</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='op'>-</span><span class='float'>1234.56</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>
150
- <span class='id identifier rubyid_loss'>loss</span><span class='period'>.</span><span class='id identifier rubyid_to_s'>to_s</span><span class='lparen'>(</span><span class='label'>format:</span> <span class='lbrace'>{</span> <span class='label'>negative:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>(%&lt;symbol&gt;s%&lt;amount&gt;f)</span><span class='tstring_end'>&#39;</span></span> <span class='rbrace'>}</span><span class='rparen'>)</span> <span class='comment'>#=&gt; &quot;($1,234.56)&quot;
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'>BRL</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_to_s'><span class='object_link'><a href="Mint/Money.html#to_s-instance_method" title="Mint::Money#to_s (method)">to_s</a></span></span><span class='lparen'>(</span><span class='label'>format:</span> <span class='lbrace'>{</span> <span class='label'>zero:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>--</span><span class='tstring_end'>&#39;</span></span> <span class='rbrace'>}</span><span class='rparen'>)</span> <span class='comment'>#=&gt; &quot;--&quot;
152
- </span><span class='comment'># All three keys at once:
153
- </span><span class='id identifier rubyid_fmt'>fmt</span> <span class='op'>=</span> <span class='lbrace'>{</span> <span class='label'>positive:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>%&lt;symbol&gt;s%&lt;amount&gt;f</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span> <span class='label'>negative:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>(%&lt;symbol&gt;s%&lt;amount&gt;f)</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span> <span class='label'>zero:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>--</span><span class='tstring_end'>&#39;</span></span> <span class='rbrace'>}</span>
154
- <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'>1234.56</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='period'>.</span><span class='id identifier rubyid_to_s'><span class='object_link'><a href="Mint/Money.html#to_s-instance_method" title="Mint::Money#to_s (method)">to_s</a></span></span><span class='lparen'>(</span><span class='label'>format:</span> <span class='id identifier rubyid_fmt'>fmt</span><span class='rparen'>)</span> <span class='comment'>#=&gt; &quot;$1,234.56&quot;
155
- </span>
156
- <span class='comment'># Json serialization
157
- </span>
158
- <span class='id identifier rubyid_price'>price</span><span class='period'>.</span><span class='id identifier rubyid_to_json'>to_json</span> <span class='comment'># =&gt; &quot;{\&quot;currency\&quot;: \&quot;USD\&quot;, \&quot;amount\&quot;: \&quot;9.99\&quot;}&quot;
159
- </span>
160
- <span class='comment'># Hash conversion
161
- </span>
162
- <span class='id identifier rubyid_price'>price</span><span class='period'>.</span><span class='id identifier rubyid_to_hash'>to_hash</span> <span class='comment'>#=&gt; {currency: &quot;USD&quot;, amount: &quot;9.99&quot;}
163
- </span>
164
-
165
- <span class='comment'># Fractional units (inverse of #fractional) - exact integer arithmetic
166
- </span>
167
- <span class='id identifier rubyid_price'>price</span><span class='period'>.</span><span class='id identifier rubyid_subunits'>subunits</span> <span class='comment'>#=&gt; 999
168
- </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_from_subunits'><span class='object_link'><a href="Mint/Money.html#from_subunits-class_method" title="Mint::Money.from_subunits (method)">from_subunits</a></span></span><span class='lparen'>(</span><span class='int'>999</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; [USD 9.99]
169
- </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_from_subunits'><span class='object_link'><a href="Mint/Money.html#from_subunits-class_method" title="Mint::Money.from_subunits (method)">from_subunits</a></span></span><span class='lparen'>(</span><span class='int'>1234</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>JPY</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span> <span class='comment'>#=&gt; [JPY 1234] # subunit 0 -&gt; no scaling
170
- </span>
171
-
172
- <span class='comment'># No currency (ISO 4217 XXX)
173
- </span>
174
- <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_no_currency'><span class='object_link'><a href="Mint/Money.html#no_currency-class_method" title="Mint::Money.no_currency (method)">no_currency</a></span></span><span class='lparen'>(</span><span class='int'>100</span><span class='rparen'>)</span> <span class='comment'>#=&gt; [XXX 100]
175
- </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_no_currency'><span class='object_link'><a href="Mint/Money.html#no_currency-class_method" title="Mint::Money.no_currency (method)">no_currency</a></span></span><span class='lparen'>(</span><span class='int'>0</span><span class='rparen'>)</span> <span class='comment'>#=&gt; [XXX 0]
176
- </span>
177
-
178
- <span class='comment'># Proportional allocation and split
179
- </span>
180
- <span class='id identifier rubyid_ten'>ten</span><span class='period'>.</span><span class='id identifier rubyid_split'>split</span><span class='lparen'>(</span><span class='int'>3</span><span class='rparen'>)</span> <span class='comment'>#=&gt; [[USD 3.34], [USD 3.33], [USD 3.33]]
181
- </span><span class='id identifier rubyid_ten'>ten</span><span class='period'>.</span><span class='id identifier rubyid_allocate'>allocate</span><span class='lparen'>(</span><span class='lbracket'>[</span><span class='int'>1</span><span class='comma'>,</span> <span class='int'>2</span><span class='comma'>,</span> <span class='int'>3</span><span class='rbracket'>]</span><span class='rparen'>)</span> <span class='comment'>#=&gt; [[USD 1.67], [USD 3.33], [USD 5.00]]
182
- </span>
183
- <span class='comment'># Clamping to a range
184
- </span>
185
- <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='int'>50</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>
186
- <span class='id identifier rubyid_min_price'>min_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='int'>75</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>
187
-
188
- <span class='id identifier rubyid_price'>price</span><span class='period'>.</span><span class='id identifier rubyid_clamp'>clamp</span><span class='lparen'>(</span><span class='int'>0</span><span class='comma'>,</span> <span class='int'>100</span><span class='rparen'>)</span> <span class='comment'>#=&gt; [USD 50.00] (returns self, no new object)
189
- </span><span class='id identifier rubyid_price'>price</span><span class='period'>.</span><span class='id identifier rubyid_clamp'>clamp</span><span class='lparen'>(</span><span class='int'>0</span><span class='comma'>,</span> <span class='int'>25</span><span class='rparen'>)</span> <span class='comment'>#=&gt; [USD 25.00] (clamped to max)
190
- </span><span class='id identifier rubyid_price'>price</span><span class='period'>.</span><span class='id identifier rubyid_clamp'>clamp</span><span class='lparen'>(</span><span class='id identifier rubyid_min_price'>min_price</span><span class='comma'>,</span> <span class='int'>100</span><span class='rparen'>)</span> <span class='comment'>#=&gt; [USD 75.00] (clamped to min)
191
- </span>
192
- <span class='comment'># Clamp accepts Money bounds or Numeric amounts
193
- </span><span class='id identifier rubyid_price'>price</span><span class='period'>.</span><span class='id identifier rubyid_clamp'>clamp</span><span class='lparen'>(</span><span class='id identifier rubyid_min_price'>min_price</span><span class='comma'>,</span> <span class='int'>100</span><span class='rparen'>)</span> <span class='comment'>#=&gt; [USD 75.00]
194
- </span>
195
- <span class='comment'># Ranges and enumeration are supported
196
- </span>
197
- <span class='int'>1</span><span class='period'>.</span><span class='id identifier rubyid_dollar'>dollar</span><span class='op'>..</span><span class='int'>10</span><span class='period'>.</span><span class='id identifier rubyid_dollars'>dollars</span> <span class='comment'>#=&gt; [USD 1.00]..[USD 10.00]
198
- </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]]
199
- </span>
200
- </code></pre>
201
- <h2 id="Parsing_strings">Parsing strings</h2>
202
- <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]
203
- </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]
204
- </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]
205
- </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]
206
- </span></code></pre>
207
- <p>Notes:</p>
208
- <ul>
209
- <li>Pass a currency code when the string has no symbol or code.</li>
210
- <li><code>1,234</code> means 1234, not 1.234 and <code>1,23</code> means 1.23, not 123</li>
211
- <li><code>1,234.00</code> is unambiguous (thousands + decimal).</li>
212
- <li>Accounting negatives like <code>($1.23)</code> or <code>(USD 10.00)</code> are supported — the parser detects parentheses and negates the amount.</li>
213
- <li>Ambiguous symbols like <code>$</code> resolve by currency priority (currently USD).</li>
214
- <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>
215
- </ul>
216
- <h2 id="Currency_lookup">Currency lookup</h2>
217
- <pre class="code ruby"><code class="ruby"><span class='comment'># By ISO code (direct hash lookup, string only)
218
- </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;
219
- </span>
220
- <span class='comment'># By display symbol (highest-priority currency for ambiguous symbols)
221
- </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;
222
- </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;
223
- </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;
224
- </span>
225
- </code></pre>
226
- <h2 id="API_notes">API notes</h2>
227
- <p><strong>Exact amounts</strong> — Amounts are stored as <code>Rational</code> and rounded to the currency subunit.</p>
228
- <p><strong>Rounding modes</strong> — Wrap operations in <code>Mint.with_rounding(mode)</code> to change how amounts are rounded to the subunit:</p>
229
- <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]
230
- </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]
231
- </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]
232
- </span></code></pre>
233
- <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>
234
- <blockquote>
235
- <p><strong>Performance note:</strong> Rounding-mode support is not loaded by default — <code>require 'minting'</code> uses the fastest possible rounding (equivalent to <code>:half_up</code>) with zero dispatch overhead. The first call to <code>Mint.with_rounding</code> loads the rounding module and patches <code>Currency#normalize_amount</code>, adding ~10–35 ns per money creation or mutation. If your application never uses custom rounding modes (the common case), there is <strong>no performance cost</strong>.</p>
236
- </blockquote>
237
- <p><strong>Refinements</strong> — <code>10.dollars</code> and similar helpers require <code>using Mint</code> in the current scope (see Usage above).</p>
238
- <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>
239
- <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>
240
- <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>
241
- <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 or searches. Nonetheless, you don't need to register a currency to use it with most of the features.</p>
242
- <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>
243
- <h2 id="Optional_top_level__Money__and__Currency_">Optional top-level <code>Money</code> and <code>Currency</code></h2>
244
- <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>
245
- <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>
246
- <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
247
- </span></code></pre>
248
- <p>Or at runtime:</p>
249
- <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>
250
- </code></pre>
251
- <p>For Rails applications, you can enable the top-level constants in an initializer:</p>
252
- <pre class="code ruby"><code class="ruby"><span class='comment'># config/initializers/minting.rb
253
- </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>
254
- </code></pre>
255
- <p>After opting in:</p>
256
- <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
257
- </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>
258
- <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>
259
- </code></pre>
260
- <p><strong>Good fit:</strong> Application code, especially Rails apps.
261
- <strong>Not recommended:</strong> Reusable gems/libraries — stick to <code>Mint::Money</code> to avoid conflicts.</p>
262
- <h2 id="Roadmap">Roadmap</h2>
263
- <ul>
264
- <li>Exchange-rate conversion infrastructure</li>
265
- </ul>
266
- <h2 id="License">License</h2>
267
- <p>MIT</p></div></div>
268
-
269
- <div id="footer">
270
- Generated on Mon Jun 22 16:47:01 2026 by
271
- <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
272
- 0.9.44 (ruby-4.0.5).
273
- </div>
274
-
275
- </div>
276
- </body>
277
- </html>