minting 1.0.1 → 1.1.1

data/lib/minting/mint/registry.rb

@@ -1,13 +1,24 @@
-# :nodoc
+require 'yaml'
+
 module Mint
+  # Creates a new {Money} instance with the given amount and currency code.
+  #
+  # @param amount [Numeric] the financial value
+  # @param currency_code [String, Symbol] the ISO currency code or symbol
+  # @return [Money] the instantiated Money object
+  # @raise [ArgumentError] if the currency code is not registered
   def self.money(amount, currency_code)
     currency = currency(currency_code)
-    return Money.new(amount, currency).freeze if currency
+    return Money.new(amount, currency) if currency
 
-    available = currencies.keys.join(', ')
-    raise ArgumentError, "Currency [#{currency_code}] not registered. Available: #{available}"
+    raise ArgumentError, "Currency [#{currency_code}] not registered. Check Mint.currencies"
   end
 
+  # Finds a registered currency by its code, symbol,
+  # or retrieves it directly if already a Currency object.
+  #
+  # @param currency [String, Symbol, Currency] the currency identifier or object
+  # @return [Currency, nil] the registered Currency instance or nil if not found
   def self.currency(currency)
     case currency
     when Currency
@@ -19,12 +30,29 @@ module Mint
     end
   end
 
-  def self.register_currency(code, subunit: 2, symbol: '$')
+  # Registers a new currency if not already registered.
+  #
+  # @param code [String, Symbol] the unique currency code (e.g. 'USD', :EUR)
+  # @param subunit [Integer] the decimal subunit precision (defaults to 2)
+  # @param symbol [String] the display symbol (defaults to '$')
+  # @param priority [Integer] parser precedence priority (defaults to 0)
+  # @return [Currency] the registered or existing Currency instance
+  # @raise [ArgumentError] if the code layout is invalid or register throws an error
+  def self.register_currency(code:, subunit: 2, symbol: '$', priority: 0)
     code = code.to_s
-    currencies[code] || register_currency!(code, subunit: subunit, symbol: symbol)
+    currencies[code] || register_currency!(code:, subunit:, symbol:, priority:)
   end
 
-  def self.register_currency!(code, subunit:, symbol: '')
+  # Strictly registers a new currency, raising a KeyError if already registered.
+  #
+  # @param code [String, Symbol] the unique currency code
+  # @param subunit [Integer] the decimal subunit precision
+  # @param symbol [String] the display symbol
+  # @param priority [Integer] parser precedence priority
+  # @return [Currency] the newly registered Currency instance
+  # @raise [ArgumentError] if the code contains invalid characters
+  # @raise [KeyError] if the currency code is already registered
+  def self.register_currency!(code:, subunit:, symbol: '', priority: 0)
     code = code.to_s
     unless code.match?(/^[A-Z_]+$/)
       raise ArgumentError,
@@ -35,142 +63,49 @@ module Mint
             "Currency: #{code} already registered"
     end
 
-    currencies[code] =
-      Currency.new(code, subunit: subunit.to_i, symbol: symbol.to_s).freeze
+    currencies[code] = Currency.new(code:, subunit:, symbol:, priority:)
+    @currency_symbols = nil
+    currencies[code]
   end
 
+  # Returns the hash of all registered currencies.
+  #
+  # @return [Hash{String => Currency}] registered currencies mapped by code
   def self.currencies
