minting 1.9.4 → 1.9.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e784f15a78d9890f02c3b44c95ab975bd8a12647c27d87531059603fa0e5cab5
-  data.tar.gz: 83e28899e8e8cedcd98a93fd2b787470485d8f440ba82f63138499dc1ba33c20
+  metadata.gz: 51f0a76084db98e53f29af4f82f1284f749c9691727a7a84a7f8cc758d1a9f67
+  data.tar.gz: f24a130df454ee80f923aa42fd995e4b3eaf2f4f16d1a6f3a9e84548c08a4988
 SHA512:
-  metadata.gz: dc823a1170e16ae3ef0751d2e35200b681e89c42d8480d7dfb6117c9f7b6dbe8b6d5cec2fa47a57755e0f52eeb0324a5dd560a359729307aa19186625490f6fc
-  data.tar.gz: a281aae01fc2e2472c0697ea02f6d68f21c64ecb9acb9c8704a70bba35a8e7dafa0523f8d6696c93c818c67488c81c6c2b3d117cc48a5f0720eeaaa31607dac1
+  metadata.gz: 42ed5e90ba4a936426344cfd1f8aad69755038704c53b67d8f714ced040661e2f37829aa44d2d67f12575596656b7d9bd5b80058995b57875aaa46b2cf6dd291
+  data.tar.gz: a6490a3356b949df6889e72ee3fc885a4e10af8d14e09591d7bd615ea468371c30b1695b73e996cb91526ab824a610e2667797eb24e94144ec46ddd22dc42395

data/README.md

@@ -57,9 +57,6 @@ require 'minting'
 # Create money
 ten = Mint.money(10, 'USD')            #=> [USD 10.00]
 
-# Create money using Numeric refinements
-using Mint
-
 1.dollar == Mint.money(1, 'USD') #=> true
 ten = 10.dollars                 #=> [USD 10.00]
 4.to_money('USD')                #=> [USD 4.00]
@@ -83,43 +80,43 @@ price = Mint.money(9.99, 'USD')
 loss  = Mint.money(-1234.56, 'USD')
 
 # Built-in named presets
-loss.to_formatted_s(:accounting)                      #=> "($1,234.56)"
-Mint.money(1234.56, 'EUR').to_formatted_s(:european)  #=> "1.234,56 €"
-price.to_formatted_s(:amount)                         #=> "9.99"
-price.to_formatted_s(:currency)                       #=> "USD 9.99"
+loss.format(:accounting)                      #=> "($1,234.56)"
+Mint.money(1234.56, 'EUR').format(:european)  #=> "1.234,56 €"
+price.format(:amount)                         #=> "9.99"
+price.format(:currency)                       #=> "USD 9.99"
 
 # Presets can be overridden with explicit kwargs
-Mint.money(1234.56, 'EUR').to_formatted_s(:european, format: '%<amount>f %<currency>s')
+Mint.money(1234.56, 'EUR').format(:european, format: '%<amount>f %<currency>s')
 #=> "1.234,56 EUR"
 
 # Or use direct format strings
-price.to_formatted_s                                  #=> "$9.99",
-price.to_formatted_s(format: '%<amount>d')            #=> "9",
-price.to_formatted_s(format: '%<symbol>s%<amount>f')  #=> "$9.99",
-price.to_formatted_s(format: '%<symbol>s%<amount>+f') #=> "$+9.99",
-(-price).to_formatted_s(format: '%<amount>f')         #=> "-9.99",
+price.format                                  #=> "$9.99",
+price.format(format: '%<amount>d')            #=> "9",
+price.format(format: '%<symbol>s%<amount>f')  #=> "$9.99",
+price.format(format: '%<symbol>s%<amount>+f') #=> "$+9.99",
+(-price).format(format: '%<amount>f')         #=> "-9.99",
 
 # Format with padding
 price_in_euros = Mint.money(12.34, 'EUR')
 
-price.to_formatted_s(format: '--%<amount>7d')               #=> "--      9"
-price.to_formatted_s(format: '  %<amount>10f %<currency>s') #=> "        9.99 USD"
-(-price).to_formatted_s(format: '  %<amount>10f')           #=> "       -9.99"
+price.format(format: '--%<amount>7d')               #=> "--      9"
+price.format(format: '  %<amount>10f %<currency>s') #=> "        9.99 USD"
+(-price).format(format: '  %<amount>10f')           #=> "       -9.99"
 
