minting 1.4.0 → 1.5.0

data/lib/minting/money/arithmetics.rb

@@ -1,4 +1,7 @@
+# frozen_string_literal: true
+
 module Mint
+  # Money Arithmetics
   class Money
     # Returns the absolute value of the monetary amount as a new {Money} instance.
     #
@@ -27,9 +30,10 @@ module Mint
     # @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)
-
+      case addend
+      when 0     then return self
+      when Money then return mint(amount + addend.amount) if same_currency?(addend)
+      end
       raise TypeError, "#{addend} can't be added to #{self}"
     end
 
@@ -39,11 +43,10 @@ module Mint
     # @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)
-        return mint(amount - subtrahend.amount)
+      case subtrahend
+      when 0     then return self
+      when Money then return mint(amount - subtrahend.amount) if same_currency?(subtrahend)
       end
-
       raise TypeError, "#{subtrahend} can't be subtracted from #{self}"
     end
 
@@ -72,10 +75,22 @@ module Mint
     # @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
-
+      case divisor
+      when Numeric then return mint(amount / divisor)
+      when Money   then return amount / divisor.amount if same_currency? divisor
+      end
       raise TypeError, "#{self} can't be divided by #{divisor}"
     end
+
+    # Performs exponentiation of the monetary value by a standard scalar Numeric.
+    #
+    # @param exponent [Numeric]
+    # @return [Money] reult of amount ** exponent
+    # @raise [TypeError] if exponent is not Numeric
+    def **(exponent)
+      return mint(amount**exponent) if exponent.is_a?(Numeric)
+
+      raise TypeError, "#{self} can't be powered by #{exponent}"
+    end
   end
 end

data/lib/minting/money/coercion.rb

@@ -1,6 +1,8 @@
+# frozen_string_literal: true
+
 module Mint
+  # Implements the standard Ruby coercion protocol.
   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

data/lib/minting/money/comparable.rb

@@ -1,5 +1,6 @@
+# frozen_string_literal: true
+
 module Mint
-  # :nodoc
   # Comparison methods
   class Money
     include Comparable
@@ -28,12 +29,10 @@ module Mint
     #
     def <=>(other)
       case other
-      when Numeric
-        return amount <=> other if other.zero?
-      when Mint::Money
-        return amount <=> other.amount if currency == other.currency
+      in 0                                    then amount <=> other
+      in Mint::Money if same_currency?(other) then amount <=> other.amount
+      else                                    raise TypeError, "#{inspect} can't be compared to #{other.inspect}"
       end
-      raise TypeError, "#{inspect} can't be compared to #{other.inspect}"
     end
 
     def nonzero? = amount.nonzero?

data/lib/minting/money/constructors.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Mint
+  # Money constructors
+  class Money
+    # Creates a new Money immutable object with the specified amount and currency
+    # @param amount [Numeric] The monetary amount
+    # @param currency [Currency] The currency object
+    # @raise [ArgumentError] If amount is not numeric or currency is invalid
+    def self.create(amount, currency)
+      raise ArgumentError, 'amount must be Numeric' unless amount.is_a?(Numeric)
+
+      checked_currency = Mint.currency(currency)
+      raise ArgumentError, "Currency not found (#{currency})" unless checked_currency
+
+      new(checked_currency.normalize_amount(amount), checked_currency)
+    end
+
+    # Builds a Money from a fractional (smallest-unit) Integer amount.
+    # This is the inverse of {#fractional}: for USD, the fractional unit 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
+    #   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+
+    #   is not registered
+    #
+    # @example USD cents
+    #   Money.from_fractional(123_456, 'USD') #=> [USD 1234.56]
+    # @example JPY (subunit 0)
+    #   Money.from_fractional(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)
+
+      checked_currency = Mint.currency(currency)
+      raise ArgumentError, "Currency not found (#{currency})" unless checked_currency
+
+      amount = Rational(fractional, checked_currency.fractional_multiplier)
+      new(amount, checked_currency)
+    end
+
+    # 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 = currency.normalize_amount(new_amount)
+      new_amount == amount ? self : Money.new(new_amount, currency)
+    end
+
+    private
+
+    # Initializes a new Money object with the given amount and currency.
+    # @param amount [Numeric] The monetary amount
+    # @param currency [Currency] The currency object
+    def initialize(amount, currency)
+      @amount = amount
+      @currency = currency
+      freeze
+    end
+  end
+end

data/lib/minting/money/conversion.rb

