minting 1.5.1 → 1.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40050495b5105709bf403740b7373079ee354a005bd3057891a28f756043025a
-  data.tar.gz: b6635617152e7794aefbf3b5ff2a601e8c6cf6a6f0b9660b69b985bde1d7f6d6
+  metadata.gz: 3c50c230bea20784e9834f9f0c2fd9968b73cb94cbd14aa06a0eb4e3a3e41d74
+  data.tar.gz: d57f1a4e5a4664c721a286e1ff93eba1558cbf24babeaca6615af755d53663eb
 SHA512:
-  metadata.gz: 2fa5d0bcbe484c2cb2ae87f2bb770f4a9fe4aadbcc123ed8b5ae1cc3b20553bfcfc73bb76e85d90d363cf428ef38bebb687531bb687cec249579ccc0fcda3b21
-  data.tar.gz: 4bcc01dea9e15a88552c171206b867aba3bf97a22cdd7e16b596b597527ae280ba9079e7ccd9bb61e498ba3f36c4bd17b4a29be949c8fea9caaaaa7f761a555d
+  metadata.gz: 1a4d800520eaa79c57a0cb0111e8b40dcf603fe49fdc697e2b065e3b295c2fe7599285f7af1bc987c0cec3ac13a94a95ef836eb741e86f34986e915e4f904daa
+  data.tar.gz: fc8840f398dead653854665cae2afea1f333e973678eac67df401c045af45ee5370a50f365debdd85f42404b80c10cd68c7bba5dc9b086afa2e9c705d323bbe2

data/README.md

@@ -148,7 +148,7 @@ price.clamp(min_price, 100) #=> [USD 75.00]
 
 **Zero equality** — Any zero amount is considered equal across currencies and to numeric zero `Mint.money(0, 'USD') == Mint.money(0, 'EUR')` is intentionally `true`. Non-zero amounts must match currency and value.
 
-**Custom currencies** — `Mint.register_currency` returns the existing entry if the code is already registered; use `register_currency!` to detect duplicates.
+**Custom currencies** — `Mint.register_currency`, Only registered currency codes and symbolos are recoginized by the parser.
 
 **Built-in currencies** — ISO-style codes ship in `lib/minting/data/currencies.yaml` and load when the registry is first accessed.
 
@@ -188,10 +188,10 @@ gem install minting
 ## Parsing strings
 
 ```ruby
-Mint::Money.parse('$19.99')           #=> [USD 19.99]
-Mint::Money.parse('19,99 €')          #=> [EUR 19.99]
-Mint::Money.parse('1.234,56', 'EUR')  #=> [EUR 1234.56]
-Mint::Money.parse('USD 1,234.56')     #=> [USD 1234.56]
+Mint.parse('$19.99')           #=> [USD 19.99]
+Mint.parse('19,99 €')          #=> [EUR 19.99]
+Mint.parse('1.234,56', 'EUR')  #=> [EUR 1234.56]
+Mint.parse('USD 1,234.56')     #=> [USD 1234.56]
 ```
 
 - Pass a currency code when the string has no symbol or code. 
@@ -212,75 +212,10 @@ Bug reports and pull requests are welcome on GitHub at <https://github.com/gferr
 
 1. Fork and create a feature branch
 2. Run the test suite: `rake`
-3. Run performance suites as needed: `BENCH=true rake bench:performance`
+3. Run performance suites as needed: `rake bench:performance`
 4. Open a PR with a clear description and benchmarks if relevant
 
 
