minting 1.6.0 → 1.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 293a64ebe3fd00ed8f6d062b596234550f85ead517b7f8094648dd9502be2f86
-  data.tar.gz: 3a98bb94ce601340b9cced8b275ee0be3e578d7e3cf781245cdd0fe5ee8038f1
+  metadata.gz: 3c50c230bea20784e9834f9f0c2fd9968b73cb94cbd14aa06a0eb4e3a3e41d74
+  data.tar.gz: d57f1a4e5a4664c721a286e1ff93eba1558cbf24babeaca6615af755d53663eb
 SHA512:
-  metadata.gz: fe587b6b5180c831b1e32092dfe9857ae37516f7fd274215be27e21af1263e99a93725f019e3be96962c5f20c13519326fc2b18b81b88e22aab43dc0d93a9b49
-  data.tar.gz: b0b8ca0b0dd832668e7b37dfbcca6e3606c673496c8149de90e9d2ffd21a166205e37ae9b455e36b1a71b07729a1d8c5bac074022991d45906ec7c410ec73740
+  metadata.gz: 1a4d800520eaa79c57a0cb0111e8b40dcf603fe49fdc697e2b065e3b295c2fe7599285f7af1bc987c0cec3ac13a94a95ef836eb741e86f34986e915e4f904daa
+  data.tar.gz: fc8840f398dead653854665cae2afea1f333e973678eac67df401c045af45ee5370a50f365debdd85f42404b80c10cd68c7bba5dc9b086afa2e9c705d323bbe2

data/README.md

@@ -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.)

data/lib/minting/mint/currency.rb

@@ -1,22 +1,33 @@
 # 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
+  # @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, :minimum_amount) do
+                         :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
-      minimum_amount = Rational(1, fractional_multiplier)
       super(code:, subunit:, symbol:, priority:, country:, name:,
-            fractional_multiplier:, minimum_amount:)
+            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

data/lib/minting/mint/mint.rb

@@ -3,7 +3,7 @@
 # Mint currency registration and factory (public API)
 module Mint
   # Unknown currency excpetion
-  class UnknownCurreny < StandardError
+  class UnknownCurrency < StandardError
   end
 
   # Creates a new {Money} instance with the given amount and currency code.

data/lib/minting/mint/parser.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# Mint Money parsing
 module Mint
   extend self
 

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/constructors.rb

@@ -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.6.0'
+  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.6.0
+  version: 1.6.1
 platform: ruby
 authors:
 - Gilson Ferraz