@@ -1,9 +1,12 @@
+# frozen_string_literal: true
+
+require 'bigdecimal'
 require 'erb'
 
 module Mint
   # Conversion and serialization logic for {Money} instances.
   class Money
-    # Converts the monetary amount to a {BigDecimal} object.
+    # Converts the monetary amount to a BigDecimal object.
     #
     # @return [BigDecimal] the decimal representation of the money amount
     def to_d = amount.to_d 0

data/lib/minting/money/formatting.rb

@@ -1,9 +1,8 @@
+# frozen_string_literal: true
+
 module Mint
   # Formatting functionality for Money objects
   class Money
-    # Keys accepted in the per-sign Hash form of `to_s(format:)`.
-    SIGN_FORMAT_KEYS = %i[positive negative zero].freeze
-
     # Formats money as a string with customizable format, thousand delimiter, and decimal
     #
     # @param format [String, Hash] Either a Format string with placeholders
@@ -45,9 +44,12 @@ module Mint
     #   money.to_s(format: '%<symbol>s%<amount>010.2f')     #=> "$0001234.56"
     #
     def to_s(format: '%<symbol>s%<amount>f', decimal: '.', thousand: ',', width: nil)
-      raise ArgumentError, 'Invalid format' unless format.is_a?(String) || format.is_a?(Hash)
-
-      validate_format_hash!(format) if format.is_a?(Hash)
+      case format
+      when {}, '', nil then raise ArgumentError, 'format must not be empty or null'
+      when Hash        then validate_format_hash!(format)
+      when String # noop
+      else raise ArgumentError, 'Invalid format'
+      end
 
       formatted = format_amount(format)
 
@@ -66,27 +68,26 @@ module Mint
     private
 
     def validate_format_hash!(format)
-      raise ArgumentError, 'format Hash must not be empty' if format.empty?
-
-      unknown = format.keys - SIGN_FORMAT_KEYS
-      return if unknown.empty?
+      unknown = format.keys - %i[positive negative zero]
 
-      raise ArgumentError,
-            "Unknown format Hash key(s): #{unknown.inspect}. " \
-            "Valid keys are #{SIGN_FORMAT_KEYS.inspect}"
+      raise ArgumentError, "Unknown format parameter(s): #{unknown.inspect}. " unless unknown.empty?
     end
 
     def format_amount(format)
       format = { positive: format } if format.is_a?(String)
-      value = amount
+      positive_format = format[:positive]
+      negative_format = format[:negative]
+      zero_format = format[:zero]
 
-      if amount.negative? && format[:negative]
-        format = format[:negative]
+      if amount.negative? && negative_format
+        format = negative_format
         value = -amount
-      elsif amount.zero? && format[:zero]
-        format = format[:zero]
+      elsif amount.zero? && zero_format
+        format = zero_format
+        value = amount
       else
-        format = format[:positive]
+        format = positive_format
+        value = amount
       end
       format ||= '%<symbol>s%<amount>f'
 

data/lib/minting/money/money.rb

@@ -1,52 +1,14 @@
+# frozen_string_literal: true
+
 module Mint
+  # Money constructors
   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
+    DEFAULT_FORMAT = '%<symbol>s%<amount>f'
 
     attr_reader :amount, :currency
 
-    # Creates a new Money immutable object with the specified amount and currency
-    # @param amount [Numeric] The monetary amount
-    # @param currency [Currency] The currency object
-    # @raise [ArgumentError] If amount is not numeric or currency is invalid
-    def self.create(amount, currency)
-      raise ArgumentError, 'amount must be Numeric' unless amount.is_a?(Numeric)
-
-      checked_currency = Mint.currency(currency)
-      raise ArgumentError, "Currency not found (#{currency})" unless checked_currency
-
-      new(checked_currency.normalize_amount(amount), checked_currency)
-    end
-
-    # Builds a Money from a fractional (smallest-unit) Integer amount.
-    # This is the inverse of {#fractional}: for USD, the fractional unit 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
-    #   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+
-    #   is not registered
-    #
-    # @example USD cents
-    #   Money.from_fractional(123_456, 'USD') #=> [USD 1234.56]
-    # @example JPY (subunit 0)
-    #   Money.from_fractional(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)
-
-      checked_currency = Mint.currency(currency)
-      raise ArgumentError, "Currency not found (#{currency})" unless checked_currency
-
-      amount = Rational(fractional, checked_currency.fractional_multiplier)
-      new(amount, checked_currency)
-    end
-
     # Returns the ISO 3-letter currency code string.
     #
     # @return [String] the ISO currency code