-## Performance
-
-This gem includes a performance suite under `test/performance`:
-
-- Core operations (creation, arithmetic, comparisons)
-- Algorithm benchmarks (split, allocate)
-- Memory and GC pressure tests
-- Competitive benchmarks vs `money` gem
-
-Run locally:
-
-```bash
-# All performance suites
-BENCH=true rake bench:performance
-
-# Competitive vs money gem
-BENCH=true rake bench:competitive
-
-# Regression checks
-rake bench:regression
-```
-
-## Benchmark Summary: Minting vs Money Gem
-
-Generated by Qwen from the latest benchmark run on Ruby 4.0.1. - 2026-05-30
-
-### Key Takeaways
-
-- **Mint is consistently faster** than the Money gem across all measured operations.
-- **Mint is 2.28x faster** in the 50,000-transaction simulation.
-- **Mint object creation is 2.76x faster** than `Money.from_amount`.
-- In formatting and conversion, Mint is often **10+x **.
-- Mint’s performance advantage is especially strong for numeric conversion, string formatting, comparisons, and high-volume transaction loops.
-
-### Performance Highlights
-
-| Category | Mint | Money | Approx. Ratio |
-| --- | --- | --- | --- |
-| High-volume transactions | 195,412 ops/sec | 85,882 ops/sec | 2.28x faster |
-| `Mint.money` creation | 1.14M ops/sec | — | 2.76x faster than `Money.from_amount` |
-| `some.dollars` creation | 990k ops/sec | — | 1.15x faster than `Mint.money` |
-| `Money.new` creation | — | 715k ops/sec | Mint 1.59x faster |
-| `to_f` formatting | 8.8M–9.3M ops/sec | 0.7M ops/sec | ~12x faster |
-| `to_d` conversion | 2.1M–2.3M ops/sec | 0.73M–0.79M ops/sec | ~3x faster |
-| `to_s` formatting | 300k–420k ops/sec | 109k–132k ops/sec | ~3x faster |
-| `inspect` formatting | ~2.6–2.9M ops/sec | ~1.1–1.16M ops/sec | ~2.5x faster |
-| `to_json` formatting | ~2.0–2.2M ops/sec | ~110k–126k ops/sec | ~17x faster |
-| Currency lookup `Mint.currency('USD')` | 3.82M ops/sec | — | 1.60x faster than `Money::Currency.new` |
-| Currency lookup `Money::Currency.find('USD')` | 3.63M ops/sec | 1.67M ops/sec | 2.29x faster |
-| Addition | 1.11M ops/sec | 0.37M ops/sec | 3.0x faster |
-| Subtraction | 1.11M ops/sec | 0.36M ops/sec | 3.0x faster |
-| Multiplication | 1.28M ops/sec | 0.51M ops/sec | 2.5x faster |
-| Division | 1.04M ops/sec | 0.37M ops/sec | 2.8x faster |
-| Ratio division | 2.94M ops/sec | 0.39M ops/sec | 7.6x faster |
-| Comparison (`==`, `<`, `>`) | 2.5M–4.1M ops/sec | 0.35M–0.38M ops/sec | 7x–10x faster |
-| Allocation (`Mint.allocate`) | 279k ops/sec | 146k ops/sec | 1.9x faster |
-| Split (`Mint.split`) | 215k ops/sec | 85k ops/sec | 3.3x faster |
-
-### Commands Used
-
-```sh
-BENCH=true bundle exec ruby -Ilib:test -r ./test/test_helper.rb test/performance/competitive_performance_benchmark.rb
-BENCH=true bundle exec ruby -Ilib:test -r ./test/test_helper.rb test/performance/competitive_memory_benchmark.rb
-```
-
 ## License
 
 MIT

data/Rakefile

@@ -12,33 +12,29 @@ Rake::TestTask.new(:test) do |t|
   t.ruby_opts << '-rtest_helper.rb'
 end
 
-Rake::TestTask.new('bench') do |t|
+Rake::TestTask.new('bench:all') do |t|
   t.libs = %w[lib test]
-  t.pattern = 'test/performance/*_benchmark.rb'
+  t.pattern = 'test/performance/**/*_benchmark.rb'
 end
 
-Rake::TestTask.new('bench:parse') do |t|
+Rake::TestTask.new('bench:core') do |t|
   t.libs = %w[lib test]