-    @currencies ||= {
-      # Major Global Currencies
-      'USD' => Currency.new('USD', subunit: 2, symbol: '$'),
-      'EUR' => Currency.new('EUR', subunit: 2, symbol: '€'),
-      'GBP' => Currency.new('GBP', subunit: 2, symbol: '£'),
-      'JPY' => Currency.new('JPY', subunit: 0, symbol: '¥'),
-      'CHF' => Currency.new('CHF', subunit: 2, symbol: 'Fr'),
-      'CAD' => Currency.new('CAD', subunit: 2, symbol: '$'),
-      'AUD' => Currency.new('AUD', subunit: 2, symbol: '$'),
-      'CNY' => Currency.new('CNY', subunit: 2, symbol: '¥'),
-      'SEK' => Currency.new('SEK', subunit: 2, symbol: 'kr'),
-      'NZD' => Currency.new('NZD', subunit: 2, symbol: '$'),
-
-      # Asia-Pacific
-      'HKD' => Currency.new('HKD', subunit: 2, symbol: 'HK$'),
-      'SGD' => Currency.new('SGD', subunit: 2, symbol: 'S$'),
-      'KRW' => Currency.new('KRW', subunit: 0, symbol: '₩'),
-      'INR' => Currency.new('INR', subunit: 2, symbol: '₹'),
-      'THB' => Currency.new('THB', subunit: 2, symbol: '฿'),
-      'MYR' => Currency.new('MYR', subunit: 2, symbol: 'RM'),
-      'IDR' => Currency.new('IDR', subunit: 2, symbol: 'Rp'),
-      'PHP' => Currency.new('PHP', subunit: 2, symbol: '₱'),
-      'VND' => Currency.new('VND', subunit: 0, symbol: '₫'),
-      'TWD' => Currency.new('TWD', subunit: 2, symbol: 'NT$'),
-      'PKR' => Currency.new('PKR', subunit: 2, symbol: '₨'),
-      'BDT' => Currency.new('BDT', subunit: 2, symbol: '৳'),
-      'LKR' => Currency.new('LKR', subunit: 2, symbol: '₨'),
-      'NPR' => Currency.new('NPR', subunit: 2, symbol: '₨'),
-      'MMK' => Currency.new('MMK', subunit: 2, symbol: 'K'),
-      'KHR' => Currency.new('KHR', subunit: 2, symbol: '៛'),
-      'LAK' => Currency.new('LAK', subunit: 2, symbol: '₭'),
-      'BND' => Currency.new('BND', subunit: 2, symbol: 'B$'),
-
-      # Middle East & Central Asia
-      'AED' => Currency.new('AED', subunit: 2, symbol: 'د.إ'),
-      'SAR' => Currency.new('SAR', subunit: 2, symbol: '﷼'),
-      'QAR' => Currency.new('QAR', subunit: 2, symbol: '﷼'),
-      'KWD' => Currency.new('KWD', subunit: 3, symbol: 'د.ك'),
-      'BHD' => Currency.new('BHD', subunit: 3, symbol: '.د.ب'),
-      'OMR' => Currency.new('OMR', subunit: 3, symbol: '﷼'),
-      'JOD' => Currency.new('JOD', subunit: 3, symbol: 'د.ا'),
-      'ILS' => Currency.new('ILS', subunit: 2, symbol: '₪'),
-      'TRY' => Currency.new('TRY', subunit: 2, symbol: '₺'),
-      'IRR' => Currency.new('IRR', subunit: 2, symbol: '﷼'),
-      'IQD' => Currency.new('IQD', subunit: 3, symbol: 'د.ع'),
-      'AFN' => Currency.new('AFN', subunit: 2, symbol: '؋'),
-      'KZT' => Currency.new('KZT', subunit: 2, symbol: '₸'),
-      'UZS' => Currency.new('UZS', subunit: 2, symbol: 'лв'),
-      'KGS' => Currency.new('KGS', subunit: 2, symbol: 'лв'),
-      'TJS' => Currency.new('TJS', subunit: 2, symbol: 'SM'),
-
-      # Europe
-      'NOK' => Currency.new('NOK', subunit: 2, symbol: 'kr'),
-      'DKK' => Currency.new('DKK', subunit: 2, symbol: 'kr'),
-      'ISK' => Currency.new('ISK', subunit: 0, symbol: 'kr'),
-      'PLN' => Currency.new('PLN', subunit: 2, symbol: 'zł'),
-      'CZK' => Currency.new('CZK', subunit: 2, symbol: 'Kč'),
-      'HUF' => Currency.new('HUF', subunit: 2, symbol: 'Ft'),
-      'RON' => Currency.new('RON', subunit: 2, symbol: 'lei'),
-      'BGN' => Currency.new('BGN', subunit: 2, symbol: 'лв'),
-      'HRK' => Currency.new('HRK', subunit: 2, symbol: 'kn'),
-      'RSD' => Currency.new('RSD', subunit: 2, symbol: 'Дин.'),
-      'RUB' => Currency.new('RUB', subunit: 2, symbol: '₽'),
-      'UAH' => Currency.new('UAH', subunit: 2, symbol: '₴'),
-      'BYN' => Currency.new('BYN', subunit: 2, symbol: 'Br'),
-      'MDL' => Currency.new('MDL', subunit: 2, symbol: 'L'),
-      'GEL' => Currency.new('GEL', subunit: 2, symbol: '₾'),
-      'AMD' => Currency.new('AMD', subunit: 2, symbol: '֏'),
-      'AZN' => Currency.new('AZN', subunit: 2, symbol: '₼'),
+    @currencies ||= begin
+      registry = { 'XXX' => Currency.new(code: 'XXX', name: 'No currency', symbol: '¤') }
+      load_currencies(registry)
+    end
+  end
 
-      # Africa
-      'ZAR' => Currency.new('ZAR', subunit: 2, symbol: 'R'),
-      'EGP' => Currency.new('EGP', subunit: 2, symbol: '£'),
-      'NGN' => Currency.new('NGN', subunit: 2, symbol: '₦'),
-      'KES' => Currency.new('KES', subunit: 2, symbol: 'KSh'),
-      'GHS' => Currency.new('GHS', subunit: 2, symbol: '¢'),
-      'UGX' => Currency.new('UGX', subunit: 0, symbol: 'USh'),
-      'TZS' => Currency.new('TZS', subunit: 2, symbol: 'TSh'),
-      'ETB' => Currency.new('ETB', subunit: 2, symbol: 'Br'),
-      'MAD' => Currency.new('MAD', subunit: 2, symbol: 'د.م.'),
-      'TND' => Currency.new('TND', subunit: 3, symbol: 'د.ت'),
-      'DZD' => Currency.new('DZD', subunit: 2, symbol: 'د.ج'),
-      'LYD' => Currency.new('LYD', subunit: 3, symbol: 'ل.د'),
-      'AOA' => Currency.new('AOA', subunit: 2, symbol: 'Kz'),
-      'BWP' => Currency.new('BWP', subunit: 2, symbol: 'P'),
-      'NAD' => Currency.new('NAD', subunit: 2, symbol: 'N$'),
-      'SZL' => Currency.new('SZL', subunit: 2, symbol: 'L'),
-      'LSL' => Currency.new('LSL', subunit: 2, symbol: 'L'),
-      'MZN' => Currency.new('MZN', subunit: 2, symbol: 'MT'),
-      'ZMW' => Currency.new('ZMW', subunit: 2, symbol: 'ZK'),
-      'MWK' => Currency.new('MWK', subunit: 2, symbol: 'MK'),
-      'RWF' => Currency.new('RWF', subunit: 0, symbol: 'R₣'),
-      'BIF' => Currency.new('BIF', subunit: 0, symbol: 'FBu'),
+  # Registered symbols sorted for detection: longest match wins, then parser priority.
+  def self.currency_symbols
+    @currency_symbols ||= begin
+      currencies.values
+                .map { |currency| [currency.symbol, currency] }
+                .reject { |symbol, _| symbol.empty? }
+                .sort_by { |symbol, currency| [-symbol.length, -currency.priority] }
+    end.freeze
+  end
 
-      # Americas
-      'MXN' => Currency.new('MXN', subunit: 2, symbol: '$'),
-      'BRL' => Currency.new('BRL', subunit: 2, symbol: 'R$'),
-      'ARS' => Currency.new('ARS', subunit: 2, symbol: '$'),
-      'CLP' => Currency.new('CLP', subunit: 0, symbol: '$'),
-      'PEN' => Currency.new('PEN', subunit: 2, symbol: 'S/.'),
-      'COP' => Currency.new('COP', subunit: 2, symbol: '$'),
-      'VES' => Currency.new('VES', subunit: 2, symbol: 'Bs.'),
-      'UYU' => Currency.new('UYU', subunit: 2, symbol: '$U'),
-      'PYG' => Currency.new('PYG', subunit: 0, symbol: 'Gs'),
-      'BOB' => Currency.new('BOB', subunit: 2, symbol: '$b'),
-      'CRC' => Currency.new('CRC', subunit: 2, symbol: '₡'),
-      'GTQ' => Currency.new('GTQ', subunit: 2, symbol: 'Q'),
-      'HNL' => Currency.new('HNL', subunit: 2, symbol: 'L'),
-      'NIO' => Currency.new('NIO', subunit: 2, symbol: 'C$'),
-      'PAB' => Currency.new('PAB', subunit: 2, symbol: 'B/.'),
-      'DOP' => Currency.new('DOP', subunit: 2, symbol: 'RD$'),
-      'HTG' => Currency.new('HTG', subunit: 2, symbol: 'G'),
-      'JMD' => Currency.new('JMD', subunit: 2, symbol: 'J$'),
-      'TTD' => Currency.new('TTD', subunit: 2, symbol: 'TT$'),
-      'BBD' => Currency.new('BBD', subunit: 2, symbol: 'Bds$'),
-      'BSD' => Currency.new('BSD', subunit: 2, symbol: 'B$'),
-      'BZD' => Currency.new('BZD', subunit: 2, symbol: 'BZ$'),
-      'GYD' => Currency.new('GYD', subunit: 2, symbol: 'G$'),
-      'SRD' => Currency.new('SRD', subunit: 2, symbol: 'Sr$'),
+  def self.load_currencies(registry)
+    base = File.expand_path('../data', __dir__)
+    path = File.join(base, 'currencies.yaml')
 
-      # Pacific & Others
-      'FJD' => Currency.new('FJD', subunit: 2, symbol: 'FJ$'),
-      'PGK' => Currency.new('PGK', subunit: 2, symbol: 'K'),
-      'SBD' => Currency.new('SBD', subunit: 2, symbol: 'SI$'),
-      'VUV' => Currency.new('VUV', subunit: 0, symbol: 'VT'),
-      'TOP' => Currency.new('TOP', subunit: 2, symbol: 'T$'),
-      'WST' => Currency.new('WST', subunit: 2, symbol: 'WS$'),
-      'XCD' => Currency.new('XCD', subunit: 2, symbol: 'EC$'),
-      'XOF' => Currency.new('XOF', subunit: 0, symbol: 'CFA'),
-      'XAF' => Currency.new('XAF', subunit: 0, symbol: 'FCFA'),
-      'XPF' => Currency.new('XPF', subunit: 0, symbol: '₣')
-    }
+    data = YAML.load_file(path)
+    data.each do |entry|
+      code = entry['code']
+      registry[code] = Currency.new(
+        code: code,
+        subunit: entry['subunit'],
+        symbol: entry['symbol'],
+        priority: entry['priority'],
+        country: entry['country'],
+        name: entry['name']
+      )
+    end
+    registry
   end