@@ -59,14 +21,6 @@ module Mint
     # @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 = currency.normalize_amount(new_amount)
-      new_amount == 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
@@ -76,13 +30,17 @@ module Mint
 
     # Helper method to verify if another object has the identical currency.
     #
-    # @param other [Object] the target object to compare
+    # @param other [Currency] the target currency to compare
     # @return [Boolean] true if currencies match, false otherwise
-    def same_currency?(other) = other.respond_to?(:currency) && other.currency == currency
+    def same_currency?(other) = other.currency == currency
 
     # Constrains +self+ to the inclusive range [+min+, +max+].
     #
-    # Both bounds may be either a same-currency {Money} or a {Numeric}. A
+    # Bounds may be:
+    # - nil meaning no boundary
+    # - same-currency {Money} or Range
+    # - Numeric amount, or Range
+    #
     # Numeric is interpreted as an amount in +self+'s currency, so the common
     # pricing idiom +price.clamp(0, 100)+ reads as "0 to 100 in the same
     # currency as +price+".
@@ -91,11 +49,12 @@ module Mint
     # allocated). When out of range, the nearest bound is returned as a new
     # frozen {Money} in +self+'s currency.
     #
-    # @param min [Money, Numeric] lower bound (inclusive)
-    # @param max [Money, Numeric] upper bound (inclusive)
+    # @param min_or_range [Money, Numeric, Range, nil] lower bound (inclusive), or range
+    # @param max [Money, Numeric, nil] upper bound (inclusive)
     # @return [Money] +self+ if in range, otherwise the nearer bound
-    # @raise [ArgumentError] if +min+ or +max+ is not a Money or Numeric; if
-    #   a Money operand has a different currency; if +min+ > +max+
+    # @raise [ArgumentError] if +min+ or +max+ is not a Money, Numeric or nil; if
+    #   a Money operand has a different currency; if +min+ > +max+;
+    #   if min is a Range, and max is not nil
     #
     # @example In range
     #   Mint.money(5, 'USD').clamp(0, 10) #=> [USD 5.00]  (returns self)
@@ -111,37 +70,26 @@ module Mint
     #
     # @example Subunit-0 currency (JPY)
     #   Mint.money(500, 'JPY').clamp(0, 100) #=> [JPY 100]
-    def clamp(min, max)
-      case min
-      when Numeric
-      when Money
-        raise(ArgumentError, "min currency must be: #{currency_code}") unless same_currency?(min)
+    def clamp(min_or_range, max = nil)
+      if min_or_range.is_a?(Range)
+        raise(ArgumentError, "Either amount range alone or two amounts accepted: #{max}") if max
 
-        min = min.amount
-      else raise(ArgumentError, 'min must be Numeric or Money')
+        min, max = min_or_range.minmax
+      else
+        min = min_or_range
       end
-
-      case max
-      when Numeric
-      when Money
-        raise(ArgumentError, "max currency must be: #{currency_code}") unless same_currency?(max)
-
-        max = max.amount
-      else raise(ArgumentError, 'max must be Numeric or Money')
-      end
-
-      mint(amount.clamp(min, max))
+      mint(amount.clamp(normalize_boundary(min), normalize_boundary(max)))
     end
 
     private
 
-    # Initializes a new Money object with the given amount and currency.
-    # @param amount [Numeric] The monetary amount
-    # @param currency [Currency] The currency object
-    def initialize(amount, currency)
-      @amount = amount
-      @currency = currency
-      freeze
+    def normalize_boundary(boundary)
+      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}"
+      else                                 raise ArgumentError, "Boundary must be Numeric or Money #{boundary}"
+      end
     end
   end
 end

data/lib/minting/money/parse.rb

@@ -1,5 +1,7 @@
+# frozen_string_literal: true
+
 module Mint
-  # nodoc
+  # Money parser
   class Money
     # Parses a human-readable money string into a {Money} object.
     #
@@ -22,7 +24,7 @@ module Mint
       input = input.strip
       raise ArgumentError, 'input cannot be empty' if input.empty?
 
-      currency = currency ? Mint.currency(currency) : parse_currency(input)
+      currency = parse_currency(currency) || parse_currency(input)
       raise ArgumentError, "Currency [#{currency}] not registered" unless currency
 
       amount = currency.normalize_amount(parse_amount(input))