-  t.pattern = 'test/performance/parse_benchmark.rb'
-  t.ruby_opts << '-r test_helper.rb'
+  t.pattern = 'test/performance/core/parse_benchmark.rb'
 end
 
-Rake::TestTask.new('bench:edge') do |t|
+Rake::TestTask.new('bench:memory') do |t|
   t.libs = %w[lib test]
-  t.pattern = 'test/performance/algorithm_benchmark.rb'
-  t.ruby_opts << '-r test_helper.rb'
+  t.pattern = 'test/performance/memory/*_benchmark.rb'
 end
 
 Rake::TestTask.new('bench:regression') do |t|
   t.libs = %w[lib test]
-  t.pattern = 'test/performance/regression_benchmark.rb'
-  t.ruby_opts << '-r test_helper.rb'
+  t.pattern = 'test/performance/regression/*_benchmark.rb'
 end
 
 Rake::TestTask.new('bench:competitive') do |t|
   t.libs = %w[lib test]
-  t.pattern = 'test/performance/competitive_performance_benchmark.rb'
-  t.ruby_opts << '-r test_helper.rb'
+  t.pattern = 'test/performance/competitive/**/*_benchmark.rb'
 end
 
 RuboCop::RakeTask.new(:cop)

data/doc/agents/AGENTS.md

@@ -20,6 +20,6 @@ Project highlights & conventions:
 - Amounts stored as Rational; prefer rationals or decimal strings for precision
 - Zero-equality: zeros equal across currencies; non-zero comparisons require same currency
 - Currency codes must match /^[A-Z_]+$/
-- Tests: Minitest; performance benches under test/performance (use BENCH=true)
+- Tests: Minitest; performance benches under test/performance 
 
 Edit guidance: keep this file minimal and link to existing docs; add repo-specific agent tips here.

data/doc/agents/copilot-instructions.md

@@ -21,9 +21,9 @@ Build, test and lint commands
 - Run a single test method by name (Minitest -n regexp):
   - ruby -Ilib:test -r ./test/test_helper.rb test/money/money_test.rb -n /test_creation/
 
-- Performance suites (set BENCH=true as in README):
-  - BENCH=true rake bench:performance
-  - BENCH=true rake bench:competitive
+- Performance suites:
+  - rake bench:performance
+  - rake bench:competitive
   - rake bench:regression
 
 - Linting:
@@ -56,7 +56,7 @@ Key conventions and repo-specific rules
 - Currency registration: use Mint.register_currency for idempotent registration; Mint.register_currency! raises on duplicates. Codes must match /^[A-Z_]+$/.
 - Symbol parsing: parser resolves symbols by longest match then currency priority (see Mint.currency_symbols sorting).
 - Tests: test_helper.rb configures coverage (SimpleCov) and loads minitest; when running tests outside rake, require test_helper (-r ./test/test_helper.rb).
-- Benchmarks: set BENCH=true to enable benchmark-heavy tasks; benchmarks use Minitest::Benchmark patterns.
+- Benchmarks: set to enable benchmark-heavy tasks; benchmarks use Minitest::Benchmark patterns.
 - Formatting: Money.to_s uses Kernel.format patterns; take care with %<amount>f vs %<amount>d depending on desired rounding/formatting.
 
 Files and places to check first during edits

data/doc/agents/recommendations.md

@@ -87,7 +87,7 @@ Qwen run on 2026-05-30 and aren't reproducible from CI.
 **Concrete action:** in CI, run
 
 ```sh
-BENCH=true rake bench:regression
+ake bench:regression
 ```
 
 and fail the build if any benchmark regresses by more than (e.g.)
@@ -208,7 +208,7 @@ property test:
 
 ```ruby
 m = Mint.money(9.99, 'USD')
-assert_equal m, Mint::Money.parse(m.inspect.delete_prefix('[').delete_suffix(']'))
+assert_equal m, Mint.parse(m.inspect.delete_prefix('[').delete_suffix(']'))
 ```
 
 Make it a one-liner or a property-based test with 10–20 random

