minting 1.8.2 → 1.9.0

data/doc/method_list.html

@@ -145,7 +145,7 @@
 
   <li class="odd ">
     <div class="item">
-      <span class='object_link'><a href="Mint/Money.html#change-instance_method" title="Mint::Money#change (method)">#change</a></span>
+      <span class='object_link'><a href="Mint/Money.html#clamp-instance_method" title="Mint::Money#clamp (method)">#clamp</a></span>
       <small>Mint::Money</small>
     </div>
   </li>
@@ -153,23 +153,23 @@
 
   <li class="even ">
     <div class="item">
-      <span class='object_link'><a href="Mint/Money.html#clamp-instance_method" title="Mint::Money#clamp (method)">#clamp</a></span>
-      <small>Mint::Money</small>
+      <span class='object_link'><a href="Mint/Currency.html#code-instance_method" title="Mint::Currency#code (method)">#code</a></span>
+      <small>Mint::Currency</small>
     </div>
   </li>
   
 
   <li class="odd ">
     <div class="item">
-      <span class='object_link'><a href="Mint/Currency.html#code-instance_method" title="Mint::Currency#code (method)">#code</a></span>
-      <small>Mint::Currency</small>
+      <span class='object_link'><a href="Mint/Money.html#coerce-instance_method" title="Mint::Money#coerce (method)">#coerce</a></span>
+      <small>Mint::Money</small>
     </div>
   </li>
   
 
   <li class="even ">
     <div class="item">
-      <span class='object_link'><a href="Mint/Money.html#coerce-instance_method" title="Mint::Money#coerce (method)">#coerce</a></span>
+      <span class='object_link'><a href="Mint/Money.html#copy_with-instance_method" title="Mint::Money#copy_with (method)">#copy_with</a></span>
       <small>Mint::Money</small>
     </div>
   </li>
@@ -289,7 +289,7 @@
 
   <li class="odd ">
     <div class="item">
-      <span class='object_link'><a href="Mint/Money.html#from_fractional-class_method" title="Mint::Money.from_fractional (method)">from_fractional</a></span>
+      <span class='object_link'><a href="Mint/Money.html#from_subunits-class_method" title="Mint::Money.from_subunits (method)">from_subunits</a></span>
       <small>Mint::Money</small>
     </div>
   </li>
@@ -343,7 +343,7 @@
   </li>
   
 
-  <li class="even ">
+  <li class="even deprecated">
     <div class="item">
       <span class='object_link'><a href="Mint/Money.html#mint-instance_method" title="Mint::Money#mint (method)">#mint</a></span>
       <small>Mint::Money</small>
@@ -377,7 +377,7 @@
 
   <li class="even ">
     <div class="item">
-      <span class='object_link'><a href="Mint/Money.html#nonzero%3F-instance_method" title="Mint::Money#nonzero? (method)">#nonzero?</a></span>
+      <span class='object_link'><a href="Mint/Money.html#no_currency-class_method" title="Mint::Money.no_currency (method)">no_currency</a></span>
       <small>Mint::Money</small>
     </div>
   </li>
@@ -385,31 +385,31 @@
 
   <li class="odd ">
     <div class="item">
-      <span class='object_link'><a href="Mint/Currency.html#normalize_amount-instance_method" title="Mint::Currency#normalize_amount (method)">#normalize_amount</a></span>
-      <small>Mint::Currency</small>
+      <span class='object_link'><a href="Mint/Money.html#nonzero%3F-instance_method" title="Mint::Money#nonzero? (method)">#nonzero?</a></span>
+      <small>Mint::Money</small>
     </div>
   </li>
   
 
   <li class="even ">
     <div class="item">
-      <span class='object_link'><a href="Mint.html#parse-instance_method" title="Mint#parse (method)">#parse</a></span>
-      <small>Mint</small>
+      <span class='object_link'><a href="Mint/Currency.html#normalize_amount-instance_method" title="Mint::Currency#normalize_amount (method)">#normalize_amount</a></span>
+      <small>Mint::Currency</small>
     </div>
   </li>
   
 
   <li class="odd ">
     <div class="item">
-      <span class='object_link'><a href="Mint/Money.html#parse-class_method" title="Mint::Money.parse (method)">parse</a></span>
-      <small>Mint::Money</small>
+      <span class='object_link'><a href="Mint.html#parse-instance_method" title="Mint#parse (method)">#parse</a></span>
+      <small>Mint</small>
     </div>
   </li>
   
 
   <li class="even ">
     <div class="item">
