minting 1.7.3 → 1.8.1
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 +31 -24
- data/Rakefile +15 -4
- data/doc/Mint/Currency.html +535 -18
- data/doc/Mint/Money.html +659 -185
- data/doc/Mint/RangeStepPatch.html +1 -1
- data/doc/Mint/Registry.html +19 -2
- data/doc/Mint/Rounding.html +495 -0
- data/doc/Mint/UnknownCurrency.html +1 -1
- data/doc/Mint.html +187 -399
- data/doc/Minting.html +2 -2
- data/doc/_index.html +8 -1
- data/doc/agents/api_review-2026-06-15.md +0 -13
- data/doc/agents/copilot-instructions.md +70 -0
- data/doc/class_list.html +1 -1
- data/doc/file.README.html +19 -9
- data/doc/index.html +19 -9
- data/doc/method_list.html +130 -42
- data/doc/top-level-namespace.html +1 -1
- data/lib/minting/currency/currency.rb +41 -2
- data/lib/minting/mint/dsl/numeric.rb +4 -4
- data/lib/minting/mint/dsl/range.rb +1 -0
- data/lib/minting/mint/dsl/string.rb +1 -1
- data/lib/minting/mint/mint.rb +10 -37
- data/lib/minting/mint/parser/parser.rb +50 -15
- data/lib/minting/mint/parser/separators.rb +10 -8
- data/lib/minting/mint/registry/zeros.rb +3 -1
- data/lib/minting/mint/rounding.rb +51 -0
- data/lib/minting/mint.rb +1 -0
- data/lib/minting/money/allocation/allocation.rb +1 -2
- data/lib/minting/money/allocation/split.rb +1 -1
- data/lib/minting/money/arithmetics/methods.rb +2 -2
- data/lib/minting/money/arithmetics/operators.rb +6 -6
- data/lib/minting/money/clamp.rb +1 -1
- data/lib/minting/money/coercion.rb +1 -1
- data/lib/minting/money/comparable.rb +6 -0
- data/lib/minting/money/constructors.rb +60 -12
- data/lib/minting/money/money.rb +0 -6
- data/lib/minting/version.rb +1 -1
- metadata +4 -1
data/doc/Minting.html
CHANGED
|
@@ -116,7 +116,7 @@
|
|
|
116
116
|
|
|
117
117
|
</div>
|
|
118
118
|
</dt>
|
|
119
|
-
<dd><pre class="code"><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>1.7.
|
|
119
|
+
<dd><pre class="code"><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>1.7.3</span><span class='tstring_end'>'</span></span></pre></dd>
|
|
120
120
|
|
|
121
121
|
</dl>
|
|
122
122
|
|
|
@@ -132,7 +132,7 @@
|
|
|
132
132
|
</div>
|
|
133
133
|
|
|
134
134
|
<div id="footer">
|
|
135
|
-
Generated on
|
|
135
|
+
Generated on Tue Jun 16 20:22:19 2026 by
|
|
136
136
|
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
|
|
137
137
|
0.9.44 (ruby-4.0.5).
|
|
138
138
|
</div>
|
data/doc/_index.html
CHANGED
|
@@ -136,6 +136,13 @@
|
|
|
136
136
|
|
|
137
137
|
</li>
|
|
138
138
|
|
|
139
|
+
<li>
|
|
140
|
+
<span class='object_link'><a href="Mint/Rounding.html" title="Mint::Rounding (module)">Rounding</a></span>
|
|
141
|
+
|
|
142
|
+
<small>(Mint)</small>
|
|
143
|
+
|
|
144
|
+
</li>
|
|
145
|
+
|
|
139
146
|
</ul>
|
|
140
147
|
</ul>
|
|
141
148
|
|
|
@@ -163,7 +170,7 @@
|
|
|
163
170
|
</div>
|
|
164
171
|
|
|
165
172
|
<div id="footer">
|
|
166
|
-
Generated on
|
|
173
|
+
Generated on Tue Jun 16 20:22:19 2026 by
|
|
167
174
|
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
|
|
168
175
|
0.9.44 (ruby-4.0.5).
|
|
169
176
|
</div>
|
|
@@ -142,8 +142,6 @@ This is odd: the param type is a `Currency` in the docs, but you call `other.cur
|
|
|
142
142
|
|
|
143
143
|
## 3. Parsing API
|
|
144
144
|
|
|
145
|
-
`Mint.parse` is already strong. To beat competitors, lean into this.
|
|
146
|
-
|
|
147
145
|
### Suggestions
|
|
148
146
|
|
|
149
147
|
1. **Return type & error modes**
|
|
@@ -153,17 +151,6 @@ This is odd: the param type is a `Currency` in the docs, but you call `other.cur
|
|
|
153
151
|
- `Mint.parse!(...)` – raises on failure.
|
|
154
152
|
- `Mint.parse(...)` – returns `nil` on failure or perhaps `Result` object in future, but nil is sufficient initially.
|
|
155
153
|
|
|
156
|
-
2. **Expose configuration hooks**
|
|
157
|
-
|
|
158
|
-
Even if not fully implemented yet, define the shape:
|
|
159
|
-
|
|
160
|
-
```ruby
|
|
161
|
-
Mint.parser.default_currency = 'USD'
|
|
162
|
-
Mint.parser.symbol_priority = %w[USD CAD AUD]
|
|
163
|
-
```
|
|
164
|
-
|
|
165
|
-
That gives you a path to match/beat `monetize` / `money` ecosystem flexibility.
|
|
166
|
-
|
|
167
154
|
3. **Quality-of-life alias**
|
|
168
155
|
|
|
169
156
|
- `Mint.money_from(str, currency_code = nil)`
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
Repository overview
|
|
2
|
+
|
|
3
|
+
- Language: Ruby gem (minting)
|
|
4
|
+
- Location of main code: lib/minting and its subfolders (mint/, money/)
|
|
5
|
+
- Public API surface: Mint (factory/helpers), Mint::Money, Mint::Currency
|
|
6
|
+
- Data: built-in currencies in lib/minting/data/currencies.yaml
|
|
7
|
+
- Tests: Minitest (unit) + performance benchmarks under test/performance
|
|
8
|
+
|
|
9
|
+
Build, test and lint commands
|
|
10
|
+
|
|
11
|
+
- Install dependencies:
|
|
12
|
+
- bundle install
|
|
13
|
+
|
|
14
|
+
- Run full test suite (default task):
|
|
15
|
+
- bundle exec rake
|
|
16
|
+
- or simply: rake
|
|
17
|
+
|
|
18
|
+
- Run a single test file (recommended when iterating):
|
|
19
|
+
- ruby -Ilib:test -r ./test/test_helper.rb test/money/money_test.rb
|
|
20
|
+
|
|
21
|
+
- Run a single test method by name (Minitest -n regexp):
|
|
22
|
+
- ruby -Ilib:test -r ./test/test_helper.rb test/money/money_test.rb -n /test_creation/
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
- Linting:
|
|
26
|
+
- bundle exec rake cop
|
|
27
|
+
- or: bundle exec rubocop
|
|
28
|
+
|
|
29
|
+
- Build gem package:
|
|
30
|
+
- gem build minting.gemspec
|
|
31
|
+
|
|
32
|
+
- Documentation:
|
|
33
|
+
- bundle exec rake yard
|
|
34
|
+
|
|
35
|
+
- README verification:
|
|
36
|
+
- README examples are exercised by `test/minting_test.rb#test_readme_usage`.
|
|
37
|
+
- Prefer the README as the authoritative usage guide for feature behavior and examples.
|
|
38
|
+
|
|
39
|
+
High-level architecture (big picture)
|
|
40
|
+
|
|
41
|
+
- Top-level: lib/minting.rb requires the Mint module and Money implementation.
|
|
42
|
+
- Mint module: currency registry and factory helpers live in lib/minting/mint/*. Registry loads lib/minting/data/currencies.yaml on first access.
|
|
43
|
+
- Currency: lightweight value object (code, subunit, symbol, priority, minimum_amount).
|
|
44
|
+
- Money: immutable value object stored as Rational and rounded to currency.subunit. Core concerns split across lib/minting/money/* (arithmetics, formatting, conversion, coercion, allocation, parsing, comparable).
|
|
45
|
+
- Refinements: Numeric/String/Refinements in lib/minting/mint/refinements.rb expose helpers like 10.dollars, 4.to_money('USD'), and require `using Mint` in scope.
|
|
46
|
+
- Performance tests: separate bench tasks under Rake; test/performance holds benchmark suites.
|
|
47
|
+
|
|
48
|
+
Key conventions and repo-specific rules
|
|
49
|
+
|
|
50
|
+
- Exactness: amounts are stored as Rational and rounded to the currency subunit. Prefer rationals or decimal strings (e.g., '19.99'.to_r or 1999/100r) when precision is needed.
|
|
51
|
+
- Zero equality: zeros are equal across currencies (Mint.money(0,'USD') == Mint.money(0,'EUR') == 0). Non-zero comparisons require identical currency and amount.
|
|
52
|
+
- Currency registration: use Mint.register_currency for idempotent registration; Mint.register_currency! raises on duplicates. Codes must match /^[A-Z_]+$/.
|
|
53
|
+
- Symbol parsing: parser resolves symbols by longest match then currency priority (see Mint.currency_symbols sorting).
|
|
54
|
+
- Tests: test_helper.rb configures coverage (SimpleCov) and loads minitest; when running tests outside rake, require test_helper (-r ./test/test_helper.rb).
|
|
55
|
+
- Formatting: Money.to_s uses Kernel.format patterns; take care with %<amount>f vs %<amount>d depending on desired rounding/formatting.
|
|
56
|
+
|
|
57
|
+
Files and places to check first during edits
|
|
58
|
+
|
|
59
|
+
- lib/minting/money - core behavior and arithmetic
|
|
60
|
+
- lib/minting/mint - currency registry, refinements, and factory API
|
|
61
|
+
- lib/minting/data/currencies.yaml - canonical currency definitions
|
|
62
|
+
- test/ - unit tests; test/performance - benchmark suites
|
|
63
|
+
|
|
64
|
+
Notes for Copilot sessions
|
|
65
|
+
|
|
66
|
+
- Prefer making atomic changes and run the unit test(s) covering the changed area. Use the single-file test invocation above when iterating rapidly.
|
|
67
|
+
- When changing numeric/rounding behavior, run both unit tests and relevant performance benchmarks.
|
|
68
|
+
- Respect zero-equality semantics and currency code validation when modifying equality/hash logic.
|
|
69
|
+
|
|
70
|
+
If you want, update this file with project-specific conventions to capture workflow choices (e.g., backport policy, DI patterns).
|
data/doc/class_list.html
CHANGED
|
@@ -46,7 +46,7 @@
|
|
|
46
46
|
|
|
47
47
|
<ul id="full_list" class="class">
|
|
48
48
|
<li id="object_" class="odd"><div class="item" style="padding-left:30px"><span class='object_link'><a href="top-level-namespace.html" title="Top Level Namespace (root)">Top Level Namespace</a></span></div></li>
|
|
49
|
-
<li id='object_Mint' class='even'><div class='item' style='padding-left:30px'><a tabindex='0' class='toggle' role='button' aria-label='Mint child nodes' aria-expanded='false' aria-controls='object_Mint'></a> <span class='object_link'><a href="Mint.html" title="Mint (module)">Mint</a></span><small class='search_info'>Top Level Namespace</small></div><div aria-labelledby='object_Mint'><ul><li id='object_Mint::Currency' class='collapsed odd'><div class='item' style='padding-left:45px'><span class='object_link'><a href="Mint/Currency.html" title="Mint::Currency (class)">Currency</a></span> < Data<small class='search_info'>Mint</small></div></li><li id='object_Mint::Money' class='collapsed even'><div class='item' style='padding-left:45px'><span class='object_link'><a href="Mint/Money.html" title="Mint::Money (class)">Money</a></span> < Object<small class='search_info'>Mint</small></div></li><li id='object_Mint::RangeStepPatch' class='collapsed odd'><div class='item' style='padding-left:45px'><span class='object_link'><a href="Mint/RangeStepPatch.html" title="Mint::RangeStepPatch (module)">RangeStepPatch</a></span><small class='search_info'>Mint</small></div></li><li id='object_Mint::Registry' class='collapsed even'><div class='item' style='padding-left:45px'><span class='object_link'><a href="Mint/Registry.html" title="Mint::Registry (module)">Registry</a></span><small class='search_info'>Mint</small></div></li><li id='object_Mint::
|
|
49
|
+
<li id='object_Mint' class='even'><div class='item' style='padding-left:30px'><a tabindex='0' class='toggle' role='button' aria-label='Mint child nodes' aria-expanded='false' aria-controls='object_Mint'></a> <span class='object_link'><a href="Mint.html" title="Mint (module)">Mint</a></span><small class='search_info'>Top Level Namespace</small></div><div aria-labelledby='object_Mint'><ul><li id='object_Mint::Currency' class='collapsed odd'><div class='item' style='padding-left:45px'><span class='object_link'><a href="Mint/Currency.html" title="Mint::Currency (class)">Currency</a></span> < Data<small class='search_info'>Mint</small></div></li><li id='object_Mint::Money' class='collapsed even'><div class='item' style='padding-left:45px'><span class='object_link'><a href="Mint/Money.html" title="Mint::Money (class)">Money</a></span> < Object<small class='search_info'>Mint</small></div></li><li id='object_Mint::RangeStepPatch' class='collapsed odd'><div class='item' style='padding-left:45px'><span class='object_link'><a href="Mint/RangeStepPatch.html" title="Mint::RangeStepPatch (module)">RangeStepPatch</a></span><small class='search_info'>Mint</small></div></li><li id='object_Mint::Registry' class='collapsed even'><div class='item' style='padding-left:45px'><span class='object_link'><a href="Mint/Registry.html" title="Mint::Registry (module)">Registry</a></span><small class='search_info'>Mint</small></div></li><li id='object_Mint::Rounding' class='collapsed odd'><div class='item' style='padding-left:45px'><span class='object_link'><a href="Mint/Rounding.html" title="Mint::Rounding (module)">Rounding</a></span><small class='search_info'>Mint</small></div></li><li id='object_Mint::UnknownCurrency' class='collapsed even'><div class='item' style='padding-left:45px'><span class='object_link'><a href="Mint/UnknownCurrency.html" title="Mint::UnknownCurrency (class)">UnknownCurrency</a></span> < StandardError<small class='search_info'>Mint</small></div></li></ul></div></li><li id='object_Minting' class='odd'><div class='item' style='padding-left:30px'><span class='object_link'><a href="Minting.html" title="Minting (module)">Minting</a></span><small class='search_info'>Top Level Namespace</small></div></li>
|
|
50
50
|
|
|
51
51
|
</ul>
|
|
52
52
|
</div>
|
data/doc/file.README.html
CHANGED
|
@@ -236,21 +236,27 @@
|
|
|
236
236
|
</ul>
|
|
237
237
|
<h2 id="Currency_lookup">Currency lookup</h2>
|
|
238
238
|
<pre class="code ruby"><code class="ruby"><span class='comment'># By ISO code (direct hash lookup, string only)
|
|
239
|
-
</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
|
|
239
|
+
</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" ...>
|
|
240
240
|
</span>
|
|
241
241
|
<span class='comment'># By display symbol (highest-priority currency for ambiguous symbols)
|
|
242
|
-
</span><span class='const'><span class='object_link'><a href="Mint.html" title="Mint (module)">Mint</a></span></span><span class='period'>.</span><span class='id identifier
|
|
243
|
-
</span><span class='const'><span class='object_link'><a href="Mint.html" title="Mint (module)">Mint</a></span></span><span class='period'>.</span><span class='id identifier
|
|
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
|
|
242
|
+
</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" ...>
|
|
243
|
+
</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" ...>
|
|
244
|
+
</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" ...>
|
|
245
245
|
</span>
|
|
246
246
|
</code></pre>
|
|
247
247
|
<h2 id="API_notes">API notes</h2>
|
|
248
248
|
<p><strong>Exact amounts</strong> — Amounts are stored as <code>Rational</code> and rounded to the currency subunit.</p>
|
|
249
|
+
<p><strong>Rounding modes</strong> — Wrap operations in <code>Mint.with_rounding(mode)</code> to change how amounts are rounded to the subunit:</p>
|
|
250
|
+
<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]
|
|
251
|
+
</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]
|
|
252
|
+
</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]
|
|
253
|
+
</span></code></pre>
|
|
254
|
+
<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>
|
|
249
255
|
<p><strong>Refinements</strong> — <code>10.dollars</code> and similar helpers require <code>using Mint</code> in the current scope (see Usage above).</p>
|
|
250
256
|
<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>
|
|
251
257
|
<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>
|
|
252
|
-
<p><strong>Zero helper</strong> — <code>
|
|
253
|
-
<p><strong>Registered currencies</strong> — <code>
|
|
258
|
+
<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>
|
|
259
|
+
<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.</p>
|
|
254
260
|
<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>
|
|
255
261
|
<h2 id="Optional_top_level__Money__and__Currency_">Optional top-level <code>Money</code> and <code>Currency</code></h2>
|
|
256
262
|
<p>By default, Minting keeps everything namespaced under <code>Mint</code> to coexist nicely with other gems. If you prefer shorter constants, opt in:</p>
|
|
@@ -260,9 +266,13 @@
|
|
|
260
266
|
<p>Or at runtime:</p>
|
|
261
267
|
<pre class="code ruby"><code class="ruby"><span class='const'><span class='object_link'><a href="Minting.html" title="Minting (module)">Minting</a></span></span><span class='period'>.</span><span class='id identifier rubyid_use_top_level_constants!'>use_top_level_constants!</span>
|
|
262
268
|
</code></pre>
|
|
269
|
+
<p>For Rails applications, you can enable the top-level constants 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/dsl</span><span class='tstring_end'>"</span></span>
|
|
272
|
+
</code></pre>
|
|
263
273
|
<p>After opting in:</p>
|
|
264
|
-
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_price'>price</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="top-level-namespace.html#Money-constant" title="Money (constant)">Money</a></span></span><span class='period'>.</span><span class='id identifier
|
|
265
|
-
</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
|
|
274
|
+
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_price'>price</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="top-level-namespace.html#Money-constant" title="Money (constant)">Money</a></span></span><span class='period'>.</span><span class='id identifier rubyid_from'>from</span><span class='lparen'>(</span><span class='int'>10</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>"</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
|
|
275
|
+
</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>
|
|
266
276
|
<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>
|
|
267
277
|
</code></pre>
|
|
268
278
|
<p><strong>Good fit:</strong> Application code, especially Rails apps.
|
|
@@ -276,7 +286,7 @@
|
|
|
276
286
|
<p>MIT</p></div></div>
|
|
277
287
|
|
|
278
288
|
<div id="footer">
|
|
279
|
-
Generated on
|
|
289
|
+
Generated on Tue Jun 16 20:22:19 2026 by
|
|
280
290
|
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
|
|
281
291
|
0.9.44 (ruby-4.0.5).
|
|
282
292
|
</div>
|
data/doc/index.html
CHANGED
|
@@ -236,21 +236,27 @@
|
|
|
236
236
|
</ul>
|
|
237
237
|
<h2 id="Currency_lookup">Currency lookup</h2>
|
|
238
238
|
<pre class="code ruby"><code class="ruby"><span class='comment'># By ISO code (direct hash lookup, string only)
|
|
239
|
-
</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
|
|
239
|
+
</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" ...>
|
|
240
240
|
</span>
|
|
241
241
|
<span class='comment'># By display symbol (highest-priority currency for ambiguous symbols)
|
|
242
|
-
</span><span class='const'><span class='object_link'><a href="Mint.html" title="Mint (module)">Mint</a></span></span><span class='period'>.</span><span class='id identifier
|
|
243
|
-
</span><span class='const'><span class='object_link'><a href="Mint.html" title="Mint (module)">Mint</a></span></span><span class='period'>.</span><span class='id identifier
|
|
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
|
|
242
|
+
</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" ...>
|
|
243
|
+
</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" ...>
|
|
244
|
+
</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" ...>
|
|
245
245
|
</span>
|
|
246
246
|
</code></pre>
|
|
247
247
|
<h2 id="API_notes">API notes</h2>
|
|
248
248
|
<p><strong>Exact amounts</strong> — Amounts are stored as <code>Rational</code> and rounded to the currency subunit.</p>
|
|
249
|
+
<p><strong>Rounding modes</strong> — Wrap operations in <code>Mint.with_rounding(mode)</code> to change how amounts are rounded to the subunit:</p>
|
|
250
|
+
<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]
|
|
251
|
+
</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]
|
|
252
|
+
</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]
|
|
253
|
+
</span></code></pre>
|
|
254
|
+
<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>
|
|
249
255
|
<p><strong>Refinements</strong> — <code>10.dollars</code> and similar helpers require <code>using Mint</code> in the current scope (see Usage above).</p>
|
|
250
256
|
<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>
|
|
251
257
|
<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>
|
|
252
|
-
<p><strong>Zero helper</strong> — <code>
|
|
253
|
-
<p><strong>Registered currencies</strong> — <code>
|
|
258
|
+
<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>
|
|
259
|
+
<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.</p>
|
|
254
260
|
<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>
|
|
255
261
|
<h2 id="Optional_top_level__Money__and__Currency_">Optional top-level <code>Money</code> and <code>Currency</code></h2>
|
|
256
262
|
<p>By default, Minting keeps everything namespaced under <code>Mint</code> to coexist nicely with other gems. If you prefer shorter constants, opt in:</p>
|
|
@@ -260,9 +266,13 @@
|
|
|
260
266
|
<p>Or at runtime:</p>
|
|
261
267
|
<pre class="code ruby"><code class="ruby"><span class='const'><span class='object_link'><a href="Minting.html" title="Minting (module)">Minting</a></span></span><span class='period'>.</span><span class='id identifier rubyid_use_top_level_constants!'>use_top_level_constants!</span>
|
|
262
268
|
</code></pre>
|
|
269
|
+
<p>For Rails applications, you can enable the top-level constants 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/dsl</span><span class='tstring_end'>"</span></span>
|
|
272
|
+
</code></pre>
|
|
263
273
|
<p>After opting in:</p>
|
|
264
|
-
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_price'>price</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="top-level-namespace.html#Money-constant" title="Money (constant)">Money</a></span></span><span class='period'>.</span><span class='id identifier
|
|
265
|
-
</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
|
|
274
|
+
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_price'>price</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="top-level-namespace.html#Money-constant" title="Money (constant)">Money</a></span></span><span class='period'>.</span><span class='id identifier rubyid_from'>from</span><span class='lparen'>(</span><span class='int'>10</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>"</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
|
|
275
|
+
</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>
|
|
266
276
|
<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>
|
|
267
277
|
</code></pre>
|
|
268
278
|
<p><strong>Good fit:</strong> Application code, especially Rails apps.
|
|
@@ -276,7 +286,7 @@
|
|
|
276
286
|
<p>MIT</p></div></div>
|
|
277
287
|
|
|
278
288
|
<div id="footer">
|
|
279
|
-
Generated on
|
|
289
|
+
Generated on Tue Jun 16 20:22:19 2026 by
|
|
280
290
|
<a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
|
|
281
291
|
0.9.44 (ruby-4.0.5).
|
|
282
292
|
</div>
|