Module: Mint

Defined in:
lib/minting/mint/refinements.rb,
lib/minting/money/money.rb,
lib/minting/money/parse.rb,
lib/minting/mint/currency.rb,
lib/minting/mint/registry.rb,
lib/minting/money/coercion.rb,
lib/minting/money/allocation.rb,
lib/minting/money/comparable.rb,
lib/minting/money/conversion.rb,
lib/minting/money/formatting.rb,
lib/minting/money/arithmetics.rb

Overview

Mint is a library to operate with monetary values

Defined Under Namespace

Classes: Currency, Money

Class Method Summary collapse

Class Method Details

.currencies ⇒ Hash{String => Currency}

Returns the hash of all registered currencies.

Returns:

  • (Hash{String => Currency}) —

    registered currencies mapped by code



74
75
76
77
78
79
 
# File 'lib/minting/mint/registry.rb', line 74

def self.currencies
  @currencies ||= begin
    registry = { 'XXX' => Currency.new(code: 'XXX', name: 'No currency', symbol: '¤') }
    load_currencies(registry)
  end
end

.currency(currency) ⇒ Currency?

Finds a registered currency by its code, symbol, or retrieves it directly if already a Currency object.

Parameters:

  • currency (String, Symbol, Currency) —

    the currency identifier or object

Returns:

  • (Currency, nil) —

    the registered Currency instance or nil if not found



22
23
24
25
26
27
28
29
30
31
 
# File 'lib/minting/mint/registry.rb', line 22

def self.currency(currency)
  case currency
  when Currency
    currency
  when Symbol
    currencies[currency.to_s]
  else
    currencies[currency]
  end
end

.currency_symbols ⇒ Object

Registered symbols sorted for detection: longest match wins, then parser priority.



82
83
84
85
86
87
88
89
 
# File 'lib/minting/mint/registry.rb', line 82

def self.currency_symbols
  @currency_symbols ||= begin
    currencies.values
              .map { |currency| [currency.symbol, currency] }
              .reject { |symbol, _| symbol.empty? }
              .sort_by { |symbol, currency| [-symbol.length, -currency.priority] }
  end.freeze
end

.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 (String, Symbol) —

    the ISO currency code or symbol

Returns:

  • (Money) —

    the instantiated Money object

Raises:

  • (ArgumentError) —

    if the currency code is not registered



10
11
12
13
14
15
 
# File 'lib/minting/mint/registry.rb', line 10

def self.money(amount, currency_code)
  currency = currency(currency_code)
  return Money.new(amount, currency) if currency

  raise ArgumentError, "Currency [#{currency_code}] not registered. Check Mint.currencies"
end

.register_currency(code:, subunit: 2, symbol: '$', priority: 0) ⇒ Currency

Registers a new currency if not already registered.

Parameters:

  • code (String, Symbol) —

    the unique currency code (e.g. ‘USD’, :EUR)

  • subunit (Integer) (defaults to: 2) —

    the decimal subunit precision (defaults to 2)

  • symbol (String) (defaults to: '$') —

    the display symbol (defaults to ‘$’)

  • priority (Integer) (defaults to: 0) —

    parser precedence priority (defaults to 0)

Returns:

  • (Currency) —

    the registered or existing Currency instance

Raises:

  • (ArgumentError) —

    if the code layout is invalid or register throws an error



41
42
43
44
 
# File 'lib/minting/mint/registry.rb', line 41

def self.register_currency(code:, subunit: 2, symbol: '$', priority: 0)
  code = code.to_s
  currencies[code] || register_currency!(code:, subunit:, symbol:, priority:)
end

.register_currency!(code:, subunit:, symbol: '', priority: 0) ⇒ Currency

Strictly registers a new currency, raising a KeyError if already registered.

Parameters:

  • code (String, Symbol) —

    the unique currency code

  • subunit (Integer) —

    the decimal subunit precision

  • symbol (String) (defaults to: '') —

    the display symbol

  • priority (Integer) (defaults to: 0) —

    parser precedence priority

Returns:

  • (Currency) —

    the newly registered Currency instance

Raises:

  • (ArgumentError) —

    if the code contains invalid characters

  • (KeyError) —

    if the currency code is already registered



55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/minting/mint/registry.rb', line 55

def self.register_currency!(code:, subunit:, symbol: '', priority: 0)
  code = code.to_s
  unless code.match?(/^[A-Z_]+$/)
    raise ArgumentError,
          "Currency code must be String or Symbol ('USD', :EUR, 'FUEL', 'MY_COIN')"
  end
  if currencies[code]
    raise KeyError,
          "Currency: #{code} already registered"
  end

  currencies[code] = Currency.new(code:, subunit:, symbol:, priority:)
  @currency_symbols = nil
  currencies[code]
end