-      <span class='object_link'><a href="Mint/Money.html#parse!-class_method" title="Mint::Money.parse! (method)">parse!</a></span>
+      <span class='object_link'><a href="Mint/Money.html#parse-class_method" title="Mint::Money.parse (method)">parse</a></span>
       <small>Mint::Money</small>
     </div>
   </li>
@@ -425,7 +425,7 @@
 
   <li class="even ">
     <div class="item">
-      <span class='object_link'><a href="Mint/Money.html#positive%3F-instance_method" title="Mint::Money#positive? (method)">#positive?</a></span>
+      <span class='object_link'><a href="Mint/Money.html#parse!-class_method" title="Mint::Money.parse! (method)">parse!</a></span>
       <small>Mint::Money</small>
     </div>
   </li>
@@ -433,16 +433,16 @@
 
   <li class="odd ">
     <div class="item">
-      <span class='object_link'><a href="Mint/Currency.html#priority-instance_method" title="Mint::Currency#priority (method)">#priority</a></span>
-      <small>Mint::Currency</small>
+      <span class='object_link'><a href="Mint/Money.html#positive%3F-instance_method" title="Mint::Money#positive? (method)">#positive?</a></span>
+      <small>Mint::Money</small>
     </div>
   </li>
   
 
   <li class="even ">
     <div class="item">
-      <span class='object_link'><a href="Mint/Registry.html#register-class_method" title="Mint::Registry.register (method)">register</a></span>
-      <small>Mint::Registry</small>
+      <span class='object_link'><a href="Mint/Currency.html#priority-instance_method" title="Mint::Currency#priority (method)">#priority</a></span>
+      <small>Mint::Currency</small>
     </div>
   </li>
   
@@ -456,6 +456,14 @@
   
 
   <li class="even ">
+    <div class="item">
+      <span class='object_link'><a href="Mint/Registry.html#register-class_method" title="Mint::Registry.register (method)">register</a></span>
+      <small>Mint::Registry</small>
+    </div>
+  </li>
+  
+
+  <li class="odd ">
     <div class="item">
       <span class='object_link'><a href="Mint/Currency.html#resolve-class_method" title="Mint::Currency.resolve (method)">resolve</a></span>
       <small>Mint::Currency</small>
@@ -463,7 +471,7 @@
   </li>
   
 
-  <li class="odd ">
+  <li class="even ">
     <div class="item">
       <span class='object_link'><a href="Mint/Currency.html#resolve!-class_method" title="Mint::Currency.resolve! (method)">resolve!</a></span>
       <small>Mint::Currency</small>
@@ -471,7 +479,7 @@
   </li>
   
 
-  <li class="even ">
+  <li class="odd ">
     <div class="item">
       <span class='object_link'><a href="Mint/Money.html#same_currency%3F-instance_method" title="Mint::Money#same_currency? (method)">#same_currency?</a></span>
       <small>Mint::Money</small>
@@ -479,7 +487,7 @@
   </li>
   
 
-  <li class="odd ">
+  <li class="even ">
     <div class="item">
       <span class='object_link'><a href="Mint/Money.html#split-instance_method" title="Mint::Money#split (method)">#split</a></span>
       <small>Mint::Money</small>
@@ -487,7 +495,7 @@
   </li>
   
 
-  <li class="even ">
+  <li class="odd ">
     <div class="item">
       <span class='object_link'><a href="Mint/RangeStepPatch.html#step-instance_method" title="Mint::RangeStepPatch#step (method)">#step</a></span>
       <small>Mint::RangeStepPatch</small>
@@ -495,7 +503,7 @@
   </li>
   
 
-  <li class="odd ">
+  <li class="even ">
     <div class="item">
       <span class='object_link'><a href="Mint/Currency.html#subunit-instance_method" title="Mint::Currency#subunit (method)">#subunit</a></span>
       <small>Mint::Currency</small>
@@ -503,6 +511,14 @@
   </li>
   
 
+  <li class="odd ">
+    <div class="item">
+      <span class='object_link'><a href="Mint/Money.html#subunits-instance_method" title="Mint::Money#subunits (method)">#subunits</a></span>
+      <small>Mint::Money</small>
+    </div>
+  </li>
+  
+
   <li class="even ">
     <div class="item">
       <span class='object_link'><a href="Mint/Money.html#succ-instance_method" title="Mint::Money#succ (method)">#succ</a></span>