+
+  private_class_method :load_currencies
 end

data/lib/minting/money/allocation.rb

@@ -1,15 +1,34 @@
 module Mint
-  # :nodoc
-  # split and allocation methods
   class Money
+    # Proportionally allocates the monetary amount among a list of ratios.
+    # Disperses any subunit rounding amounts across the initial slots
+    # @param proportions [Array<Numeric>] a list of numeric proportions/ratios to allocate by
+    # @return [Array<Money>] the list of newly allocated Money objects
+    # @raise [ArgumentError] if the proportions list is empty or sums to zero
+    #
+    # @example Proportional allocation
+    #   money = Mint.money(10.00, 'USD')
+    #   money.allocate([1, 2, 3]) #=> [[USD 1.67], [USD 3.33], [USD 5.00]]
     def allocate(proportions)
+      whole = proportions.sum.to_r
       raise ArgumentError, 'Need at least 1 proportion element' if proportions.empty?
+      raise ArgumentError, 'Proportions total must not be zero' if whole.zero?
 
-      whole = proportions.sum.to_r
-      amounts = proportions.map! { |rate| (amount * rate.to_r / whole).round(currency.subunit) }
+      amounts = proportions.map { |rate| (amount * rate.to_r / whole).round(currency.subunit) }
       allocate_left_over!(amounts: amounts, left_over: amount - amounts.sum)
     end
 