-price_in_euros.to_formatted_s(format: '%<symbol>2s%<amount>+10f')    #=> " €    +12.34"
+price_in_euros.format(format: '%<symbol>2s%<amount>+10f')    #=> " €    +12.34"
 
 # Integral & fractional parts
-price.to_formatted_s(format: '%<integral>d %<fractional>d/100')        #=> "9 99/100"
-Mint.money(0.99, 'USD').to_fs(format: '%<integral>d dollars and %<fractional>02d cents')
+price.format(format: '%<integral>d %<fractional>d/100')        #=> "9 99/100"
+Mint.money(0.99, 'USD').format(format: '%<integral>d dollars and %<fractional>02d cents')
 #=> "0 dollars and 99 cents"
 
 # Per-sign Hash format (e.g. accounting parentheses for losses)
 loss = Mint.money(-1234.56, 'USD')
-loss.to_formatted_s(format: { negative: '(%<symbol>s%<amount>f)' })  #=> "($1,234.56)"
-Mint.money(0, 'BRL').to_formatted_s(format: { zero: '--' })          #=> "--"
+loss.format(format: { negative: '(%<symbol>s%<amount>f)' })  #=> "($1,234.56)"
+Mint.money(0, 'BRL').format(format: { zero: '--' })          #=> "--"
 # All three keys at once:
 fmt = { positive: '%<symbol>s%<amount>f', negative: '(%<symbol>s%<amount>f)', zero: '--' }
-Mint.money(1234.56, 'USD').to_formatted_s(format: fmt)               #=> "$1,234.56"
+Mint.money(1234.56, 'USD').format(format: fmt)               #=> "$1,234.56"
 
 # Json serialization
 
@@ -213,8 +210,6 @@ Modes: `:half_up` (default), `:half_down`, `:floor`, `:ceil`, `:truncate`, `:dow
 
 > **Performance note:** Rounding-mode support is not loaded by default — `require 'minting'` uses the fastest possible rounding (equivalent to `:half_up`) with zero dispatch overhead. The first call to `Mint.with_rounding` loads the rounding module and patches `Currency#normalize_amount`, adding ~10–35 ns per money creation or mutation. If your application never uses custom rounding modes (the common case), there is **no performance cost**.
 
-**Refinements** — `10.dollars` and similar helpers require `using Mint` in the current scope (see Usage above).
-
 **Division** — `money / 5` returns new `Money`; `money / other_money` returns a numeric ratio, not money.
 
 **Zero equality** — Any zero amount is considered equal across currencies and to numeric zero (`Mint.money(0, 'USD') == Mint.money(0, 'EUR')` is intentionally `true`). Non-zero amounts must match currency and value.

data/lib/minting/currency/currency.rb

@@ -88,9 +88,11 @@ module Mint
   #
   # @param object [String, Currency, Money, nil] a currency code, object, or +nil+
   # @return [Currency] the resolved Currency
-  # @raise [ArgumentError] if +object+ cannot be resolved into a registered currency
+  # @raise [Mint::UnknownCurrency] if +object+ cannot be resolved into a
+  #   registered currency. +Mint::UnknownCurrency+ inherits from +ArgumentError+,
+  #   so existing +rescue ArgumentError+ handlers continue to work.
   def Currency.resolve!(object)
-    resolve(object) or raise ArgumentError, "Could not resolve (#{object}) into a currency"
+    resolve(object) or raise Mint::UnknownCurrency, "Could not resolve (#{object}) into a currency"
   end
 
   # Looks up a registered currency by its alpha code.
@@ -114,6 +116,6 @@ module Mint
   #
   # @param currency [String, Currency] a currency code or object
   # @return [Money] a frozen zero-Money
-  # @raise [ArgumentError] if the currency can't be resolved
+  # @raise [Mint::UnknownCurrency] if the currency can't be resolved
   def Currency.zero(currency) = Registry.zero_for(Currency.resolve!(currency))
 end

data/lib/minting/mint/dsl/numeric.rb

@@ -1,23 +1,21 @@
 # frozen_string_literal: true
 
-# Mint Numeric refinements
-module Mint
-  refine Numeric do
-    # @return [Money] self interpreted as BRL
-    def reais = Mint::Money.from(self, 'BRL')
+# Core extension: adds money-conversion helpers to Numeric.
+class Numeric
+  # @return [Money] self interpreted as BRL
+  def reais = Mint::Money.from(self, 'BRL')
 