data/lib/minting/data/currencies.yaml

@@ -709,3 +709,9 @@
   symbol: T$
   name: Tongan Paʻanga
   priority: 1
+- code: XXX
+  country:
+  subunit: 0
+  symbol: ¤
+  name: No Currency
+  priority: 0

data/lib/minting/mint/currency.rb

@@ -1,34 +1,36 @@
 # frozen_string_literal: true
 
 module Mint
-  # Represents a specific currency unit, identified by ISO 4217 alphabetic code
+  # Represents a specific currency unit, identified by ISO 4217 alphabetic code.
+  # Currency objects are immutable and define the properties of a monetary unit
+  # including its subunit precision, display symbol, and formatting rules.
   #
   # @see https://www.iso.org/iso-4217-currency-codes.html
-  class Currency
-    attr_reader :code, :subunit, :symbol,
-                :country,
-                :fractional_multiplier, :minimum_amount,
-                :name, :priority
+  # @attr_reader code [String] ISO 4217 currency code (e.g., "USD", "EUR")
+  # @attr_reader subunit [Integer] Number of decimal places (0 for JPY, 2 for USD, 3 for IQD)
+  # @attr_reader symbol [String] Display symbol (e.g., "$", "€", "R$")
+  # @attr_reader priority [Integer] Parser precedence for symbol detection
+  # @attr_reader country [String, nil] Associated country code
+  # @attr_reader name [String, nil] Currency name
+  # @attr_reader fractional_multiplier [Integer] 10^subunit, used for fractional conversions
+  # @attr_reader minimum_amount [Rational] Smallest representable amount (1/fractional_multiplier)
+  Currency = Data.define(:code, :subunit, :symbol, :priority, :country, :name,
+                         :fractional_multiplier) do
+    def initialize(code:, symbol:, subunit: 0, priority: 0, country: nil, name: nil)
+      subunit = subunit.to_i
+      priority = priority.to_i
+      fractional_multiplier = 10**subunit
+      super(code:, subunit:, symbol:, priority:, country:, name:,
+            fractional_multiplier:)
+    end
 
     def inspect = "<Currency:(#{code} #{symbol} #{subunit} #{name})>"
 
+    def minimum_amount = Rational(1, fractional_multiplier)
+
     # Normalizes numeric amounts for this currency
     # 1. Converts to Rational
     # 2. Rounds to respect currency subunit
     def normalize_amount(amount) = amount.to_r.round(subunit)
-
-    private
-
-    def initialize(code:, symbol:, subunit: 0, priority: 0, country: nil, name: nil)
-      @code = code
-      @subunit = subunit.to_i
-      @symbol = symbol
-      @priority = priority.to_i
-      @country = country
-      @name = name
-      @fractional_multiplier = 10**@subunit
-      @minimum_amount = Rational(1, fractional_multiplier)
-      freeze
-    end
   end
 end

data/lib/minting/mint/currency_store.rb

@@ -4,25 +4,24 @@ require 'yaml'
 
 # Mint currency store (internal)
 module Mint
-  # Internal currency storage and loading.
+  # Internal currency registry
   # Manages the registry cache and currency symbol lookups.
-  module CurrencyStore
+  module Registry
+    module_function
+
     # Returns the hash of all registered currencies.
     #
     # @return [Hash{String => Currency}] registered currencies mapped by code
     # @api private
-    def self.currencies
-      @currencies ||= begin
-        registry = { 'XXX' => Currency.new(code: 'XXX', name: 'No currency', symbol: '¤') }
-        load_currencies(registry)
-      end
+    def currencies
+      @currencies ||= Mint.world_currencies.dup
     end
 
     # Registered symbols sorted for detection: longest match wins, then parser priority.
     #
     # @return [Array<Array<String, Currency>>] sorted symbol-to-currency mappings
     # @api private