+    # Splits the monetary amount into a given quantity of equal parts.
+    # Disperses any fractional subunit rounding differences across the initial slots
+    # so that the sum is preserved.
+    #
+    # @param quantity [Integer] the number of equal parts to divide the money into (must be > 0)
+    # @return [Array<Money>] the list of newly split Money objects
+    # @raise [ArgumentError] if quantity is not a positive integer
+    #
+    # @example Even split
+    #   money = Mint.money(10.00, 'USD')
+    #   money.split(3) #=> [[USD 3.34], [USD 3.33], [USD 3.33]]
     def split(quantity)
       unless  quantity.positive? && quantity.integer?
         raise ArgumentError,
@@ -29,7 +48,7 @@ module Mint
         last_slot = (left_over / minimum).to_i - 1
         (0..last_slot).each { |slot| amounts[slot] += minimum }
       end
-      amounts.map { mint(it) }
+      amounts.map { mint it }
     end
   end
 end

data/lib/minting/money/arithmetics.rb

@@ -1,15 +1,31 @@
 module Mint
-  # :nodoc
-  # Arithmetic functions for money objects
   class Money
+    # Returns the absolute value of the monetary amount as a new {Money} instance.
+    #
+    # @return [Money] the absolute value
     def abs =     mint(amount.abs)
 