@@ -609,31 +625,31 @@
 
   <li class="odd ">
     <div class="item">
-      <span class='object_link'><a href="Mint.html#world_currencies-class_method" title="Mint.world_currencies (method)">world_currencies</a></span>
-      <small>Mint</small>
+      <span class='object_link'><a href="Mint/Registry.html#world_currencies-class_method" title="Mint::Registry.world_currencies (method)">world_currencies</a></span>
+      <small>Mint::Registry</small>
     </div>
   </li>
   
 
   <li class="even ">
     <div class="item">
-      <span class='object_link'><a href="Mint/Registry.html#world_currencies-class_method" title="Mint::Registry.world_currencies (method)">world_currencies</a></span>
-      <small>Mint::Registry</small>
+      <span class='object_link'><a href="Mint.html#world_currencies-class_method" title="Mint.world_currencies (method)">world_currencies</a></span>
+      <small>Mint</small>
     </div>
   </li>
   
 
   <li class="odd ">
     <div class="item">
-      <span class='object_link'><a href="Mint/Money.html#zero-class_method" title="Mint::Money.zero (method)">zero</a></span>
-      <small>Mint::Money</small>
+      <span class='object_link'><a href="Mint/Currency.html#zero-class_method" title="Mint::Currency.zero (method)">zero</a></span>
+      <small>Mint::Currency</small>
     </div>
   </li>
   
 
   <li class="even ">
     <div class="item">
-      <span class='object_link'><a href="Mint/Currency.html#zero-class_method" title="Mint::Currency.zero (method)">zero</a></span>
+      <span class='object_link'><a href="Mint/Currency.html#zero-instance_method" title="Mint::Currency#zero (method)">#zero</a></span>
       <small>Mint::Currency</small>
     </div>
   </li>
@@ -641,8 +657,8 @@
 
   <li class="odd ">
     <div class="item">
-      <span class='object_link'><a href="Mint/Currency.html#zero-instance_method" title="Mint::Currency#zero (method)">#zero</a></span>
-      <small>Mint::Currency</small>
+      <span class='object_link'><a href="Mint/Money.html#zero-class_method" title="Mint::Money.zero (method)">zero</a></span>
+      <small>Mint::Money</small>
     </div>
   </li>
   

data/doc/top-level-namespace.html

@@ -141,7 +141,7 @@
 </div>
 
       <div id="footer">
-  Generated on Tue Jun 16 20:22:19 2026 by
+  Generated on Mon Jun 22 16:47:02 2026 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.44 (ruby-4.0.5).
 </div>

data/lib/minting/currency/currency.rb

@@ -40,8 +40,13 @@ module Mint
     # Normalizes numeric amounts for this currency
     # 1. Converts to Rational
     # 2. Rounds to respect currency subunit
-    def normalize_amount(amount) = Mint::Rounding.apply(amount, subunit)
+    def normalize_amount(amount) = amount.to_r.round(subunit)
 
+    # Returns the cached frozen zero-Money for this currency.
+    #
+    # @return [Money] a frozen zero-Money instance
+    # @example
+    #   Mint::Currency.for_code('USD').zero  #=> [USD 0.00]
     def zero = Registry.zero_for(self)
   end
 

data/lib/minting/mint/{locale_backend.rb → i18n.rb}

@@ -26,4 +26,31 @@ module Mint
     # @return [Proc, #call, nil]
     attr_accessor :locale_backend
   end
+
+  # @api private
+  class Money
+    private
+
+    # Resolves format/decimal/thousand from locale_backend when not explicitly given.
+    # @private
+    def resolve_locale_for(format, decimal, thousand)
+      locale = locale_backend
+
+      [format || locale[:format] || '%<symbol>s%<amount>f',
+       decimal || locale[:decimal] || '.',
+       thousand.nil? ? (locale[:thousand] || ',') : thousand]
+    end
+
+    def locale_backend
+      case bk = Mint.locale_backend
+      when Hash     then bk
+      when NilClass then {}
+      else
+        return bk.call if bk.respond_to?(:call)
+
+        warn "ignoring invalid locale_backend: #{bk.inspect}"
+        {}
+      end
+    end
+  end
 end

data/lib/minting/mint/mint.rb

@@ -24,9 +24,18 @@ module Mint
   # Restores the previous mode (or default) when the block exits, even on
   # exception.
   #