-    def self.currency_symbols
+    def currency_symbols
       @currency_symbols ||= begin
         currencies.values
                   .reject { |currency| currency.symbol.empty? }
@@ -35,34 +34,8 @@ module Mint
     # Called when currencies are registered.
     #
     # @api private
-    def self.invalidate_symbols_cache
+    def invalidate_symbols_cache
       @currency_symbols = nil
     end
-
-    # Loads currencies from YAML file into the registry.
-    #
-    # @param registry [Hash] the registry hash to populate
-    # @return [Hash] the populated registry
-    # @api private
-    def self.load_currencies(registry)
-      base = File.expand_path('../data', __dir__)
-      path = File.join(base, 'currencies.yaml')
-
-      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
 end

data/lib/minting/mint/mint.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# Mint currency registration and factory (public API)
+module Mint
+  # Unknown currency excpetion
+  class UnknownCurrency < StandardError
+  end
+
+  # Creates a new {Money} instance with the given amount and currency code.
+  #
+  # @param amount [Numeric] the financial value
+  # @param currency_code [Currency, String] Currency code
+  # @return [Money] the instantiated Money object
+  # @raise [ArgumentError] if the currency code is not registered
+  def self.money(amount, currency_code) = Money.create(amount, currency_code)
+
+  # Finds a registered currency by its code, symbol,
+  # or retrieves it directly if already a Currency object.
+  #
+  # @param currency [String, 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 nil      then nil
+    when Currency then currency
+    when String   then Registry.currencies[currency]
+    else raise ArgumentError, "currency must be [Currency] ot [String] (#{currency})"
+    end
+  end
+end

data/lib/minting/mint/parser.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+# Mint Money parsing
+module Mint
+  extend self
+
+  # Parses a human-readable money string into a {Money} object.
+  #
+  # @param input [String] Amount input, optionally including a currency symbol or code
+  # @param currency [String, Symbol, Currency, nil] ISO code when not present in +input+
+  # @return [Money]
+  # @raise [ArgumentError] when +input+ is invalid or currency cannot be determined
+  #
+  # @example With explicit currency
+  #   Money.parse('19.99', 'USD')    #=> [USD 19.99]
+  #   Money.parse('1.234,56', 'EUR') #=> [EUR 1234.56]
+  #
+  # @example With symbol or code in the string
+  #   Money.parse('$19.99')            #=> [USD 19.99]
+  #   Money.parse('19,99 €')         #=> [EUR 19.99]
+  #   Money.parse('USD 1,234.56')    #=> [USD 1234.56]
+  def parse(input, currency = nil)
+    raise ArgumentError, 'input must be a String' unless input.is_a?(String)
+
+    input = input.strip
+    raise ArgumentError, 'input cannot be empty' if input.empty?
+
+    currency = Mint.currency(currency) || parse_currency(input)
+    raise ArgumentError, "Currency [#{currency}] not registered" unless currency
+
+    amount = currency.normalize_amount(parse_amount(input))
+    Mint::Money.new(amount, currency)
+  end
+
+  private
+
+  # Extracts a numeric value from input that should only contain an amount.
+  def parse_amount(input)
+    # Remove any charater that is not a digit, comma or period
+    numeric = input.scan(/[\d.,-]/).join
+    numeric = normalize_separators(numeric)
+    Rational(numeric)
+  end
+
+  # Converts locale-specific decimal/thousand separators into a plain decimal string.
+  def normalize_separators(numeric)
+    case [numeric.count(','), numeric.count('.')]
+    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.
+      if numeric.rindex(',') > numeric.rindex('.')
+        numeric.delete('.').tr(',', '.')
+      else
+        numeric.delete(',')
+      end
+    else # Multiple of the same separator only (e.g. 1,234,567) — all are thousands.
+      numeric.delete(',.')
+    end
+  end
+
+  def parse_currency(input)
+    case input
+    when nil then return nil
+    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
+
+      # 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'
+  end
+end

data/lib/minting/mint/refinements.rb