+    # Returns true if the monetary amount is less than zero.
+    #
+    # @return [Boolean] true if negative, false otherwise
     def negative? = amount.negative?
 
+    # Returns true if the monetary amount is greater than zero.
+    #
+    # @return [Boolean] true if positive, false otherwise
     def positive? = amount.positive?
 
+    # Returns the successor of the Money instance by adding the minimum possible subunit amount.
+    # Enables standard ranges and stepping (e.g. `1.dollar..10.dollars`).
+    #
+    # @return [Money] successor Money instance
     def succ = mint(amount + currency.minimum_amount)
 
+    # Performs addition with another {Money} instance or standard zero Numeric.
+    #
+    # @param addend [Money, Numeric] the value to add
+    # @return [Money] the sum of the addition
+    # @raise [TypeError] if addition involves a different currency or incompatible types
     def +(addend)
       return self if addend.respond_to?(:zero?) && addend.zero?
       return mint(amount + addend.amount) if addend.is_a?(Money) && same_currency?(addend)
@@ -17,6 +33,11 @@ module Mint
       raise TypeError, "#{addend} can't be added to #{self}"
     end
 
+    # Performs subtraction with another {Money} instance or standard zero Numeric.
+    #
+    # @param subtrahend [Money, Numeric] the value to subtract
+    # @return [Money] the difference of the subtraction
+    # @raise [TypeError] if subtraction involves a different currency or incompatible types
     def -(subtrahend)
       return self if subtrahend.respond_to?(:zero?) && subtrahend.zero?
       if subtrahend.is_a?(Money) && same_currency?(subtrahend)
@@ -26,16 +47,30 @@ module Mint
       raise TypeError, "#{subtrahend} can't be subtracted from #{self}"
     end
 
+    # Unary negation operator. Returns a new {Money} instance with the inverted sign.
+    #
+    # @return [Money] negated Money instance
     def -@
       mint(-amount)
     end
 
+    # Performs multiplication of the monetary value by a standard scalar Numeric.
+    #
+    # @param multiplicand [Numeric] the scalar multiplier
+    # @return [Money] the multiplied Money instance
+    # @raise [TypeError] if multiplier is not Numeric or is a Money object
     def *(multiplicand)
       return mint(amount * multiplicand.to_r) if multiplicand.is_a?(Numeric)
 
       raise TypeError, "#{self} can't be multiplied by #{multiplicand}"
     end
 
+    # Performs division of the monetary value by a scalar Numeric or identical currency {Money}.
+    #
+    # @param divisor [Numeric, Money] the divisor
+    # @return [Money, Numeric] a new Money (scalar division) or a numeric ratio (Money division)
+    # @raise [TypeError] if divisor is of incompatible type or different currency
+    # @raise [ZeroDivisionError] if division by zero is attempted
     def /(divisor)
       return mint(amount / divisor) if divisor.is_a?(Numeric)
       return amount / divisor.amount if same_currency? divisor

data/lib/minting/money/coercion.rb

@@ -1,40 +1,50 @@
 module Mint
-  # :nodoc
-  # Coercion logic
   class Money
+    # Implements the standard Ruby coercion protocol.
+    # Allows {Money} to interact seamlessly as the right-hand operand in Numeric arithmetic.
+    #
+    # @param other [Numeric] the left-hand operand to coerce
+    # @return [Array(CoercedNumber, Money)] coerced operand array
     def coerce(other)
       [CoercedNumber.new(other), self]
     end
 
