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



68
69
70
71
72
73
 
# File 'lib/minting/mint/registry.rb', line 68

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, Currency) —

    the currency identifier or object

Returns:

  • (Currency, nil) —

    the registered Currency instance or nil if not found



25
26
27
 
# File 'lib/minting/mint/registry.rb', line 25

def self.currency(currency)
  currency.is_a?(Currency) ? currency : currencies[currency]
end

.currency_symbols ⇒ Object

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



76
77
78
79
80
81
82
83
 
# File 'lib/minting/mint/registry.rb', line 76

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.create(amount, currency) if currency

  raise ArgumentError, "[#{currency.inspect}] is not a registered currency. Check Mint.currencies"
end

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

Registers a new currency if not already registered.

Parameters:

  • code (String) —

    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



37
38
39
 
# File 'lib/minting/mint/registry.rb', line 37

def self.register_currency(code:, subunit: 2, symbol: '', priority: 0)
  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) —

    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



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

def self.register_currency!(code:, subunit:, 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')"
  end

  currency = currencies[code]
  raise KeyError, "Currency: #{code} already registered" if currency

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

.zero ⇒ Object

Returns default zero, no currency money



18
 
# File 'lib/minting/mint/registry.rb', line 18

def self.zero = @zero ||= Money.new(0, Mint.currency('XXX'))