minting 1.6.3 → 1.7.2

data/lib/minting/money/constructors.rb

@@ -13,7 +13,9 @@ module Mint
       checked_currency = Mint.currency(currency)
       raise ArgumentError, "Currency not found (#{currency})" unless checked_currency
 
-      new(checked_currency.normalize_amount(amount), checked_currency)
+      amount = checked_currency.normalize_amount(amount)
+
+      amount.zero? ? Mint.zero(checked_currency) : new(amount, checked_currency)
     end
 
     # Builds a Money from a fractional (smallest-unit) Integer amount.
@@ -41,7 +43,8 @@ module Mint
       raise ArgumentError, "Currency not found (#{currency})" unless checked_currency
 
       amount = Rational(fractional, checked_currency.fractional_multiplier)
-      new(amount, checked_currency)
+
+      amount.zero? ? Mint.zero(checked_currency) : new(amount, checked_currency)
     end
 
     # Returns a new Money object with the specified amount, or self if unchanged.
@@ -56,7 +59,14 @@ module Mint
     #   price.mint(10.00)  #=> [USD 10.00] (returns self)
     def mint(new_amount)
       new_amount = currency.normalize_amount(new_amount)
-      new_amount == amount ? self : Money.new(new_amount, currency)
+
+      if new_amount == amount
+        self
+      elsif new_amount.zero?
+        Mint.zero(currency)
+      else
+        Money.new(new_amount, currency)
+      end
     end
 
     private

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Mint
+  # Formatting functionality for Money objects
+  class Money
+    private
+
+    # Selects the appropriate format template and value based on the amount's sign.
+    # @private
+    def select_format(format)
+      negative_format = format[:negative]
+      zero_format = format[:zero]
+
+      if amount.negative? && negative_format
+        [negative_format, -amount]
+      elsif amount.zero? && zero_format
+        [zero_format,     amount]
+      else
+        [format[:positive], amount]
+      end
+    end
+
+    # Validates that format hash contains only known keys.
+    # @private
+    def validate_format_hash(format)
+      unknown = format.keys - %i[positive negative zero]
+
+      raise ArgumentError, "Unknown format parameter(s): #{unknown.inspect}. " unless unknown.empty?
+    end
+
+    # Applies a format template to produce a formatted string representation.
+    # @private
+    def format_amount(format)
+      format, value = select_format(format)
+      format ||= '%<symbol>s%<amount>f'
+      # Automatically adjust decimal places based on currency subunit if missing
+      format = format.gsub(/%<amount>(\s*\+?\d*)f/, "%<amount>\\1.#{currency.subunit}f")
+
+      refs = format.scan(/%<(\w+)>/).flatten.map(&:to_sym)
+      all_args = { amount: value, currency: currency_code, symbol: currency.symbol }
+      Kernel.format(format, **all_args.slice(*refs))
+    end
+  end
+end

data/lib/minting/money/{formatting.rb → format/to_s.rb}

@@ -45,10 +45,10 @@ module Mint
     #
     def to_s(format: '%<symbol>s%<amount>f', decimal: '.', thousand: ',', width: nil)
       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'
+      when {}, '' then raise ArgumentError, 'format must not be empty'
+      when Hash   then validate_format_hash(format)
+      when String then format = { positive: format }
+      else        raise ArgumentError, 'Invalid format. Only String or Hash are accepted'
       end
 
       formatted = format_amount(format)
@@ -61,44 +61,7 @@ module Mint
         formatted.gsub!(/(\d)(?=(?:\d{3})+(?:[^\d]{1}|$))/, "\\1#{thousand}")
       end
 
-      formatted = formatted.rjust(width) if width
-      formatted
-    end
-
-    private
-
-    def validate_format_hash!(format)
-      unknown = format.keys - %i[positive negative zero]
-
-      raise ArgumentError, "Unknown format parameter(s): #{unknown.inspect}. " unless unknown.empty?
-    end
-
-    def format_amount(format)
-      format = { positive: format } if format.is_a?(String)
-      positive_format = format[:positive]
-      negative_format = format[:negative]
-      zero_format = format[:zero]
-
-      if amount.negative? && negative_format
-        format = negative_format
-        value = -amount
-      elsif amount.zero? && zero_format
-        format = zero_format
-        value = amount
-      else
-        format = positive_format
-        value = amount
-      end
-      format ||= '%<symbol>s%<amount>f'
-
-      # Automatically adjust decimal places based on currency subunit if missing
-      adjusted_format = format
-                        .gsub(/%<amount>(\s*\+?\d*)f/, "%<amount>\\1.#{currency.subunit}f")
-
-      Kernel.format(adjusted_format,
-                    amount: value,
-                    currency: currency_code,
-                    symbol: currency.symbol)
+      width ? formatted.rjust(width) : formatted
     end
   end
 end

data/lib/minting/money/money.rb