@@ -25,8 +25,6 @@ module Mint
   end
 
   refine String do
-    def to_money(currency)
-      Mint.money(to_r, currency)
-    end
+    def to_money(currency) = Mint.money(to_r, currency)
   end
 end

data/lib/minting/mint/registry.rb

@@ -2,61 +2,27 @@
 
 # Mint currency registration and factory (public API)
 module Mint
-  # Creates a new {Money} instance with the given amount and currency code.
-  #
-  # @param amount [Numeric] the financial value
-  # @param currency_code [String] the ISO currency code
-  # @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.create(amount, currency) if currency
-
-    raise ArgumentError, "[#{currency.inspect}] is not a registered currency."
-  end
-
-  # Finds a registered currency by its code, symbol,
-  # or retrieves it directly if already a Currency object.
-  #
-  # @param currency [String, Currency] the currency identifier or object
-  # @return [Currency, nil] the registered Currency instance or nil if not found
-  def self.currency(currency)
-    currency.is_a?(Currency) ? currency : CurrencyStore.currencies[currency]
-  end
-
-  # Registers a new currency if not already registered.
-  #
-  # @param code [String] 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: 0, symbol: '', priority: 0)
-    CurrencyStore.currencies[code] || register_currency!(code:, subunit:, symbol:, priority:)
-  end
-
-  # Strictly registers a new currency, raising a KeyError if already registered.
+  # Registers a new currency, raising a KeyError if already registered.
   #
   # @param code [String] the unique currency code
-  # @param subunit [Integer] the decimal subunit precision
+  # @param subunit [Integer] the decimal subunit precision, defaults to 0
   # @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)
+  def self.register_currency(code:, subunit: 0, symbol: '', priority: 0)
     raise ArgumentError, 'Currency code must be String' unless code.is_a? String
     unless code.match?(/^[A-Z_]+$/)
       raise ArgumentError,
-            "Currency code must only letters or '_' ('USD',, 'MY_COIN')"
+            "Currency code must have only letters or '_' ('USD',, 'MY_COIN')"
     end
 
-    currencies = CurrencyStore.currencies
+    currencies = Registry.currencies
     raise KeyError, "Currency: #{code} already registered" if currencies[code]
 
     currency = currencies[code] = Currency.new(code:, subunit:, symbol:, priority:)
-    CurrencyStore.invalidate_symbols_cache
+    Registry.invalidate_symbols_cache
     currency
   end
 
@@ -66,6 +32,6 @@ module Mint
   # @return [Array<Array<String, Currency>>] sorted symbol-to-currency mappings
   # @api private
   def self.currency_symbols
-    CurrencyStore.currency_symbols
+    Registry.currency_symbols
   end
 end

data/lib/minting/mint/world_currencies.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Mint
+  module_function
+
+  # Loads ISO world currencies from YAML file into the registry.
+  #
+  # @return [Hash{String => Currency}] ISO-4217 world currencies mapped by code
+  # @api private
+  def world_currencies
+    @world_currencies ||= begin
+      path = File.join(File.expand_path('../data', __dir__), 'currencies.yaml')
+
+      YAML.load_file(path).to_h { |entry| [entry['code'], Currency.new(**entry.transform_keys(&:to_sym))] }
+    end.freeze
+  end
+end

data/lib/minting/mint.rb

@@ -2,5 +2,16 @@
 
 require 'minting/mint/currency'
 require 'minting/mint/currency_store'
+require 'minting/mint/mint'
+require 'minting/mint/parser'
 require 'minting/mint/registry'
 require 'minting/mint/refinements'
+require 'minting/mint/world_currencies'
+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/money/allocation.rb

@@ -18,7 +18,7 @@ module Mint
       raise ArgumentError, 'Proportions total must not be zero' if whole.zero?
 
       subunit = currency.subunit
-      amounts = proportions.map { |rate| (amount * rate.to_r / whole).round(subunit) }
+      amounts = proportions.map { |rate| Rational(amount * rate, whole).round(subunit) }
       allocate_left_over!(amounts: amounts, left_over: amount - amounts.sum)
     end
 