-    # :nodoc
+    # @private
     # Coerced Number contains the arithmetic logic for numeric compatible ops.
+    # @private
     class CoercedNumber
       include Comparable
 
+      # @private
       def initialize(value)
         @value = value
       end
 
+      # @private
       def +(other)
         return other if @value.zero?
 
         raise_coercion_error(:+, other)
       end
 
+      # @private
       def -(other)
         return -other if @value.zero?
 
         raise_coercion_error(:-, other)
       end
 
+      # @private
       def *(other)
         other.mint(@value * other.amount)
       end
 
+      # @private
       def /(other)
         raise_coercion_error(:/, other)
       end
 
+      # @private
       def <=>(other)
         return nil if @value.nil? || other.nil?
         return @value <=> other.amount if @value.zero? || other.zero?
@@ -42,6 +52,7 @@ module Mint
         raise_coercion_error(:<=>, other)
       end
 
+      # @private
       def raise_coercion_error(operation, operand)
         raise TypeError,
               "#{self} #{operation} #{operand} : incompatible operands"

data/lib/minting/money/comparable.rb

@@ -7,18 +7,23 @@ module Mint
     # @return true if both are zero, or both have same amount and same currency
     def ==(other)
       return true if zero? && other.respond_to?(:zero?) && other.zero?
-      return false unless other.is_a?(Mint::Money)
 
-      amount == other.amount && currency == other.currency
+      eql?(other)
+    end
+
+    def eql?(other)
+      other.is_a?(Mint::Money) &&
+        amount == other.amount &&
+        currency == other.currency
     end
 
     # @example
-    #   two_usd == Mint.money(2r, 'USD']) #=> [$ 2.00]
-    #   two_usd > 0                       #=> true
-    #   two_usd > Mint.money(2, 'USD'])  #=> true
+    #   two_usd == Mint.money(2r, 'USD') #=> [$ 2.00]
+    #   two_usd > 0                      #=> true
+    #   two_usd > Mint.money(2, 'USD')   #=> false
     #   two_usd > 1
     #   => TypeError: [$ 2.00] can't be compared to 1
-    #   two_usd > Mint.money(2, 'BRL'])
+    #   two_usd > Mint.money(2, 'BRL')
     #   => TypeError: [$ 2.00] can't be compared to [R$ 2.00]
     #
     def <=>(other)
@@ -31,16 +36,8 @@ module Mint
       raise TypeError, "#{inspect} can't be compared to #{other.inspect}"
     end
 
-    def eql?(other)
-      self == other
-    end
-
-    def nonzero?
-      amount.nonzero?
-    end
+    def nonzero? = amount.nonzero?
 
-    def zero?
-      amount.zero?
-    end
+    def zero? = amount.zero?
   end
 end

data/lib/minting/money/conversion.rb

@@ -1,23 +1,48 @@
+require 'erb'
+
 module Mint
-  # Conversion logic
+  # Conversion and serialization logic for {Money} instances.
   class Money
+    # Converts the monetary amount to a {BigDecimal} object.
+    #
+    # @return [BigDecimal] the decimal representation of the money amount
+    # @raise [NoMethodError] if the bigdecimal gem is not loaded/available
     def to_d
+      raise NoMethodError, 'decimal gem required' unless defined?(BigDecimal)
+
       amount.to_d 0
     end
 
+    # Converts the monetary amount to a standard float.
+    # Note: Using float conversion loses precision guarantees.
+    #
+    # @return [Float] the floating-point representation of the money amount
     def to_f
       amount.to_f
     end
 
+    # Renders a safe HTML5 `<data>` element containing the formatted currency.
+    # Embeds the ISO currency description and raw value as the metadata `title` attribute.
+    #
+    # @param format [String] the display format to apply to the visible HTML text
+    # @return [String] HTML5 `<data>` representation
     def to_html(format = DEFAULT_FORMAT)
       title = Kernel.format("#{currency_code} %0.#{currency.subunit}f", amount)