@@ -43,63 +43,5 @@ module Mint
     # @param other [Currency] the target currency to compare
     # @return [Boolean] true if currencies match, false otherwise
     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
-
-    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/version.rb

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

data/minting.gemspec

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'minting/version'
@@ -15,18 +17,19 @@ Gem::Specification.new do |s|
   # Prevent pushing this gem to RubyGems.org.
   # To allow pushes either set the 'allowed_push_host' to allow pushing to
   # a single host or delete this section to allow pushing to any host.
-  raise 'RubyGems 3.2 or newer is required' unless s.respond_to?(:metadata)
+  raise 'RubyGems 3.3 or newer is required' unless s.respond_to?(:metadata)
 
   s.metadata = {
     'bug_tracker_uri' => "#{s.homepage}/issues",
     'changelog_uri' => "#{s.homepage}/blob/master/CHANGELOG.md",
+    'documentation_uri' => 'https://www.rubydoc.info/gems/minting',
     'homepage_uri' => s.homepage,
     'source_code_uri' => s.homepage,
     'allowed_push_host' => 'https://rubygems.org',
     'rubygems_mfa_required' => 'true'
   }
 
-  s.required_ruby_version = '>= 3.2.0'
+  s.required_ruby_version = '>= 3.3.0'
   s.add_dependency 'bigdecimal', '>= 4.0'
 
   s.files = Dir.glob('{bin,doc,lib}/**/*')

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: minting
 version: !ruby/object:Gem::Version
-  version: 1.6.3
+  version: 1.7.2
 platform: ruby
 authors:
 - Gilson Ferraz
@@ -32,31 +32,61 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- bin/bench_check
 - bin/check-currencies
 - bin/console
 - bin/setup
+- doc/Mint.html
+- doc/Mint/Currency.html
+- doc/Mint/CurrencyRegistry.html
+- doc/Mint/Money.html
+- doc/Mint/RangeStepPatch.html
+- doc/Mint/UnknownCurrency.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/agents/rubocop-issues.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/currency/currency.rb
+- lib/minting/currency/currency_registry.rb
+- lib/minting/currency/world_currencies.rb
 - lib/minting/data/world-currencies.yaml
 - lib/minting/mint.rb
 - lib/minting/mint/aliases.rb
-- lib/minting/mint/currency/currency.rb
-- lib/minting/mint/currency/currency_registry.rb
-- lib/minting/mint/currency/world_currencies.rb
-- lib/minting/mint/dsl.rb
+- lib/minting/mint/dsl/numeric.rb
+- lib/minting/mint/dsl/range.rb
+- lib/minting/mint/dsl/string.rb
+- lib/minting/mint/dsl/top_level.rb
 - lib/minting/mint/mint.rb
-- lib/minting/mint/parser.rb
-- lib/minting/money/allocation.rb
-- lib/minting/money/arithmetics.rb
+- lib/minting/mint/parser/parser.rb
+- lib/minting/mint/parser/separators.rb
+- lib/minting/money/allocation/allocation.rb
+- lib/minting/money/allocation/split.rb
+- lib/minting/money/arithmetics/methods.rb
+- lib/minting/money/arithmetics/operators.rb
+- lib/minting/money/clamp.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/format/formatting.rb
+- lib/minting/money/format/to_s.rb
 - lib/minting/money/money.rb
 - lib/minting/version.rb
 - minting.gemspec
@@ -66,6 +96,7 @@ licenses:
 metadata:
   bug_tracker_uri: https://github.com/gferraz/minting/issues
   changelog_uri: https://github.com/gferraz/minting/blob/master/CHANGELOG.md
+  documentation_uri: https://www.rubydoc.info/gems/minting
   homepage_uri: https://github.com/gferraz/minting
   source_code_uri: https://github.com/gferraz/minting
   allowed_push_host: https://rubygems.org
@@ -77,14 +108,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.9
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Library to manipulate currency values
 test_files: []

data/lib/minting/money/allocation.rb

@@ -1,59 +0,0 @@
-# frozen_string_literal: true
-
-module Mint
-  # Allocation and splitting
-  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?
-
-      subunit = currency.subunit
-      amounts = proportions.map { |rate| Rational(amount * rate, whole).round(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,
-              'quantity must be an integer > 0'
-      end
-
-      fraction = (amount / quantity).round(currency.subunit)
-      allocate_left_over!(amounts: Array.new(quantity, fraction),
-                          left_over: amount - (fraction * quantity))
-    end
-
-    private
-
-    def allocate_left_over!(amounts:, left_over:)
-      if left_over.nonzero?
-        minimum = currency.minimum_amount
-        minimum = -minimum if left_over.negative?
-        last_slot = (left_over / minimum).to_i - 1
-        (0..last_slot).each { |slot| amounts[slot] += minimum }
-      end
-      amounts.map { |amount| Money.new(amount, currency) }
-    end
-  end
-end