data/lib/minting/money/arithmetics.rb

@@ -53,9 +53,7 @@ module Mint
     # Unary negation operator. Returns a new {Money} instance with the inverted sign.
     #
     # @return [Money] negated Money instance
-    def -@
-      mint(-amount)
-    end
+    def -@ = mint(-amount)
 
     # Performs multiplication of the monetary value by a standard scalar Numeric.
     #

data/lib/minting/money/coercion.rb

@@ -4,9 +4,13 @@ module Mint
   # Implements the standard Ruby coercion protocol.
   class Money
     # Allows {Money} to interact seamlessly as the right-hand operand in Numeric arithmetic.
+    # This enables expressions like `5 + money` where `5` is a Numeric and `money` is a Money object.
     #
     # @param other [Numeric] the left-hand operand to coerce
     # @return [Array(CoercedNumber, Money)] coerced operand array
+    # @example
+    #   price = Mint.money(10, 'USD')
+    #   5 + price  #=> [USD 15.00] (via coercion)
     def coerce(other)
       [CoercedNumber.new(other), self]
     end

data/lib/minting/money/comparable.rb

@@ -7,9 +7,11 @@ 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?
-
-      eql?(other)
+      case other
+      when 0           then zero?
+      when Mint::Money then amount == other.amount && currency == other.currency
+      else                  false
+      end
     end
 
     def eql?(other)

data/lib/minting/money/constructors.rb

@@ -5,7 +5,7 @@ module Mint
   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
+    # @param currency [Currency, String] The currency code or 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)
@@ -44,9 +44,16 @@ module Mint
       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
+    # Returns a new Money object with the specified amount, or self if unchanged.
+    # This is the primary method for creating a modified copy of a Money instance
+    # while preserving immutability.
+    #
+    # @param new_amount [Numeric] The new monetary amount
+    # @return [Money] A new Money object with the new amount, or self if the amount is unchanged
+    # @example
+    #   price = Mint.money(10.00, 'USD')
+    #   price.mint(15.00)  #=> [USD 15.00]
+    #   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)

data/lib/minting/money/conversion.rb

@@ -9,6 +9,8 @@ module Mint
     # Converts the monetary amount to a BigDecimal object.
     #
     # @return [BigDecimal] the decimal representation of the money amount
+    # @example
+    #   Mint.money(9.99, 'USD').to_d  #=> 0.999e1
     def to_d = amount.to_d 0
 
     # Converts the monetary amount to a standard float.
@@ -31,8 +33,17 @@ module Mint
     # Truncates and converts the monetary amount to an Integer.
     #
     # @return [Integer] the integer representation of the money amount
+    # @example
+    #   Mint.money(9.99, 'USD').to_i  #=> 9
+    #   Mint.money(-9.99, 'USD').to_i #=> -9
     def to_i = amount.to_i
 
+    # Returns a Hash representation of the money instance.
+    #
+    # @return [Hash] hash with :currency (String) and :amount (String) keys
+    # @example
+    #   Mint.money(134120, 'BRL').to_hash
+    #   #=> { currency: "BRL", amount: "134120.00" }
     def to_hash
       { currency: currency_code, amount: Kernel.format("%0.#{currency.subunit}f", amount) }
     end

data/lib/minting/money/money.rb

@@ -11,9 +11,19 @@ module Mint
 
     # Returns the ISO 3-letter currency code string.
     #
-    # @return [String] the ISO currency code
+    # @return [String] the ISO currency code (e.g., "USD", "EUR", "BRL")
+    # @example
+    #   Mint.money(100, 'USD').currency_code  #=> "USD"
     def currency_code = currency.code
 