+  # Rounding-mode support is loaded lazily on first call. Once loaded,
+  # +Currency#normalize_amount+ is patched to dispatch through the
+  # rounding module, adding ~10–35&ns of overhead to every money creation
+  # or mutation. When rounding modes are never used (the common case),
+  # the fast path incurs zero overhead.
+  #
   # @param mode [Symbol] one of: +:half_up+, +:half_down+, +:floor+,
   #   +:ceil+, +:truncate+, +:down+
   # @yield block to execute with the rounding mode active
   # @raise [ArgumentError] if +mode+ is not a recognised rounding mode
-  def self.with_rounding(mode, &) = Rounding.with_mode(mode, &)
+  def self.with_rounding(mode, &)
+    require_relative 'rounding' unless defined?(Mint::Rounding)
+    Rounding.with_mode(mode, &)
+  end
 end

data/lib/minting/mint/registry/zeros.rb

@@ -11,6 +11,8 @@ module Mint
     def self.zero_for(currency)
       raise ArgumentError, "Expect a Currency param. (#{currency})" unless currency.is_a?(Currency)
 
+      return @zeros[currency] if @zeros&.key?(currency)
+
       MUTEX.synchronize do
         @zeros ||= {}
         @zeros[currency] ||= Mint::Money.send(:new, 0r, currency)

data/lib/minting/mint/rounding.rb

@@ -24,12 +24,18 @@ module Mint
     end
 
     # Rounds +amount+ to +ndigits+ using the currently scoped rounding mode.
+    # Uses the fast path (+to_r.round+) when no custom mode is active.
     # @api private
     # @param amount [Numeric]
     # @param ndigits [Integer]
     # @return [Rational]
     def self.apply(amount, ndigits)
-      MODES.fetch(current_mode).call(amount.to_r, ndigits)
+      mode = Thread.current[:minting_rounding_mode]
+      if mode
+        MODES.fetch(mode).call(amount.to_r, ndigits)
+      else
+        amount.to_r.round(ndigits)
+      end
     end
 
     # Sets a rounding mode for the duration of a block, restoring the
@@ -49,3 +55,10 @@ module Mint
     end
   end
 end
+
+# When loaded, patch Currency to delegate rounding through this module.
+# Remove the default fast-path method first to avoid redefinition warnings.
+Mint::Currency.remove_method(:normalize_amount)
+Mint::Currency.define_method(:normalize_amount) do |amount|
+  Mint::Rounding.apply(amount, subunit)
+end

data/lib/minting/mint.rb

@@ -1,13 +1,12 @@
 # frozen_string_literal: true
 
-require_relative 'mint/rounding'
 require_relative 'currency/currency'
 
 require_relative 'mint/dsl/numeric'
 require_relative 'mint/dsl/range'
 require_relative 'mint/dsl/string'
 require_relative 'mint/dsl/top_level'
-require_relative 'mint/locale_backend'
+require_relative 'mint/i18n'
 require_relative 'mint/mint'
 require_relative 'mint/parser/parser'
 require_relative 'mint/parser/separators'

data/lib/minting/money/allocation/allocation.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Mint
-  # Allocation and splitting
+  # :nodoc:
   class Money
     # Proportionally allocates the monetary amount among a list of ratios.
     # Disperses any subunit rounding amounts across the initial slots

data/lib/minting/money/allocation/split.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Mint
-  # Allocation and splitting
+  # :nodoc:
   class Money
     # Splits the monetary amount into a given quantity of equal parts.
     # Disperses any fractional subunit rounding differences across the initial slots

data/lib/minting/money/arithmetics/methods.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Mint
-  # Money Arithmetics
+  # :nodoc:
   class Money
     # Returns the absolute value of the monetary amount as a new {Money} instance.
     #

data/lib/minting/money/arithmetics/operators.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Mint
-  # Money Arithmetics
+  # :nodoc:
   class Money
     # Performs addition with another {Money} instance or standard zero Numeric.
     #

data/lib/minting/money/clamp.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Mint
-  # Money clamp
+  # :nodoc:
   class Money
     # Constrains +self+ to the inclusive range [+min+, +max+].
     #
@@ -58,7 +58,7 @@ module Mint
       case boundary
       in NilClass | Numeric                then boundary
       in Money if same_currency?(boundary) then boundary.amount