-    # @return [Money] self interpreted as USD
-    def dollars = Mint::Money.from(self, 'USD')
+  # @return [Money] self interpreted as USD
+  def dollars = Mint::Money.from(self, 'USD')
 
-    # @return [Money] self interpreted as EUR
-    def euros = Mint::Money.from(self, 'EUR')
+  # @return [Money] self interpreted as EUR
+  def euros = Mint::Money.from(self, 'EUR')
 
-    # @param currency [String, Symbol, Currency] target currency
-    # @return [Money] self interpreted as the given currency
-    def to_money(currency) = Mint::Money.from(self, currency)
+  # @param currency [String, Symbol, Currency] target currency
+  # @return [Money] self interpreted as the given currency
+  def to_money(currency) = Mint::Money.from(self, currency)
 
-    alias_method :dollar, :dollars
-    alias_method :euro, :euros
-    alias_method :mint, :to_money
-  end
+  alias dollar dollars
+  alias euro euros
+  alias mint to_money
 end

data/lib/minting/mint/dsl/string.rb

@@ -1,12 +1,10 @@
 # frozen_string_literal: true
 
-# Mint String refinement
-module Mint
-  refine String do
-    # Parses self as a numeric string and creates a Money in the given currency.
-    #
-    # @param currency [String, Symbol, Currency] target currency
-    # @return [Money]
-    def to_money(currency) = Mint::Money.from(to_r, currency)
-  end
+# Core extension: adds money-parsing helper to String.
+class String
+  # Parses self as a numeric string and creates a Money in the given currency.
+  #
+  # @param currency [String, Symbol, Currency] target currency
+  # @return [Money]
+  def to_money(currency = nil) = Mint::Money.parse(self, currency)
 end

data/lib/minting/mint/mint.rb

@@ -2,16 +2,24 @@
 
 # Mint currency registration and factory (public API)
 module Mint
-  # Unknown currency excpetion
-  class UnknownCurrency < StandardError
+  # Raised when a currency cannot be resolved from a code or object.
+  #
+  # Inherits from +ArgumentError+ so existing +rescue ArgumentError+ handlers
+  # continue to work; rescue +Mint::UnknownCurrency+ for the specific case.
+  class UnknownCurrency < ArgumentError
   end
 
   # Creates a new {Money} instance with the given amount and currency code.
   #
   # @param amount [Numeric] the financial value
-  # @param currency_code [Currency, String] Currency code
+  # @param currency_code [String, Currency, Money, nil] Currency code, object,
+  #   Money whose currency to reuse, or +nil+. Passed through
+  #   {Mint::Currency.resolve!} so all accepted types resolve to a registered
+  #   currency.
   # @return [Money] the instantiated Money object
-  # @raise [ArgumentError] if the currency code is not registered
+  # @raise [ArgumentError] if the amount is not a Numeric
+  # @raise [Mint::UnknownCurrency] if the currency code is not registered.
+  #   +Mint::UnknownCurrency+ inherits from +ArgumentError+.
   def self.money(amount, currency_code) = Money.from(amount, currency_code)
 
   # @return [Hash{String => Currency}] the frozen world-currencies hash

data/lib/minting/money/constructors.rb

@@ -7,7 +7,8 @@ module Mint
     # @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
+    # @raise [ArgumentError] If amount is not numeric
+    # @raise [Mint::UnknownCurrency] If currency cannot be resolved
     # @example
     #   Money.from(10, 'USD')  #=> [USD 10.00]
     def self.from(amount, currency)
@@ -61,16 +62,9 @@ module Mint
     #
     # @param currency [String, Currency] a currency code or object
     # @return [Money] a frozen zero-Money
-    # @raise [ArgumentError] if the currency can't be resolved
+    # @raise [Mint::UnknownCurrency] if the currency can't be resolved
     def self.zero(currency) = Currency.resolve!(currency).zero
 
-    # Backwards-compatible alias for previous API
-    # TODO: deprecate in a future major release
-    def self.create(amount, currency)
-      warn 'Money.create is now deprecated. Use Money.from'
-      from(amount, currency)
-    end
-
     # 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).
@@ -79,8 +73,8 @@ module Mint
     #   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 +subunits+ is not an Integer or +currency+