+    # Returns the monetary amount expressed in the currency's smallest unit (fractional units).
+    # For example, cents for USD (subunit 2), yen for JPY (subunit 0), fils for IQD (subunit 3).
+    #
+    # @return [Integer] the amount in fractional units
+    # @example
+    #   Mint.money(1234.56, 'USD').fractional  #=> 123456
+    #   Mint.money(1000, 'JPY').fractional     #=> 1000
+    #   Mint.money(123.456, 'IQD').fractional  #=> 123456
     def fractional = (amount * currency.fractional_multiplier).to_i
 
     # Generates a stable hash key for Money instances.

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.5.1'
+  VERSION = '1.6.1'
 end

data/lib/minting.rb

@@ -1,5 +1,4 @@
 # 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.5.1
+  version: 1.6.1
 platform: ruby
 authors:
 - Gilson Ferraz
@@ -44,9 +44,11 @@ files:
 - lib/minting/mint.rb
 - lib/minting/mint/currency.rb
 - lib/minting/mint/currency_store.rb
+- lib/minting/mint/mint.rb
+- lib/minting/mint/parser.rb
 - lib/minting/mint/refinements.rb
 - lib/minting/mint/registry.rb
-- lib/minting/money.rb
+- lib/minting/mint/world_currencies.rb
 - lib/minting/money/allocation.rb
 - lib/minting/money/arithmetics.rb
 - lib/minting/money/coercion.rb
@@ -55,7 +57,6 @@ files:
 - lib/minting/money/conversion.rb
 - lib/minting/money/formatting.rb
 - lib/minting/money/money.rb
-- lib/minting/money/parse.rb
 - lib/minting/version.rb
 - minting.gemspec
 homepage: https://github.com/gferraz/minting

data/lib/minting/money/parse.rb

@@ -1,79 +0,0 @@
-# frozen_string_literal: true
-
-module Mint
-  # Money parser
-  class Money
-    # Parses a human-readable money string into a {Money} object.
-    #
-    # @param input [String] Amount input, optionally including a currency symbol or code
-    # @param currency [String, Symbol, Currency, nil] ISO code when not present in +input+
-    # @return [Money]
-    # @raise [ArgumentError] when +input+ is invalid or currency cannot be determined
-    #
-    # @example With explicit currency
-    #   Money.parse('19.99', 'USD')    #=> [USD 19.99]
-    #   Money.parse('1.234,56', 'EUR') #=> [EUR 1234.56]
-    #
-    # @example With symbol or code in the string
-    #   Money.parse('$19.99')            #=> [USD 19.99]
-    #   Money.parse('19,99 €')         #=> [EUR 19.99]
-    #   Money.parse('USD 1,234.56')    #=> [USD 1234.56]
-    def self.parse(input, currency = nil)
-      raise ArgumentError, 'input must be a String' unless input.is_a?(String)
-
-      input = input.strip
-      raise ArgumentError, 'input cannot be empty' if input.empty?
-
-      currency = parse_currency(currency) || parse_currency(input)
-      raise ArgumentError, "Currency [#{currency}] not registered" unless currency
-
-      amount = currency.normalize_amount(parse_amount(input))
-      new(amount, currency)
-    end
-
-    # Extracts a numeric value from input that should only contain an amount.
-    def self.parse_amount(input)
-      # Remove any charater that is not a digit, comma or period
-      numeric = input.scan(/[\d.,-]/).join
-      numeric = normalize_separators(numeric)
-      Rational(numeric)
-    end
-
-    # 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] 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.
-        if numeric.rindex(',') > numeric.rindex('.')
-          numeric.delete('.').tr(',', '.')
-        else
-          numeric.delete(',')
-        end
-      else # Multiple of the same separator only (e.g. 1,234,567) — all are thousands.
-        numeric.delete(',.')
-      end
-    end
-
-    def self.parse_currency(input)
-      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
-
-        # 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'
-    end
-
-    private_class_method :parse_amount, :normalize_separators,
-                         :parse_currency
-  end
-end

data/lib/minting/money.rb

@@ -1,11 +0,0 @@
-# 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'