minting 1.3.0 → 1.4.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 (33) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +17 -2
  3. data/Rakefile +3 -3
  4. data/doc/Mint/Currency.html +816 -0
  5. data/doc/Mint/Money.html +3471 -0
  6. data/doc/Mint.html +953 -0
  7. data/doc/Minting.html +142 -0
  8. data/doc/_index.html +136 -0
  9. data/doc/agents/AGENTS.md +25 -0
  10. data/doc/agents/copilot-instructions.md +75 -0
  11. data/doc/agents/gemini_gem_evaluation.md +245 -0
  12. data/doc/agents/recommendations.md +335 -0
  13. data/doc/class_list.html +54 -0
  14. data/doc/css/common.css +1 -0
  15. data/doc/css/full_list.css +206 -0
  16. data/doc/css/style.css +1089 -0
  17. data/doc/file.README.html +379 -0
  18. data/doc/file_list.html +59 -0
  19. data/doc/frames.html +22 -0
  20. data/doc/index.html +379 -0
  21. data/doc/js/app.js +801 -0
  22. data/doc/js/full_list.js +334 -0
  23. data/doc/js/jquery.js +4 -0
  24. data/doc/method_list.html +470 -0
  25. data/doc/top-level-namespace.html +112 -0
  26. data/lib/minting/mint/currency.rb +1 -1
  27. data/lib/minting/mint/registry.rb +9 -18
  28. data/lib/minting/money/conversion.rb +5 -16
  29. data/lib/minting/money/formatting.rb +34 -1
  30. data/lib/minting/money/money.rb +83 -5
  31. data/lib/minting/version.rb +1 -1
  32. data/minting.gemspec +1 -0
  33. metadata +38 -2