-      %(<data class='money' title='#{title}'>#{to_s(format: format)}</data>)
+      body = to_s(format: format)
+      %(<data class='money' title='#{ERB::Util.html_escape(title)}'>#{ERB::Util.html_escape(body)}</data>)
     end
 
+    # Truncates and converts the monetary amount to an Integer.
+    #
+    # @return [Integer] the integer representation of the money amount
     def to_i
       amount.to_i
     end
 
+    # Serializes the money instance to a standard JSON object containing the amount and currency.
+    # Highly optimized to run without external dependencies.
+    #
+    # @return [String] the JSON serialized string representation
     def to_json(*_args)
       subunit = currency.subunit
       Kernel.format(
@@ -26,6 +51,9 @@ module Mint
       )
     end
 
+    # Returns the exact internal Rational representation of the monetary amount.
+    #
+    # @return [Rational] the rational representation of the money amount
     def to_r
       amount
     end

data/lib/minting/money/formatting.rb

@@ -10,9 +10,9 @@ module Mint
     #
     # @example Basic formatting
     #   money = Mint.money(1234.56, 'USD')
-    #   money.to_s                           #=> "$1234.56"
-    #   money.to_s(thousand: ',')           #=> "$1,234.56"
-    #   money.to_s(decimal: ',')           #=> "$1234,56"
+    #   money.to_s                               #=> "$1,234.56"
+    #   money.to_s(thousand: '.', decimal: ',')  #=> "$1.234,56"
+    #   money.to_s(decimal: ',', thousand: '')   #=> "$1234,56"
     #
     # @example Custom formats
     #   money.to_s(format: '%<amount>f')                    #=> "1234.56"
@@ -41,8 +41,9 @@ module Mint
       formatted
     end
 
+    private
+
     def format_amount(format)
-      # binding.irb if format.is_a? Hash
       format = { positive: format } if format.is_a?(String)
       value = amount
 

data/lib/minting/money/money.rb

@@ -1,5 +1,7 @@
 module Mint
   class Money
+    # The default display format pattern for formatting monetary values.
+    # Uses `%<symbol>s` for the currency symbol and `%<amount>f` for the rounded amount.
     DEFAULT_FORMAT = '%<symbol>s%<amount>f'.freeze
 
     attr_reader :amount, :currency
@@ -10,37 +12,44 @@ module Mint
     # @raise [ArgumentError] If amount is not numeric or currency is invalid
     def initialize(amount, currency)
       raise ArgumentError, 'amount must be Numeric' unless amount.is_a?(Numeric)
-
-      unless currency.is_a?(Currency)
-        raise ArgumentError,
-              'currency must be a Currency object'
-      end
+      raise ArgumentError, 'currency must be a Currency object' unless currency.is_a?(Currency)
 
       @amount = amount.to_r.round(currency.subunit)
       @currency = currency
+      freeze
     end
 
-    def currency_code
-      currency.code
-    end
+    # Returns the ISO 3-letter currency code string.
+    #
+    # @return [String] the ISO currency code
+    def currency_code = currency.code
 
-    def hash
-      zero? ? 0.hash : [amount, currency.code].hash
-    end
+    # Generates a stable hash key for Money instances.
+    #
+    # @return [Integer] the calculated hash value
+    def hash = [amount, currency_code].hash
 
     # Returns a new Money object with the specified amount, or self if unchanged
     # @param new_amount [Numeric] The new amount
     # @return [Money] A new Money object or self
     def mint(new_amount)
-      new_amount.to_r == amount ? self : Money.new(new_amount, currency).freeze
+      new_amount.to_r == amount ? self : Money.new(new_amount, currency)
     end
 
+    # Returns a standard developer-oriented string inspection of the Money object.
+    #
+    # @return [String] the formatted inspect representation
     def inspect
       Kernel.format "[#{currency_code} %0.#{currency.subunit}f]", amount
     end
 
-    def same_currency?(other)
-      other.respond_to?(:currency) && other.currency == currency
-    end
+    # Helper method to verify if another object has the identical currency.
+    #
+    # @param other [Object] the target object to compare
+    # @return [Boolean] true if currencies match, false otherwise
+    def same_currency?(other) = other.respond_to?(:currency) && other.currency == currency
+
+    # Returns default zero no currency money
+    def self.zero = @zero ||= new(0, Mint.currencies('XXX'))
   end
 end