@@ -40,10 +42,8 @@ module Mint
     # Converts locale-specific decimal/thousand separators into a plain decimal string.
     def self.normalize_separators(numeric)
       case [numeric.count(','), numeric.count('.')]
-      in [0, 0] | [0, 1] # Nothing to normalize (e.g. "1500" or "34.21").
-        numeric
-      in [1, 0] # Only one comma: decimal (e.g. 19,99 or 1,234).
-        numeric.tr(',', '.')
+      in [0, 0] | [0, 1] then numeric              # Nothing to normalize (e.g. "1500" or "34.21").
+      in [1, 0]          then numeric.tr(',', '.') # Only one comma: decimal (e.g. 19,99 or 1,234).
       in [c, p] if c > 1 && p > 1 # Both separators appear multiple times
         raise ArgumentError, "could not distinguish decimal and thousand separators in '#{numeric}'"
       in [c, p] if c > 0 && p > 0 # Commas and dots: the rightmost one is the decimal separator.
@@ -58,22 +58,19 @@ module Mint
     end
 
     def self.parse_currency(input)
-      # Prefer an explicit ISO 4217 code (e.g. "USD 1,234.56") over symbol matching.
-      code = input[/\b([A-Z]{3})\b/, 1]
-      if code
-        currency = Mint.currency(code)
+      case input
+      when NilClass, Mint::Currency then return input
+      when String
+        # Prefer an explicit ISO 4217 code (e.g. "USD 1,234.56") over symbol matching.
+        currency = Mint.currency(input[/\b([A-Z]+)\b/, 1])
         return currency if currency
-      end
-
-      # Fall back to registered symbols, longest first (HK$ before $).
-      Mint.currency_symbols.each do |symbol, currency|
-        next if symbol.empty?
 
-        return currency if input.include?(symbol)
+        # Fall back to registered symbols, longest first (HK$ before $).
+        Mint.currency_symbols.each do |symbol, currency|
+          return currency if input.include?(symbol)
+        end
       end
-
-      raise ArgumentError,
-            'currency could not be detected; pass a currency code as the second argument'
+      raise ArgumentError, 'currency could not be detected; pass a currency code as the second argument'
     end
 
     private_class_method :parse_amount, :normalize_separators,

data/lib/minting/money.rb

@@ -1,8 +1,11 @@
+# frozen_string_literal: true
+
 require 'minting/money/parse'
 require 'minting/money/allocation'
 require 'minting/money/arithmetics'
 require 'minting/money/coercion'
 require 'minting/money/comparable'
+require 'minting/money/constructors'
 require 'minting/money/conversion'
 require 'minting/money/formatting'
 require 'minting/money/money'

data/lib/minting/version.rb

@@ -1,5 +1,7 @@
+# frozen_string_literal: true
+
 # Root namespace for the Minting library.
 module Minting
   # Current version of the Minting gem.
-  VERSION = '1.4.0'.freeze
+  VERSION = '1.5.0'
 end

data/lib/minting.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'minting/mint'
 require 'minting/money'
 require 'minting/version'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: minting
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Gilson Ferraz
@@ -34,32 +34,16 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
-- doc/Mint.html
-- doc/Mint/Currency.html
-- doc/Mint/Money.html
-- doc/Minting.html
-- doc/_index.html
 - doc/agents/AGENTS.md
 - doc/agents/copilot-instructions.md
 - doc/agents/gemini_gem_evaluation.md
 - doc/agents/recommendations.md
-- doc/class_list.html
-- doc/css/common.css
-- doc/css/full_list.css
-- doc/css/style.css
-- doc/file.README.html
-- doc/file_list.html
-- doc/frames.html
-- doc/index.html
-- doc/js/app.js
-- doc/js/full_list.js
-- doc/js/jquery.js
-- doc/method_list.html
-- doc/top-level-namespace.html
+- doc/agents/rubocop-issues.md
 - lib/minting.rb
 - lib/minting/data/currencies.yaml
 - lib/minting/mint.rb
 - lib/minting/mint/currency.rb
+- lib/minting/mint/currency_store.rb
 - lib/minting/mint/refinements.rb
 - lib/minting/mint/registry.rb
 - lib/minting/money.rb
@@ -67,6 +51,7 @@ files:
 - lib/minting/money/arithmetics.rb
 - lib/minting/money/coercion.rb
 - lib/minting/money/comparable.rb
+- lib/minting/money/constructors.rb
 - lib/minting/money/conversion.rb
 - lib/minting/money/formatting.rb
 - lib/minting/money/money.rb