-      in Money                             then raise ArgumentError, "oundary currency must be: #{currency_code}"
+      in Money                             then raise ArgumentError, "Boundary currency must be: #{currency_code}"
       else                                 raise ArgumentError, "Boundary must be Numeric or Money #{boundary}"
       end
     end

data/lib/minting/money/coercion.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Mint
-  # Implements the standard Ruby coercion protocol.
+  # :nodoc:
   class Money
     # Allows {Money} to interact seamlessly as the right-hand operand in Numeric arithmetic.
     # This enables expressions like `5 * money` where `5` is a Numeric and `money` is a Money object.

data/lib/minting/money/comparable.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Mint
-  # Comparison methods
+  # :nodoc:
   class Money
     include Comparable
 

data/lib/minting/money/constructors.rb

@@ -1,12 +1,15 @@
 # frozen_string_literal: true
 
 module Mint
-  # Money constructors
+  # :nodoc:
   class Money
     # Creates a new Money immutable object with the specified amount and currency
     # @param amount [Numeric] The monetary amount
     # @param currency [Currency, String] The currency code or currency object
+    # @return [Money] the new Money instance
     # @raise [ArgumentError] If amount is not numeric or currency is invalid
+    # @example
+    #   Money.from(10, 'USD')  #=> [USD 10.00]
     def self.from(amount, currency)
       raise ArgumentError, 'amount must be Numeric' unless amount.is_a?(Numeric)
 
@@ -68,29 +71,29 @@ module Mint
       from(amount, currency)
     end
 
-    # Builds a Money from a fractional (smallest-unit) Integer amount.
-    # This is the inverse of {#fractional}: for USD, the fractional unit is
+    # Builds a Money from a subunit (smallest-unit) Integer amount.
+    # This is the inverse of {#subunits}: for USD, the subunit is
     # 1 cent; for JPY it is 1 yen; for IQD it is 1 dinar (subunit 3).
     #
-    # @param fractional [Integer] the amount expressed in the currency's
+    # @param subunits [Integer] the amount expressed in the currency's
     #   smallest unit (e.g. cents). Must be an Integer to preserve exactness.
     # @param currency [String, Symbol, Currency] the currency identifier
     # @return [Money] the resulting Money instance
-    # @raise [ArgumentError] if +fractional+ is not an Integer or +currency+
+    # @raise [ArgumentError] if +subunits+ is not an Integer or +currency+
     #   is not registered
     #
     # @example USD cents
-    #   Money.from_fractional(123_456, 'USD') #=> [USD 1234.56]
+    #   Money.from_subunits(123_456, 'USD') #=> [USD 1234.56]
     # @example JPY (subunit 0)
-    #   Money.from_fractional(1234, 'JPY')    #=> [JPY 1234]
+    #   Money.from_subunits(1234, 'JPY')    #=> [JPY 1234]
     # @example Round trip
     #   m = Mint.money(9.99, 'USD')
-    #   Money.from_fractional(m.fractional, 'USD') == m #=> true
-    def self.from_fractional(fractional, currency)
-      raise ArgumentError, 'fractional must be an Integer' unless fractional.is_a?(Integer)
+    #   Money.from_subunits(m.subunits, 'USD') == m #=> true
+    def self.from_subunits(subunits, currency)
+      raise ArgumentError, 'subunits must be an Integer' unless subunits.is_a?(Integer)
 
       currency = Currency.resolve!(currency)
-      amount = Rational(fractional, currency.fractional_multiplier)
+      amount = Rational(subunits, currency.fractional_multiplier)
       amount.zero? ? currency.zero : new(amount, currency)
     end
 
@@ -116,6 +119,13 @@ module Mint
       end
     end
 
+    # Returns a new Money with the given amount in the same currency.
+    #
+    # @deprecated Use {#copy_with} instead. Will be removed in v2.
+    # @param new_amount [Numeric] the new monetary amount
+    # @return [Money] a new Money instance, or self if unchanged
+    # @example
+    #   Mint.money(10, 'USD').mint(15)  #=> [USD 15.00]
     def mint(new_amount)
       warn 'Money#mint is now deprecated and will be removed in v2'
       copy_with(amount: new_amount)

data/lib/minting/money/conversion.rb

@@ -4,7 +4,7 @@ require 'bigdecimal'
 require 'erb'
 
 module Mint
-  # Conversion and serialization logic for {Money} instances.
+  # :nodoc:
   class Money
     # Converts the monetary amount to a BigDecimal object.
     #