minting 1.9.7 → 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.
- checksums.yaml +4 -4
- data/README.md +234 -116
- data/Rakefile +2 -7
- data/doc/agents/api_review-2026-06-15.md +1 -1
- data/doc/agents/copilot-instructions.md +2 -2
- data/doc/agents/expired/copilot-instructions.md +2 -2
- data/doc/agents/expired/gemini_gem_evaluation.md +2 -2
- data/lib/minting/aliases.rb +22 -0
- data/lib/minting/currency/currency.rb +81 -9
- data/lib/minting/data/crypto-currencies.yaml +126 -0
- data/lib/minting/mint/i18n.rb +79 -29
- data/lib/minting/mint/mint.rb +1 -26
- data/lib/minting/mint/registry/crypto.rb +59 -0
- data/lib/minting/mint/registry/registration.rb +1 -2
- data/lib/minting/mint/registry/symbols.rb +37 -30
- data/lib/minting/mint/rounding.rb +9 -7
- data/lib/minting/mint.rb +1 -2
- data/lib/minting/money/allocation/allocation.rb +2 -2
- data/lib/minting/money/allocation/split.rb +1 -1
- data/lib/minting/money/arithmetics/operators.rb +10 -13
- data/lib/minting/money/clamp.rb +6 -6
- data/lib/minting/money/coercion.rb +1 -1
- data/lib/minting/money/comparable.rb +3 -3
- data/lib/minting/money/constructors.rb +3 -42
- data/lib/minting/money/conversion.rb +22 -18
- data/lib/minting/money/format/format.rb +100 -0
- data/lib/minting/money/format/formatter.rb +102 -0
- data/lib/minting/money/format/to_s.rb +20 -102
- data/lib/minting/money/format/validator.rb +34 -0
- data/lib/minting/money/money.rb +25 -9
- data/lib/minting/money/parse.rb +127 -0
- data/lib/minting/money/rounding.rb +27 -0
- data/lib/minting/version.rb +1 -1
- data/lib/minting.rb +17 -8
- metadata +9 -29
- data/doc/Mint/Currency.html +0 -2032
- data/doc/Mint/Money.html +0 -5139
- data/doc/Mint/RangeStepPatch.html +0 -277
- data/doc/Mint/Registry.html +0 -863
- data/doc/Mint/Rounding.html +0 -506
- data/doc/Mint/UnknownCurrency.html +0 -138
- data/doc/Mint.html +0 -931
- data/doc/Minting.html +0 -142
- data/doc/Numeric.html +0 -479
- data/doc/String.html +0 -241
- data/doc/_index.html +0 -206
- data/doc/class_list.html +0 -54
- data/doc/css/common.css +0 -1
- data/doc/css/full_list.css +0 -206
- data/doc/css/style.css +0 -1089
- data/doc/file.README.html +0 -291
- data/doc/file_list.html +0 -59
- data/doc/frames.html +0 -22
- data/doc/index.html +0 -291
- data/doc/js/app.js +0 -801
- data/doc/js/full_list.js +0 -334
- data/doc/js/jquery.js +0 -4
- data/doc/method_list.html +0 -758
- data/doc/top-level-namespace.html +0 -135
- data/lib/minting/mint/aliases.rb +0 -16
- data/lib/minting/mint/parser/parser.rb +0 -97
- data/lib/minting/mint/parser/separators.rb +0 -41
- data/lib/minting/money/format/formatting.rb +0 -130
data/doc/index.html
DELETED
|
@@ -1,291 +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
|
-
— 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> »
|
|
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'>'</span><span class='tstring_content'>minting</span><span class='tstring_end'>'</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'>'</span><span class='tstring_content'>USD</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='comment'>#=> [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'>#=> [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'>#=> [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'>#=> "$21.59"
|
|
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'>#=> "USD"
|
|
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/BENCHMARKS.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/attribute-money">attribute-money</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'>'</span><span class='tstring_content'>minting</span><span class='tstring_end'>'</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'>'</span><span class='tstring_content'>minting</span><span class='tstring_end'>'</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'>'</span><span class='tstring_content'>USD</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='comment'>#=> [USD 10.00]
|
|
103
|
-
</span>
|
|
104
|
-
<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'>'</span><span class='tstring_content'>USD</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='comment'>#=> true
|
|
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'>#=> [USD 10.00]
|
|
106
|
-
</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'>'</span><span class='tstring_content'>USD</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='comment'>#=> [USD 4.00]
|
|
107
|
-
</span>
|
|
108
|
-
<span class='comment'># Comparisons
|
|
109
|
-
</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'>#=> true
|
|
110
|
-
</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'>'</span><span class='tstring_content'>EUR</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='comment'>#=> false
|
|
111
|
-
</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='float'>9.99</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>USD</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='comment'>#=> true
|
|
112
|
-
</span>
|
|
113
|
-
<span class='comment'># Zero equality semantics
|
|
114
|
-
</span><span class='comment'># Any zero amount is treated as equal, regardless of currency
|
|
115
|
-
</span><span class='const'><span class='object_link'><a href="Mint.html" title="Mint (module)">Mint</a></span></span><span class='period'>.</span><span class='id identifier rubyid_money'><span class='object_link'><a href="Mint.html#money-class_method" title="Mint.money (method)">money</a></span></span><span class='lparen'>(</span><span class='int'>0</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>USD</span><span class='tstring_end'>'</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'>'</span><span class='tstring_content'>EUR</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='comment'>#=> true
|
|
116
|
-
</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'>'</span><span class='tstring_content'>USD</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='op'>==</span> <span class='int'>0</span> <span class='comment'>#=> true
|
|
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'>0</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>USD</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='op'>==</span> <span class='float'>0.0</span> <span class='comment'>#=> true
|
|
118
|
-
</span>
|
|
119
|
-
<span class='comment'># Non-zero numerics are not equal to Money objects
|
|
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'>10</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>USD</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='op'>==</span> <span class='int'>10</span> <span class='comment'>#=> false
|
|
121
|
-
</span>
|
|
122
|
-
<span class='comment'># Format (uses Kernel.format syntax)
|
|
123
|
-
</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'>'</span><span class='tstring_content'>USD</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span>
|
|
124
|
-
<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'>'</span><span class='tstring_content'>USD</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span>
|
|
125
|
-
|
|
126
|
-
<span class='comment'># Built-in named presets
|
|
127
|
-
</span><span class='id identifier rubyid_loss'>loss</span><span class='period'>.</span><span class='id identifier rubyid_format'>format</span><span class='lparen'>(</span><span class='symbol'>:accounting</span><span class='rparen'>)</span> <span class='comment'>#=> "($1,234.56)"
|
|
128
|
-
</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'>1234.56</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>EUR</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_format'><span class='object_link'><a href="Mint/Money.html#format-instance_method" title="Mint::Money#format (method)">format</a></span></span><span class='lparen'>(</span><span class='symbol'>:european</span><span class='rparen'>)</span> <span class='comment'>#=> "1.234,56 €"
|
|
129
|
-
</span><span class='id identifier rubyid_price'>price</span><span class='period'>.</span><span class='id identifier rubyid_format'>format</span><span class='lparen'>(</span><span class='symbol'>:amount</span><span class='rparen'>)</span> <span class='comment'>#=> "9.99"
|
|
130
|
-
</span><span class='id identifier rubyid_price'>price</span><span class='period'>.</span><span class='id identifier rubyid_format'>format</span><span class='lparen'>(</span><span class='symbol'>:currency</span><span class='rparen'>)</span> <span class='comment'>#=> "USD 9.99"
|
|
131
|
-
</span>
|
|
132
|
-
<span class='comment'># Presets can be overridden with explicit kwargs
|
|
133
|
-
</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'>1234.56</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>EUR</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_format'><span class='object_link'><a href="Mint/Money.html#format-instance_method" title="Mint::Money#format (method)">format</a></span></span><span class='lparen'>(</span><span class='symbol'>:european</span><span class='comma'>,</span> <span class='label'>format:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>%<amount>f %<currency>s</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span>
|
|
134
|
-
<span class='comment'>#=> "1.234,56 EUR"
|
|
135
|
-
</span>
|
|
136
|
-
<span class='comment'># Or use direct format strings
|
|
137
|
-
</span><span class='id identifier rubyid_price'>price</span><span class='period'>.</span><span class='id identifier rubyid_format'>format</span> <span class='comment'>#=> "$9.99",
|
|
138
|
-
</span><span class='id identifier rubyid_price'>price</span><span class='period'>.</span><span class='id identifier rubyid_format'>format</span><span class='lparen'>(</span><span class='label'>format:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>%<amount>d</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='comment'>#=> "9",
|
|
139
|
-
</span><span class='id identifier rubyid_price'>price</span><span class='period'>.</span><span class='id identifier rubyid_format'>format</span><span class='lparen'>(</span><span class='label'>format:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>%<symbol>s%<amount>f</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='comment'>#=> "$9.99",
|
|
140
|
-
</span><span class='id identifier rubyid_price'>price</span><span class='period'>.</span><span class='id identifier rubyid_format'>format</span><span class='lparen'>(</span><span class='label'>format:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>%<symbol>s%<amount>+f</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='comment'>#=> "$+9.99",
|
|
141
|
-
</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_format'>format</span><span class='lparen'>(</span><span class='label'>format:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>%<amount>f</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='comment'>#=> "-9.99",
|
|
142
|
-
</span>
|
|
143
|
-
<span class='comment'># Format with padding
|
|
144
|
-
</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'>'</span><span class='tstring_content'>EUR</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span>
|
|
145
|
-
|
|
146
|
-
<span class='id identifier rubyid_price'>price</span><span class='period'>.</span><span class='id identifier rubyid_format'>format</span><span class='lparen'>(</span><span class='label'>format:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>--%<amount>7d</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='comment'>#=> "-- 9"
|
|
147
|
-
</span><span class='id identifier rubyid_price'>price</span><span class='period'>.</span><span class='id identifier rubyid_format'>format</span><span class='lparen'>(</span><span class='label'>format:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'> %<amount>10f %<currency>s</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='comment'>#=> " 9.99 USD"
|
|
148
|
-
</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_format'>format</span><span class='lparen'>(</span><span class='label'>format:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'> %<amount>10f</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='comment'>#=> " -9.99"
|
|
149
|
-
</span>
|
|
150
|
-
<span class='id identifier rubyid_price_in_euros'>price_in_euros</span><span class='period'>.</span><span class='id identifier rubyid_format'>format</span><span class='lparen'>(</span><span class='label'>format:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>%<symbol>2s%<amount>+10f</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='comment'>#=> " € +12.34"
|
|
151
|
-
</span>
|
|
152
|
-
<span class='comment'># Integral & fractional parts
|
|
153
|
-
</span><span class='id identifier rubyid_price'>price</span><span class='period'>.</span><span class='id identifier rubyid_format'>format</span><span class='lparen'>(</span><span class='label'>format:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>%<integral>d %<fractional>d/100</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='comment'>#=> "9 99/100"
|
|
154
|
-
</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'>'</span><span class='tstring_content'>USD</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_format'><span class='object_link'><a href="Mint/Money.html#format-instance_method" title="Mint::Money#format (method)">format</a></span></span><span class='lparen'>(</span><span class='label'>format:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>%<integral>d dollars and %<fractional>02d cents</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span>
|
|
155
|
-
<span class='comment'>#=> "0 dollars and 99 cents"
|
|
156
|
-
</span>
|
|
157
|
-
<span class='comment'># Per-sign Hash format (e.g. accounting parentheses for losses)
|
|
158
|
-
</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'>'</span><span class='tstring_content'>USD</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span>
|
|
159
|
-
<span class='id identifier rubyid_loss'>loss</span><span class='period'>.</span><span class='id identifier rubyid_format'>format</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'>'</span><span class='tstring_content'>(%<symbol>s%<amount>f)</span><span class='tstring_end'>'</span></span> <span class='rbrace'>}</span><span class='rparen'>)</span> <span class='comment'>#=> "($1,234.56)"
|
|
160
|
-
</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'>'</span><span class='tstring_content'>BRL</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_format'><span class='object_link'><a href="Mint/Money.html#format-instance_method" title="Mint::Money#format (method)">format</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'>'</span><span class='tstring_content'>--</span><span class='tstring_end'>'</span></span> <span class='rbrace'>}</span><span class='rparen'>)</span> <span class='comment'>#=> "--"
|
|
161
|
-
</span><span class='comment'># All three keys at once:
|
|
162
|
-
</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'>'</span><span class='tstring_content'>%<symbol>s%<amount>f</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='label'>negative:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>(%<symbol>s%<amount>f)</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='label'>zero:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>--</span><span class='tstring_end'>'</span></span> <span class='rbrace'>}</span>
|
|
163
|
-
<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'>'</span><span class='tstring_content'>USD</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_format'><span class='object_link'><a href="Mint/Money.html#format-instance_method" title="Mint::Money#format (method)">format</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'>#=> "$1,234.56"
|
|
164
|
-
</span>
|
|
165
|
-
<span class='comment'># Disambiguated symbol (e.g. "US$" vs "C$" vs "A$")
|
|
166
|
-
</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'>'</span><span class='tstring_content'>USD</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_format'><span class='object_link'><a href="Mint/Money.html#format-instance_method" title="Mint::Money#format (method)">format</a></span></span><span class='lparen'>(</span><span class='label'>format:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>%<dsymbol>s%<amount>f</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='comment'>#=> "US$10.00"
|
|
167
|
-
</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'>'</span><span class='tstring_content'>CAD</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_format'><span class='object_link'><a href="Mint/Money.html#format-instance_method" title="Mint::Money#format (method)">format</a></span></span><span class='lparen'>(</span><span class='label'>format:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>%<dsymbol>s%<amount>f</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='comment'>#=> "C$10.00"
|
|
168
|
-
</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'>'</span><span class='tstring_content'>EUR</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_format'><span class='object_link'><a href="Mint/Money.html#format-instance_method" title="Mint::Money#format (method)">format</a></span></span><span class='lparen'>(</span><span class='label'>format:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>%<dsymbol>s%<amount>f</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='comment'>#=> "€10.00" (no dsymbol, falls back to symbol)
|
|
169
|
-
</span>
|
|
170
|
-
<span class='comment'># Json serialization
|
|
171
|
-
</span>
|
|
172
|
-
<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'># => "{\"currency\": \"USD\", \"amount\": \"9.99\"}"
|
|
173
|
-
</span>
|
|
174
|
-
<span class='comment'># Hash conversion
|
|
175
|
-
</span>
|
|
176
|
-
<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'>#=> {currency: "USD", amount: "9.99"}
|
|
177
|
-
</span>
|
|
178
|
-
|
|
179
|
-
<span class='comment'># Fractional units (inverse of #fractional) - exact integer arithmetic
|
|
180
|
-
</span>
|
|
181
|
-
<span class='id identifier rubyid_price'>price</span><span class='period'>.</span><span class='id identifier rubyid_subunits'>subunits</span> <span class='comment'>#=> 999
|
|
182
|
-
</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'>'</span><span class='tstring_content'>USD</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='comment'>#=> [USD 9.99]
|
|
183
|
-
</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'>'</span><span class='tstring_content'>JPY</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='comment'>#=> [JPY 1234] # subunit 0 -> no scaling
|
|
184
|
-
</span>
|
|
185
|
-
|
|
186
|
-
<span class='comment'># No currency (ISO 4217 XXX)
|
|
187
|
-
</span>
|
|
188
|
-
<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'>#=> [XXX 100]
|
|
189
|
-
</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'>#=> [XXX 0]
|
|
190
|
-
</span>
|
|
191
|
-
|
|
192
|
-
<span class='comment'># Proportional allocation and split
|
|
193
|
-
</span>
|
|
194
|
-
<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'>#=> [[USD 3.34], [USD 3.33], [USD 3.33]]
|
|
195
|
-
</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'>#=> [[USD 1.67], [USD 3.33], [USD 5.00]]
|
|
196
|
-
</span>
|
|
197
|
-
<span class='comment'># Clamping to a range
|
|
198
|
-
</span>
|
|
199
|
-
<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'>'</span><span class='tstring_content'>USD</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span>
|
|
200
|
-
<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'>'</span><span class='tstring_content'>USD</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span>
|
|
201
|
-
|
|
202
|
-
<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'>#=> [USD 50.00] (returns self, no new object)
|
|
203
|
-
</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'>#=> [USD 25.00] (clamped to max)
|
|
204
|
-
</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'>#=> [USD 75.00] (clamped to min)
|
|
205
|
-
</span>
|
|
206
|
-
<span class='comment'># Clamp accepts Money bounds or Numeric amounts
|
|
207
|
-
</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'>#=> [USD 75.00]
|
|
208
|
-
</span>
|
|
209
|
-
<span class='comment'># Ranges and enumeration are supported
|
|
210
|
-
</span>
|
|
211
|
-
<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'>#=> [USD 1.00]..[USD 10.00]
|
|
212
|
-
</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'>#=> [[USD 1.00], [USD 2.00], [USD 3.00]]
|
|
213
|
-
</span>
|
|
214
|
-
</code></pre>
|
|
215
|
-
<h2 id="Parsing_strings">Parsing strings</h2>
|
|
216
|
-
<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'>'</span><span class='tstring_content'>$19.99</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='comment'>#=> [USD 19.99]
|
|
217
|
-
</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'>'</span><span class='tstring_content'>19,99 €</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='comment'>#=> [EUR 19.99]
|
|
218
|
-
</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'>'</span><span class='tstring_content'>1.234,56</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>EUR</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='comment'>#=> [EUR 1234.56]
|
|
219
|
-
</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'>'</span><span class='tstring_content'>USD 1,234.56</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='comment'>#=> [USD 1234.56]
|
|
220
|
-
</span></code></pre>
|
|
221
|
-
<p>Notes:</p>
|
|
222
|
-
<ul>
|
|
223
|
-
<li>Pass a currency code when the string has no symbol or code.</li>
|
|
224
|
-
<li><code>1,234</code> means 1234, not 1.234 and <code>1,23</code> means 1.23, not 123</li>
|
|
225
|
-
<li><code>1,234.00</code> is unambiguous (thousands + decimal).</li>
|
|
226
|
-
<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>
|
|
227
|
-
<li>Ambiguous symbols like <code>$</code> resolve by currency priority (currently USD).</li>
|
|
228
|
-
<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("MAX 10.00 USD")</code> yields <code>[USD 10.00]</code>.</li>
|
|
229
|
-
</ul>
|
|
230
|
-
<h2 id="Currency_lookup">Currency lookup</h2>
|
|
231
|
-
<pre class="code ruby"><code class="ruby"><span class='comment'># By ISO code (direct hash lookup, string only)
|
|
232
|
-
</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'>'</span><span class='tstring_content'>USD</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='comment'>#=> #<Currency code="USD" ...>
|
|
233
|
-
</span>
|
|
234
|
-
<span class='comment'># By display symbol (highest-priority currency for ambiguous symbols)
|
|
235
|
-
</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'>'</span><span class='tstring_content'>$</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='comment'>#=> #<Currency code="USD" ...>
|
|
236
|
-
</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'>'</span><span class='tstring_content'>R$</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='comment'>#=> #<Currency code="BRL" ...>
|
|
237
|
-
</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'>'</span><span class='tstring_content'>€</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='comment'>#=> #<Currency code="EUR" ...>
|
|
238
|
-
</span>
|
|
239
|
-
</code></pre>
|
|
240
|
-
<h2 id="API_notes">API notes</h2>
|
|
241
|
-
<p><strong>Exact amounts</strong> — Amounts are stored as <code>Rational</code> and rounded to the currency subunit.</p>
|
|
242
|
-
<p><strong>Rounding modes</strong> — Wrap operations in <code>Mint.with_rounding(mode)</code> to change how amounts are rounded to the subunit:</p>
|
|
243
|
-
<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'>'</span><span class='tstring_content'>USD</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='rbrace'>}</span> <span class='comment'>#=> [USD 1.00]
|
|
244
|
-
</span><span class='const'><span class='object_link'><a href="Mint.html" title="Mint (module)">Mint</a></span></span><span class='period'>.</span><span class='id identifier rubyid_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'>'</span><span class='tstring_content'>USD</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='rbrace'>}</span> <span class='comment'>#=> [USD 1.01]
|
|
245
|
-
</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'>'</span><span class='tstring_content'>1.009</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>USD</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='rbrace'>}</span> <span class='comment'>#=> [USD 1.00]
|
|
246
|
-
</span></code></pre>
|
|
247
|
-
<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>
|
|
248
|
-
<blockquote>
|
|
249
|
-
<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>
|
|
250
|
-
</blockquote>
|
|
251
|
-
<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>
|
|
252
|
-
<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>
|
|
253
|
-
<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>
|
|
254
|
-
<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>
|
|
255
|
-
<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>
|
|
256
|
-
<h2 id="Optional_top_level__Money__and__Currency_">Optional top-level <code>Money</code> and <code>Currency</code></h2>
|
|
257
|
-
<p>By default, <code>require "minting"</code> exposes <code>Mint::Money</code> as the top-level <code>Money</code> constant, so you can write <code>Money.from(10, "USD")</code> directly:</p>
|
|
258
|
-
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>minting</span><span class='tstring_end'>"</span></span>
|
|
259
|
-
|
|
260
|
-
<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'>"</span><span class='tstring_content'>USD</span><span class='tstring_end'>"</span></span><span class='rparen'>)</span> <span class='comment'># equivalent to Mint::Money.from
|
|
261
|
-
</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'>"</span><span class='tstring_content'>USD</span><span class='tstring_end'>"</span></span><span class='rparen'>)</span>
|
|
262
|
-
</code></pre>
|
|
263
|
-
<p><code>Currency</code> is <strong>not</strong> auto-bound, because application domain models are commonly named <code>Currency</code> (e.g. a Rails model). To opt in to the top-level <code>Currency</code> constant:</p>
|
|
264
|
-
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>minting</span><span class='tstring_end'>"</span></span>
|
|
265
|
-
<span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>minting/mint/aliases</span><span class='tstring_end'>"</span></span> <span class='comment'># opt-in top-level Currency
|
|
266
|
-
</span>
|
|
267
|
-
<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'>"</span><span class='tstring_content'>EUR</span><span class='tstring_end'>"</span></span><span class='comma'>,</span> <span class='label'>symbol:</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>€</span><span class='tstring_end'>"</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>
|
|
268
|
-
</code></pre>
|
|
269
|
-
<p>For Rails applications, you can enable the top-level <code>Currency</code> constant in an initializer:</p>
|
|
270
|
-
<pre class="code ruby"><code class="ruby"><span class='comment'># config/initializers/minting.rb
|
|
271
|
-
</span><span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>minting/mint/aliases</span><span class='tstring_end'>"</span></span>
|
|
272
|
-
</code></pre>
|
|
273
|
-
<p>If another <code>Money</code> is already defined when <code>require "minting"</code> runs (e.g. the <code>money</code> gem was loaded first), Minting warns and skips the auto-bind — use <code>Mint::Money</code> in that case. The same applies to <code>Currency</code> via <code>minting/mint/aliases</code>.</p>
|
|
274
|
-
<p><strong>Good fit:</strong> Application code, especially Rails apps.
|
|
275
|
-
<strong>Not recommended:</strong> Reusable gems/libraries — stick to <code>Mint::Money</code> to avoid conflicts.</p>
|
|
276
|
-
<h2 id="Roadmap">Roadmap</h2>
|
|
277
|
-
<ul>
|
|
278
|
-
<li>Exchange-rate conversion infrastructure</li>
|
|
279
|
-
</ul>
|
|
280
|
-
<h2 id="License">License</h2>
|
|
281
|
-
<p>MIT</p></div></div>
|
|
282
|
-
|
|
283
|
-
<div id="footer">
|
|
284
|
-
Generated on Wed Jul 1 01:11:52 2026 by
|
|
285
|
-
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
|
|
286
|
-
0.9.44 (ruby-4.0.5).
|
|
287
|
-
</div>
|
|
288
|
-
|
|
289
|
-
</div>
|
|
290
|
-
</body>
|
|
291
|
-
</html>
|