minting 1.3.0 → 1.4.0

data/lib/minting/money/conversion.rb

@@ -6,20 +6,13 @@ module Mint
     # 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
+    def to_d = amount.to_d 0
 
     # 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
+    def to_f = amount.to_f
 
     # Renders a safe HTML5 `<data>` element containing the formatted currency.
     # Embeds the ISO currency description and raw value as the metadata `title` attribute.
@@ -29,15 +22,13 @@ module Mint
     def to_html(format = DEFAULT_FORMAT)
       title = Kernel.format("#{currency_code} %0.#{currency.subunit}f", amount)
       body = to_s(format: format)
-      %(<data class='money' title='#{ERB::Util.html_escape(title)}'>#{ERB::Util.html_escape(body)}</data>)
+      %(<data class='money' title='#{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
+    def to_i = amount.to_i
 
     def to_hash
       { currency: currency_code, amount: Kernel.format("%0.#{currency.subunit}f", amount) }
@@ -56,8 +47,6 @@ module Mint
     # Returns the exact internal Rational representation of the monetary amount.
     #
     # @return [Rational] the rational representation of the money amount
-    def to_r
-      amount
-    end
+    def to_r = amount
   end
 end

data/lib/minting/money/formatting.rb

@@ -1,13 +1,28 @@
 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] Format string with placeholders: %<symbol>s, %<amount>f, %<currency>s
+    # @param format [String, Hash] Either a Format string with placeholders
+    #   (%<symbol>s, %<amount>f, %<currency>s), or a Hash with per-sign keys
+    #   (:positive, :negative, :zero) each holding a format string. A Hash
+    #   is convenient for sign-aware formats such as accounting parentheses:
+    #
+    #     money.to_s(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
+    #   :positive, :negative, :zero; anything else raises ArgumentError.
     # @param thousand [String, false] Thousands delimiter (e.g., ',' for 1,000)
     # @param decimal [String] Decimal separator (e.g., '.' or ',')
     # @return [String] Formatted money string
     #
+    # @raise [ArgumentError] if +format+ is not a String or Hash, the Hash
+    #   is empty, or the Hash contains an unrecognised key.
+    #
     # @example Basic formatting
     #   money = Mint.money(1234.56, 'USD')
     #   money.to_s                               #=> "$1,234.56"
@@ -20,6 +35,11 @@ module Mint
     #   money.to_s(format: '%<amount>f %<symbol>s')         #=> "1234.56 $"
     #   money.to_s(format: '%<symbol>s%<amount>+f')         #=> "$+1234.56"
     #
+    # @example Per-sign Hash format (accounting parentheses)
+    #   loss = Mint.money(-1234.56, 'USD')
+    #   loss.to_s(format: { negative: '(%<symbol>s%<amount>f)' }) #=> "($1,234.56)"
+    #   Mint.money(0, 'BRL').to_s(format: { zero: '--' })        #=> "--"
+    #
     # @example Padding and alignment
     #   money.to_s(format: '%<amount>10.2f')                #=> "   1234.56"
     #   money.to_s(format: '%<symbol>s%<amount>010.2f')     #=> "$0001234.56"
@@ -27,6 +47,8 @@ module Mint
     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)
+
       formatted = format_amount(format)
 
       formatted.tr!('.', decimal) if decimal != '.'
@@ -43,6 +65,17 @@ 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?
+
+      raise ArgumentError,
+            "Unknown format Hash key(s): #{unknown.inspect}. " \
+            "Valid keys are #{SIGN_FORMAT_KEYS.inspect}"
+    end
+
     def format_amount(format)
       format = { positive: format } if format.is_a?(String)
       value = amount

data/lib/minting/money/money.rb

@@ -14,14 +14,39 @@ module Mint
       raise ArgumentError, 'amount must be Numeric' unless amount.is_a?(Numeric)
 
       checked_currency = Mint.currency(currency)
-      unless checked_currency
-        raise ArgumentError,
-              "Currency not found (#{currency}). Check Mint.currencies"
-      end
+      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
@@ -38,7 +63,7 @@ module Mint
     # @param new_amount [Numeric] The new amount
     # @return [Money] A new Money object or self
     def mint(new_amount)
-      new_amount = new_amount.to_r.round(currency.subunit)
+      new_amount = currency.normalize_amount(new_amount)
       new_amount == amount ? self : Money.new(new_amount, currency)
     end
 
@@ -55,6 +80,59 @@ module Mint
     # @return [Boolean] true if currencies match, false otherwise
     def same_currency?(other) = other.respond_to?(:currency) && other.currency == currency
 
+    # Constrains +self+ to the inclusive range [+min+, +max+].
+    #
+    # Both bounds may be either a same-currency {Money} or a {Numeric}. A
+    # 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+".
+    #
+    # When +self+ is already in range the receiver is returned (no new object
+    # 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)
+    # @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+
+    #
+    # @example In range
+    #   Mint.money(5, 'USD').clamp(0, 10) #=> [USD 5.00]  (returns self)
+    #
+    # @example Out of range, with Numeric bounds
+    #   Mint.money(50, 'USD').clamp(0, 10) #=> [USD 10.00]
+    #
+    # @example Out of range, with Money bounds
+    #   loss  = Mint.money(-5, 'USD')
+    #   floor = Mint.money(0,  'USD')
+    #   ceil  = Mint.money(10, 'USD')
+    #   loss.clamp(floor, ceil) #=> [USD 0.00]
+    #
+    # @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)
+
+        min = min.amount
+      else raise(ArgumentError, 'min must be Numeric or Money')
+      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))
+    end
+
     private
 
     # Initializes a new Money object with the given amount and currency.

data/lib/minting/version.rb

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

data/minting.gemspec

@@ -27,6 +27,7 @@ Gem::Specification.new do |s|
   }
 
   s.required_ruby_version = '>= 3.2.0'
+  s.add_dependency 'bigdecimal', '>= 4.0'
 
   s.files = Dir.glob('{bin,doc,lib}/**/*')
   s.files += %w[minting.gemspec Rakefile README.md LICENSE]

metadata

@@ -1,14 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: minting
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Gilson Ferraz
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
 description: Library to manipulate currency values
 email: []
 executables: []
@@ -20,6 +34,28 @@ 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
 - lib/minting.rb
 - lib/minting/data/currencies.yaml
 - lib/minting/mint.rb