minting 1.3.0 → 1.5.0

data/lib/minting/money/money.rb

@@ -1,27 +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)
-      unless checked_currency
-        raise ArgumentError,
-              "Currency not found (#{currency}). Check Mint.currencies"
-      end
-
-      new(checked_currency.normalize_amount(amount), checked_currency)
-    end
-
     # Returns the ISO 3-letter currency code string.
     #
     # @return [String] the ISO currency code
@@ -34,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 = new_amount.to_r.round(currency.subunit)
-      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
@@ -51,19 +30,66 @@ 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+].
+    #
+    # 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+".
+    #
+    # 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_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, 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)
+    #
+    # @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_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, max = min_or_range.minmax
+      else
+        min = min_or_range
+      end
+      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.3.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'

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.5.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,10 +34,16 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- doc/agents/AGENTS.md
+- doc/agents/copilot-instructions.md
+- doc/agents/gemini_gem_evaluation.md
+- doc/agents/recommendations.md
+- 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
@@ -31,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