Module: Mint

Extended by:
Mint
Included in:
Mint
Defined in:
lib/minting/mint/mint.rb,
lib/minting/money/clamp.rb,
lib/minting/money/money.rb,
lib/minting/mint/rounding.rb,
lib/minting/mint/dsl/range.rb,
lib/minting/money/coercion.rb,
lib/minting/mint/dsl/string.rb,
lib/minting/mint/dsl/numeric.rb,
lib/minting/money/comparable.rb,
lib/minting/money/conversion.rb,
lib/minting/currency/currency.rb,
lib/minting/money/format/to_s.rb,
lib/minting/mint/dsl/top_level.rb,
lib/minting/mint/parser/parser.rb,
lib/minting/money/constructors.rb,
lib/minting/mint/locale_backend.rb,
lib/minting/mint/registry/zeros.rb,
lib/minting/mint/registry/symbols.rb,
lib/minting/mint/parser/separators.rb,
lib/minting/mint/registry/registry.rb,
lib/minting/money/allocation/split.rb,
lib/minting/money/format/formatting.rb,
lib/minting/money/arithmetics/methods.rb,
lib/minting/mint/registry/registration.rb,
lib/minting/money/allocation/allocation.rb,
lib/minting/money/arithmetics/operators.rb

Overview

Mint registry: manages all cached state

Defined Under Namespace

Modules: RangeStepPatch, Registry, Rounding Classes: Currency, Money, UnknownCurrency

Class Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Class Attribute Details

.locale_backend ⇒ Proc, ...

Optional callable that returns a Hash with locale-aware formatting defaults.

The callable receives no arguments and returns a Hash with these keys:

[+:decimal+]   Decimal separator (e.g. +","+)
[+:thousand+]  Thousands delimiter (e.g. +"."+)
[+:format+]    Format template string (e.g. +"%<amount>f %<symbol>s"+)

When set, #to_s and #format use these values as fallbacks when the corresponding parameter is not explicitly provided.

Examples:

Rails I18n integration (in minting-rails railtie)

Mint.locale_backend = -> {
  fmt = I18n.t('number.currency.format')
  {
    decimal: fmt[:separator],
    thousand: fmt[:delimiter],
    format: fmt[:format] == '%n %u' ? '%<amount>f %<symbol>s' : '%<symbol>s%<amount>f'
  }
}

Returns:

  • (Proc, #call, nil) 


27
28
29
 
# File 'lib/minting/mint/locale_backend.rb', line 27

def locale_backend
  @locale_backend
end

Class Method Details

.money(amount, currency_code) ⇒ Money

Creates a new Money instance with the given amount and currency code.

Parameters:

  • amount (Numeric) —

    the financial value

  • currency_code (Currency, String) —

    Currency code

Returns:

  • (Money) —

    the instantiated Money object

Raises:

  • (ArgumentError) —

    if the currency code is not registered



15
 
# File 'lib/minting/mint/mint.rb', line 15

def self.money(amount, currency_code) = Money.from(amount, currency_code)

.use_top_level_constants! ⇒ Object

Registers top-level ::Money and ::Currency constants as aliases for Mint’s classes.

Raises:

  • (NameError) —

    if ::Money or ::Currency are already defined and differ



8
9
10
11
12
13
14
15
16
 
# File 'lib/minting/mint/dsl/top_level.rb', line 8

def self.use_top_level_constants!
  if !defined?(::Money) && !defined?(::Currency)
    require 'minting/mint/aliases'
  elsif ::Money == Mint::Money && ::Currency == Mint::Currency
    warn 'Warning: Money and Currency already defined as Mint aliases, skipping'
  else
    raise NameError, 'Cannot define top-level Money or Currency constants: already defined'
  end
end

.with_rounding(mode) { ... } ⇒ Object

Executes a block with a specific rounding mode applied to all money construction, parsing, change, allocation, and split operations.

Restores the previous mode (or default) when the block exits, even on exception.

Parameters:

  • mode (Symbol) —

    one of: :half_up, :half_down, :floor, :ceil, :truncate, :down

Yields:

  • block to execute with the rounding mode active

Raises:

  • (ArgumentError) —

    if mode is not a recognised rounding mode



31
 
# File 'lib/minting/mint/mint.rb', line 31

def self.with_rounding(mode, &) = Rounding.with_mode(mode, &)

.world_currencies ⇒ Hash{String => Currency}

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the frozen world-currencies hash.

Returns:

  • (Hash{String => Currency}) —

    the frozen world-currencies hash



19
 
# File 'lib/minting/mint/mint.rb', line 19

def self.world_currencies = Registry.world_currencies

Instance Method Details

#parse(input, currency = nil) ⇒ Money?

Parses a human-readable money string into a Money object.

Returns nil when the input is invalid or currency cannot be determined.

Examples:

With explicit currency

Mint.parse('19.99', 'USD')    #=> [USD 19.99]
Mint.parse('garbage', 'USD')  #=> nil

With symbol or code in the string

Mint.parse('$19.99')            #=> [USD 19.99]
Mint.parse('USD 1,234.56')    #=> [USD 1234.56]

Parameters:

  • input (String) —

    Amount input, optionally including a currency symbol or code

  • currency (String, Symbol, Currency, nil) (defaults to: nil) —

    ISO code when not present in input

Returns:



22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
 
# File 'lib/minting/mint/parser/parser.rb', line 22

def parse(input, currency = nil)
  return nil unless input.is_a?(String)

  input = input.strip
  return nil if input.empty?

  currency = parse_currency(input, currency)
  return nil unless currency

  amount = parse_amount(input)
  return nil unless amount

  amount = currency.normalize_amount(amount)
  Mint::Money.new(amount, currency)
end

#parse!(input, currency = nil) ⇒ Money

Like #parse but raises on failure.

Examples:

Mint.parse!('19.99', 'USD')    #=> [USD 19.99]
Mint.parse!('garbage', 'USD')  #=> ArgumentError

Parameters:

  • input (String) —

    Amount input, optionally including a currency symbol or code

  • currency (String, Symbol, Currency, nil) (defaults to: nil) —

    ISO code when not present in input

Returns:

Raises:

  • (ArgumentError) —

    when input is invalid or currency cannot be determined



48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/minting/mint/parser/parser.rb', line 48

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 = parse_currency(input, currency)
  raise ArgumentError, "Currency [#{currency}] not found" unless currency

  amount = parse_amount(input)
  raise ArgumentError, "Could not parse [#{input}]" unless amount

  amount = currency.normalize_amount(amount)
  Mint::Money.new(amount, currency)
end