-    #   is not registered
+    # @raise [ArgumentError] if +subunits+ is not an Integer
+    # @raise [Mint::UnknownCurrency] if +currency+ is not registered
     #
     # @example USD cents
     #   Money.from_subunits(123_456, 'USD') #=> [USD 1234.56]

data/lib/minting/money/conversion.rb

@@ -26,7 +26,7 @@ module Mint
     # @return [String] HTML5 `<data>` representation
     def to_html(format = DEFAULT_FORMAT)
       title = Kernel.format("#{currency_code} %0.#{currency.subunit}f", amount)
-      body = to_formatted_s(format: format)
+      body = format(format: format)
       %(<data class='money' title='#{title}'>#{ERB::Util.html_escape(body)}</data>)
     end
 

data/lib/minting/money/format/formatting.rb

@@ -33,10 +33,10 @@ module Mint
     # @private
     def validate_separators!(decimal:, thousand:)
       case decimal
-      when '' then raise ArgumentError, 'decimal must be a non-empty'
-      when nil # :noop
-      when String
-        raise ArgumentError, "decimal and thousand cannot be identical: #{decimal.inspect}" if decimal == thousand
+      when nil      # :noop
+      when ''       then raise ArgumentError, 'decimal must be a non-empty'
+      when thousand then raise ArgumentError, "decimal and thousand cannot be identical: #{decimal.inspect}"
+      when String   # :noop
       else raise ArgumentError, "decimal must be a String, false, or nil, got #{decimal.inspect}"
       end
 
@@ -62,13 +62,7 @@ module Mint
       subunit = currency.subunit
       resolved_format, adjusted_amount = resolve_format(format)
 
-      # Inject the currency's subunit precision into %<amount>f specifiers
-      # e.g. '%<amount>f' becomes '%<amount>.2f' for USD
-      resolved_format = resolved_format.gsub(/%<amount>(\s*\+?\d*)f/, "%<amount>\\1.#{subunit}f")
-
-      # Zero-subunit currencies (e.g. JPY) have no fractional part —
-      # strip %<fractional>d specifiers entirely since there's no valid integer for "nothing"
-      resolved_format.gsub!(/%<fractional>[^%]*?d/, '') if subunit.zero?
+      resolved_format = inject_subunit_precision(resolved_format, subunit)
 
       result = Kernel.format(resolved_format, {
                                amount: adjusted_amount,
@@ -86,5 +80,18 @@ module Mint
       # Apply thousands only to the integral portion, using the decimal as boundary
       apply_thousand_separator(result, decimal:, thousand:)
     end
+
+    # Injects the currency's subunit precision into %<amount>f specifiers
+    # (e.g. '%<amount>f' → '%<amount>.2f' for USD). For zero-subunit
+    # currencies (e.g. JPY), strips %<fractional>d specifiers.
+    # @private
+    def inject_subunit_precision(template, subunit)
+      cache ||= {}
+      cache[[template, subunit]] ||= begin
+        result = template.gsub(/%<amount>(\s*\+?\d*)f/, "%<amount>\\1.#{subunit}f")
+        result.gsub!(/%<fractional>[^%]*?d/, '') if subunit.zero?
+        result.freeze
+      end
+    end
   end
 end

data/lib/minting/money/format/to_s.rb

@@ -22,7 +22,7 @@ module Mint
     #   holding a format string. A Hash is convenient for sign-aware formats
     #   such as accounting parentheses:
     #
-    #     money.to_formatted_s(format: { negative: '(%<symbol>s%<amount>f)' })
+    #     money.format(format: { negative: '(%<symbol>s%<amount>f)' })
     #
     #   Missing keys fall back to the module default, so a Hash with only
     #   :negative will still format positives sensibly. The valid keys are
@@ -41,42 +41,42 @@ module Mint
     #
     # @example Basic formatting
     #   money = Mint.money(1234.56, 'USD')
-    #   money.to_formatted_s                               #=> "$1,234.56"
-    #   money.to_formatted_s(thousand: '.', decimal: ',')  #=> "$1.234,56"
-    #   money.to_formatted_s(decimal: ',', thousand: '')   #=> "$1234,56"
+    #   money.format                               #=> "$1,234.56"
+    #   money.format(thousand: '.', decimal: ',')  #=> "$1.234,56"
+    #   money.format(decimal: ',', thousand: '')   #=> "$1234,56"
     #
     # @example Preset formats
     #   loss = Mint.money(-1234.56, 'USD')
-    #   loss.to_formatted_s(:accounting)                   #=> "($1,234.56)"
-    #   money.to_formatted_s(:european)                    #=> "1.234,56 €"
-    #   money.to_formatted_s(:amount)                      #=> "1234.56"
-    #   money.to_formatted_s(:currency)                    #=> "USD 1234.56"
+    #   loss.format(:accounting)                   #=> "($1,234.56)"
+    #   money.format(:european)                    #=> "1.234,56 €"
+    #   money.format(:amount)                      #=> "1234.56"
+    #   money.format(:currency)                    #=> "USD 1234.56"
     #
     # @example Custom formats
-    #   money.to_formatted_s(format: '%<amount>f')                    #=> "1234.56"
-    #   money.to_formatted_s(format: '%<currency>s %<amount>f')       #=> "USD 1234.56"
-    #   money.to_formatted_s(format: '%<amount>f %<symbol>s')         #=> "1234.56 $"
-    #   money.to_formatted_s(format: '%<symbol>s%<amount>+f')         #=> "$+1234.56"
+    #   money.format(format: '%<amount>f')                    #=> "1234.56"
+    #   money.format(format: '%<currency>s %<amount>f')       #=> "USD 1234.56"
+    #   money.format(format: '%<amount>f %<symbol>s')         #=> "1234.56 $"
+    #   money.format(format: '%<symbol>s%<amount>+f')         #=> "$+1234.56"
     #
     # @example Integral & fractional parts
-    #   money.to_formatted_s(format: '%<integral>d.%<fractional>02d')  #=> "1234.56"
+    #   money.format(format: '%<integral>d.%<fractional>02d')  #=> "1234.56"
     #   price = Mint.money(0.99, 'USD')
-    #   price.to_formatted_s(format: '%<integral>d dollars and %<fractional>02d cents')
+    #   price.format(format: '%<integral>d dollars and %<fractional>02d cents')
     #   #=> "0 dollars and 99 cents"
     #
     # @example Per-sign Hash format (accounting parentheses)
     #   loss = Mint.money(-1234.56, 'USD')
-    #   loss.to_formatted_s(format: { negative: '(%<symbol>s%<amount>f)' }) #=> "($1,234.56)"
-    #   Mint.money(0, 'BRL').to_formatted_s(format: { zero: '--' })        #=> "--"
+    #   loss.format(format: { negative: '(%<symbol>s%<amount>f)' }) #=> "($1,234.56)"
+    #   Mint.money(0, 'BRL').format(format: { zero: '--' })        #=> "--"
     #
     # @example Padding and alignment
-    #   money.to_formatted_s(format: '%<amount>10.2f')                #=> "   1234.56"
-    #   money.to_formatted_s(format: '%<symbol>s%<amount>010.2f')     #=> "$0001234.56"
+    #   money.format(format: '%<amount>10.2f')                #=> "   1234.56"
+    #   money.format(format: '%<symbol>s%<amount>010.2f')     #=> "$0001234.56"
     #
     # @example Locale-aware formatting (with Mint.locale_backend set)
-    #   money.to_formatted_s  # decimal and thousand come from locale_backend
+    #   money.format  # decimal and thousand come from locale_backend
     #
-    def to_formatted_s(preset = nil, format: nil, decimal: nil, thousand: nil, width: nil)
+    def format(preset = nil, format: nil, decimal: nil, thousand: nil, width: nil)
       if preset
         config = PRESETS.fetch(preset) { raise ArgumentError, "Unknown format preset: #{preset.inspect}" }
         format ||= config[:format]
@@ -101,8 +101,8 @@ module Mint
       width ? formatted.rjust(width) : formatted
     end
 
-    def to_s = to_formatted_s
+    def to_s = format
 
-    alias to_fs to_formatted_s
+    alias to_fs :format
   end
 end

data/lib/minting/version.rb

@@ -3,5 +3,5 @@
 # Root namespace for the Minting library.
 module Minting
   # Current version of the Minting gem.
-  VERSION = '1.9.4'
+  VERSION = '1.9.6'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: minting
 version: !ruby/object:Gem::Version
-  version: 1.9.4
+  version: 1.9.6
 platform: ruby
 authors:
 - Gilson Ferraz