data/doc/file.README.html ADDED
@@ -0,0 +1,379 @@
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="file_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></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 2x faster than alternatives.</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>
71
+ <h2 id="Quick_start">Quick start</h2>
72
+ <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
+
74
+ <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]
75
+ </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]
76
+ </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]
77
+ </span>
78
+ <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
+ </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
+ </span></code></pre>
81
+ <h2 id="Features">Features</h2>
82
+ <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>Numeric Refinements for ergonomics: <code>10.dollars</code>, <code>3.euros</code>, <code>4.to_money('USD')</code></li>
89
+ <li>Currency registry with 117+ currencies and custom registration</li>
90
+ </ul>
91
+ <h2 id="Usage">Usage</h2>
92
+ <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>
93
+
94
+ <span class='comment'># Create money
95
+ </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]
96
+ </span>
97
+ <span class='comment'># Create money using Numeric refinements
98
+ </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>
99
+
100
+ <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
101
+ </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]
102
+ </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]
103
+ </span>
104
+ <span class='comment'># Comparisons
105
+ </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
106
+ </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
107
+ </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
108
+ </span>
109
+ <span class='comment'># Zero equality semantics
110
+ </span><span class='comment'># Any zero amount is treated as equal, regardless of currency
111
+ </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
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='int'>0</span> <span class='comment'>#=&gt; true
113
+ </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
114
+ </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
115
+ </span>
116
+ <span class='comment'># Non-zero numerics are not equal to Money objects
117
+ </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
118
+ </span>
119
+ <span class='comment'># Format (uses Kernel.format internally)
120
+ </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>
121
+
122
+ <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;,
123
+ </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;,
124
+ </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;,
125
+ </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;,
126
+ </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;,
127
+ </span>
128
+ <span class='comment'># Format with padding
129
+ </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>
130
+
131
+ <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;
132
+ </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;
133
+ </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;
134
+ </span>
135
+ <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;
136
+ </span>
137
+ <span class='comment'># Json serialization
138
+ </span>
139
+ <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;
140
+ </span>
141
+ <span class='comment'># Hash conversion
142
+ </span>
143
+ <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;}
144
+ </span>
145
+
146
+ <span class='comment'># Proportional allocation and split
147
+ </span>
148
+ <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]]
149
+ </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]]
150
+ </span>
151
+ <span class='comment'># Ranges and enumeration are supported
152
+ </span>
153
+ <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]
154
+ </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]]
155
+ </span>
156
+ </code></pre>
157
+ <h2 id="API_notes">API notes</h2>
158
+ <p><strong>Module names</strong> — Require the <code>minting</code> gem; the public API lives under <code>Mint</code>.</p>
159
+ <p><strong>Exact amounts</strong> — Amounts are stored as <code>Rational</code> and rounded to the currency subunit.</p>
160
+ <p><strong>Refinements</strong> — <code>10.dollars</code> and similar helpers require <code>using Mint</code> in the current scope (see Usage above).</p>
161
+ <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>
162
+ <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>
163
+ <p><strong>Custom currencies</strong> — <code>Mint.register_currency</code> returns the existing entry if the code is already registered; use <code>register_currency!</code> to detect duplicates.</p>
164
+ <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>
165
+ <h2 id="Installation">Installation</h2>
166
+ <p>Option 1: Via bundler command</p>
167
+ <pre class="code shell"><code class="shell">bundle add minting
168
+ bundle install
169
+ </code></pre>
170
+ <p>Option 2: add the line below to your application's Gemfile:</p>
171
+ <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>
172
+ </code></pre>
173
+ <p>or, if you want latest development version from Github</p>
174
+ <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>
175
+ </code></pre>
176
+ <p>and execute:</p>
177
+ <pre class="code shell"><code class="shell">bundle install
178
+ </code></pre>
179
+ <p>Option 3: Install it yourself with:</p>
180
+ <pre class="code shell"><code class="shell">gem install minting
181
+ </code></pre>
182
+ <h2 id="Parsing_strings">Parsing strings</h2>
183
+ <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='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_parse'><span class='object_link'><a href="Mint/Money.html#parse-class_method" title="Mint::Money.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]
184
+ </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_parse'><span class='object_link'><a href="Mint/Money.html#parse-class_method" title="Mint::Money.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]
185
+ </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_parse'><span class='object_link'><a href="Mint/Money.html#parse-class_method" title="Mint::Money.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]
186
+ </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_parse'><span class='object_link'><a href="Mint/Money.html#parse-class_method" title="Mint::Money.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]
187
+ </span></code></pre>
188
+ <ul>
189
+ <li>Pass a currency code when the string has no symbol or code.</li>
190
+ <li>1,234 means 1.234, not 1234, because one comma is treated as decimal.</li>
191
+ <li>1,234.00 is unambiguous thousands-plus-decimal.</li>
192
+ <li>accounting negatives like ($1.23) are unsupported.</li>
193
+ <li>ambiguous symbols like $ resolve by priority, currently USD.</li>
194
+ </ul>
195
+ <h2 id="Roadmap">Roadmap</h2>
196
+ <ul>
197
+ <li>Improve formatting features</li>
198
+ <li>Localization (I18n-aware formatting)</li>
199
+ <li>Basic exchange-rate conversions</li>
200
+ </ul>
201
+ <h2 id="Contributing">Contributing</h2>
202
+ <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>
203
+ <ol>
204
+ <li>Fork and create a feature branch</li>
205
+ <li>Run the test suite: <code>rake</code></li>
206
+ <li>Run performance suites as needed: <code>BENCH=true rake bench:performance</code></li>
207
+ <li>Open a PR with a clear description and benchmarks if relevant</li>
208
+ </ol>
209
+ <h2 id="Performance">Performance</h2>
210
+ <p>This gem includes a performance suite under <code>test/performance</code>:</p>
211
+ <ul>
212
+ <li>Core operations (creation, arithmetic, comparisons)</li>
213
+ <li>Algorithm benchmarks (split, allocate)</li>
214
+ <li>Memory and GC pressure tests</li>
215
+ <li>Competitive benchmarks vs <code>money</code> gem</li>
216
+ </ul>
217
+ <p>Run locally:</p>
218
+ <pre class="code bash"><code class="bash"># All performance suites
219
+ BENCH=true rake bench:performance
220
+
221
+ # Competitive vs money gem
222
+ BENCH=true rake bench:competitive
223
+
224
+ # Regression checks
225
+ rake bench:regression
226
+ </code></pre>
227
+ <h2 id="Benchmark_Summary__Minting_vs_Money_Gem">Benchmark Summary: Minting vs Money Gem</h2>
228
+ <p>Generated by Qwen from the latest benchmark run on Ruby 4.0.1. - 2026-05-30</p>
229
+ <h3 id="Key_Takeaways">Key Takeaways</h3>
230
+ <ul>
231
+ <li><strong>Mint is consistently faster</strong> than the Money gem across all measured operations.</li>
232
+ <li><strong>Mint is 2.28x faster</strong> in the 50,000-transaction simulation.</li>
233
+ <li><strong>Mint object creation is 2.76x faster</strong> than <code>Money.from_amount</code>.</li>
234
+ <li>In formatting and conversion, Mint is often **10+x **.</li>
235
+ <li>Mint’s performance advantage is especially strong for numeric conversion, string formatting, comparisons, and high-volume transaction loops.</li>
236
+ </ul>
237
+ <h3 id="Performance_Highlights">Performance Highlights</h3>
238
+ <table>
239
+ <thead>
240
+ <tr>
241
+ <th>Category</th>
242
+ <th>Mint</th>
243
+ <th>Money</th>
244
+ <th>Approx. Ratio</th>
245
+ </tr>
246
+ </thead>
247
+ <tbody>
248
+ <tr>
249
+ <td>High-volume transactions</td>
250
+ <td>195,412 ops/sec</td>
251
+ <td>85,882 ops/sec</td>
252
+ <td>2.28x faster</td>
253
+ </tr>
254
+ <tr>
255
+ <td><code>Mint.money</code> creation</td>
256
+ <td>1.14M ops/sec</td>
257
+ <td>—</td>
258
+ <td>2.76x faster than <code>Money.from_amount</code></td>
259
+ </tr>
260
+ <tr>
261
+ <td><code>some.dollars</code> creation</td>
262
+ <td>990k ops/sec</td>
263
+ <td>—</td>
264
+ <td>1.15x faster than <code>Mint.money</code></td>
265
+ </tr>
266
+ <tr>
267
+ <td><code>Money.new</code> creation</td>
268
+ <td>—</td>
269
+ <td>715k ops/sec</td>
270
+ <td>Mint 1.59x faster</td>
271
+ </tr>
272
+ <tr>
273
+ <td><code>to_f</code> formatting</td>
274
+ <td>8.8M–9.3M ops/sec</td>
275
+ <td>0.7M ops/sec</td>
276
+ <td>~12x faster</td>
277
+ </tr>
278
+ <tr>
279
+ <td><code>to_d</code> conversion</td>
280
+ <td>2.1M–2.3M ops/sec</td>
281
+ <td>0.73M–0.79M ops/sec</td>
282
+ <td>~3x faster</td>
283
+ </tr>
284
+ <tr>
285
+ <td><code>to_s</code> formatting</td>
286
+ <td>300k–420k ops/sec</td>
287
+ <td>109k–132k ops/sec</td>
288
+ <td>~3x faster</td>
289
+ </tr>
290
+ <tr>
291
+ <td><code>inspect</code> formatting</td>
292
+ <td>~2.6–2.9M ops/sec</td>
293
+ <td>~1.1–1.16M ops/sec</td>
294
+ <td>~2.5x faster</td>
295
+ </tr>
296
+ <tr>
297
+ <td><code>to_json</code> formatting</td>
298
+ <td>~2.0–2.2M ops/sec</td>
299
+ <td>~110k–126k ops/sec</td>
300
+ <td>~17x faster</td>
301
+ </tr>
302
+ <tr>
303
+ <td>Currency lookup <code>Mint.currency('USD')</code></td>
304
+ <td>3.82M ops/sec</td>
305
+ <td>—</td>
306
+ <td>1.60x faster than <code>Money::Currency.new</code></td>
307
+ </tr>
308
+ <tr>
309
+ <td>Currency lookup <code>Money::Currency.find('USD')</code></td>
310
+ <td>3.63M ops/sec</td>
311
+ <td>1.67M ops/sec</td>
312
+ <td>2.29x faster</td>
313
+ </tr>
314
+ <tr>
315
+ <td>Addition</td>
316
+ <td>1.11M ops/sec</td>
317
+ <td>0.37M ops/sec</td>
318
+ <td>3.0x faster</td>
319
+ </tr>
320
+ <tr>
321
+ <td>Subtraction</td>
322
+ <td>1.11M ops/sec</td>
323
+ <td>0.36M ops/sec</td>
324
+ <td>3.0x faster</td>
325
+ </tr>
326
+ <tr>
327
+ <td>Multiplication</td>
328
+ <td>1.28M ops/sec</td>
329
+ <td>0.51M ops/sec</td>
330
+ <td>2.5x faster</td>
331
+ </tr>
332
+ <tr>
333
+ <td>Division</td>
334
+ <td>1.04M ops/sec</td>
335
+ <td>0.37M ops/sec</td>
336
+ <td>2.8x faster</td>
337
+ </tr>
338
+ <tr>
339
+ <td>Ratio division</td>
340
+ <td>2.94M ops/sec</td>
341
+ <td>0.39M ops/sec</td>
342
+ <td>7.6x faster</td>
343
+ </tr>
344
+ <tr>
345
+ <td>Comparison (<code>==</code>, <code>&lt;</code>, <code>&gt;</code>)</td>
346
+ <td>2.5M–4.1M ops/sec</td>
347
+ <td>0.35M–0.38M ops/sec</td>
348
+ <td>7x–10x faster</td>
349
+ </tr>
350
+ <tr>
351
+ <td>Allocation (<code>Mint.allocate</code>)</td>
352
+ <td>279k ops/sec</td>
353
+ <td>146k ops/sec</td>
354
+ <td>1.9x faster</td>
355
+ </tr>
356
+ <tr>
357
+ <td>Split (<code>Mint.split</code>)</td>
358
+ <td>215k ops/sec</td>
359
+ <td>85k ops/sec</td>
360
+ <td>3.3x faster</td>
361
+ </tr>
362
+ </tbody>
363
+ </table>
364
+ <h3 id="Commands_Used">Commands Used</h3>
365
+ <pre class="code sh"><code class="sh">BENCH=true bundle exec ruby -Ilib:test -r ./test/test_helper.rb test/performance/competitive_performance_benchmark.rb
366
+ BENCH=true bundle exec ruby -Ilib:test -r ./test/test_helper.rb test/performance/competitive_memory_benchmark.rb
367
+ </code></pre>
368
+ <h2 id="License">License</h2>
369
+ <p>MIT</p></div></div>
370
+
371
+ <div id="footer">
372
+ Generated on Tue Jun 2 14:44:35 2026 by
373
+ <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
374
+ 0.9.44 (ruby-4.0.1).
375
+ </div>
376
+
377
+ </div>
378
+ </body>
379
+ </html>
data/doc/file_list.html ADDED
@@ -0,0 +1,59 @@
1
+ <!DOCTYPE html>
2
+ <html >
3
+ <head>
4
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
5
+ <meta charset="utf-8">
6
+
7
+ <link rel="stylesheet" href="css/full_list.css" type="text/css" media="screen">
8
+
9
+ <link rel="stylesheet" href="css/common.css" type="text/css" media="screen">
10
+
11
+
12
+
13
+ <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
14
+
15
+ <script type="text/javascript" charset="utf-8" src="js/full_list.js"></script>
16
+
17
+
18
+ <title>File List</title>
19
+ <base id="base_target" target="_parent">
20
+ </head>
21
+ <body>
22
+ <div id="content">
23
+ <div class="fixed_header">
24
+ <h1 id="full_list_header">File List</h1>
25
+ <div id="full_list_nav">
26
+
27
+ <span><a target="_self" href="class_list.html">
28
+ Classes
29
+ </a></span>
30
+
31
+ <span><a target="_self" href="method_list.html">
32
+ Methods
33
+ </a></span>
34
+
35
+ <span><a target="_self" href="file_list.html">
36
+ Files
37
+ </a></span>
38
+
39
+ </div>
40
+
41
+ <div id="search">
42
+ <label for="search-class">Search:</label>
43
+ <input id="search-class" type="text">
44
+ </div>
45
+ </div>
46
+
47
+ <ul id="full_list" class="file">
48
+
49
+
50
+ <li id="object_README" class="odd">
51
+ <div class="item"><span class="object_link"><a href="index.html" title="README">README</a></span></div>
52
+ </li>
53
+
54
+
55
+
56
+ </ul>
57
+ </div>
58
+ </body>
59
+ </html>
data/doc/frames.html ADDED
@@ -0,0 +1,22 @@
1
+ <!DOCTYPE html>
2
+ <html>
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <title>Documentation by YARD 0.9.44</title>
6
+ </head>
7
+ <script type="text/javascript">
8
+ var mainUrl = 'index.html';
9
+ try {
10
+ var match = decodeURIComponent(window.location.hash).match(/^#!(.+)/);
11
+ var name = match ? match[1] : mainUrl;
12
+ var url = new URL(name, location.href);
13
+ window.top.location.replace(url.origin === location.origin ? name : mainUrl);
14
+ } catch (e) {
15
+ window.top.location.replace(mainUrl);
16
+ }
17
+ </script>
18
+ <noscript>
19
+ <h1>Oops!</h1>
20
+ <h2>YARD requires JavaScript!</h2>
21
+ </noscript>
22
+ </html>