Class: Mint::Currency

Inherits:
Data
  • Object
show all
Defined in:
lib/minting/currency/currency.rb

Overview

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 Also:

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(code:, symbol:, subunit: 0, priority: 0, country: nil, name: nil) ⇒ Currency

Returns a new instance of Currency.

Parameters:

  • code (String) —

    ISO 4217 currency code

  • symbol (String) —

    Display symbol

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

    Number of decimal places (default 0)

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

    Parser precedence for symbol detection (default 0)

  • country (String, nil) (defaults to: nil) —

    Associated country code (default nil)

  • name (String, nil) (defaults to: nil) —

    Currency name (default nil)



26
27
28
29
30
31
32
 
# File 'lib/minting/currency/currency.rb', line 26

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

Instance Attribute Details

#code ⇒ String (readonly)

ISO 4217 currency code (e.g., “USD”, “EUR”)

Returns:

  • (String) —

    the current value of code



18
19
20
 
# File 'lib/minting/currency/currency.rb', line 18

def code
  @code
end

#country ⇒ String? (readonly)

Associated country code

Returns:

  • (String, nil) —

    the current value of country



18
19
20
 
# File 'lib/minting/currency/currency.rb', line 18

def country
  @country
end

#fractional_multiplier ⇒ Integer (readonly)

10^subunit, used for fractional conversions

Returns:

  • (Integer) —

    the current value of fractional_multiplier



18
19
20
 
# File 'lib/minting/currency/currency.rb', line 18

def fractional_multiplier
  @fractional_multiplier
end

#name ⇒ String? (readonly)

Currency name

Returns:

  • (String, nil) —

    the current value of name



18
19
20
 
# File 'lib/minting/currency/currency.rb', line 18

def name
  @name
end

#priority ⇒ Integer (readonly)

Parser precedence for symbol detection

Returns:

  • (Integer) —

    the current value of priority



18
19
20
 
# File 'lib/minting/currency/currency.rb', line 18

def priority
  @priority
end

#subunit ⇒ Integer (readonly)

Number of decimal places (0 for JPY, 2 for USD, 3 for IQD)

Returns:

  • (Integer) —

    the current value of subunit



18
19
20
 
# File 'lib/minting/currency/currency.rb', line 18

def subunit
  @subunit
end

#symbol ⇒ String (readonly)

Display symbol (e.g., “$”, “€”, “R$”)

Returns:

  • (String) —

    the current value of symbol



18
19
20
 
# File 'lib/minting/currency/currency.rb', line 18

def symbol
  @symbol
end

Class Method Details

.for_code(code) ⇒ Currency?

Looks up a registered currency by its alpha code.

Parameters:

  • code (String) —

    the currency code

Returns:

  • (Currency, nil) —

    the registered Currency, or nil if not found



95
96
97
 
# File 'lib/minting/currency/currency.rb', line 95

def Currency.for_code(code)
  Registry.currencies[code]
end

.for_symbol(symbol) ⇒ Currency?

Looks up a currency by its display symbol.

Parameters:

  • symbol (String) —

    the display symbol (e.g. “$”, “R$”)

Returns:

  • (Currency, nil) —

    the highest-priority currency for the symbol



103
104
105
 
# File 'lib/minting/currency/currency.rb', line 103

def Currency.for_symbol(symbol)
  Registry.currency_for_symbol(symbol)
end

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

Registers a new currency, raising a KeyError if already registered.

Parameters:

  • code (String) —

    the unique currency code

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

    the decimal subunit precision, defaults to 0

  • 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



57
58
59
 
# File 'lib/minting/currency/currency.rb', line 57

def Currency.register(code:, subunit: 0, symbol: '', priority: 0)
  Registry.register(code:, subunit:, symbol:, priority:)
end

.resolve(object) ⇒ Currency?

Resolves an object into a Mint::Currency, returning nil when it can’t.

Accepts nil, String, Mint::Currency, or Money. Passing a Money extracts its currency

Parameters:

  • object (String, Currency, Money, nil) —

    a currency code, object, or nil

Returns:

  • (Currency, nil) —

    the resolved Currency, or nil if object is nil or the code is not registered

Raises:

  • (ArgumentError) —

    if object is an unsupported type (e.g. Integer)



70
71
72
73
74
75
76
77
78
 
# File 'lib/minting/currency/currency.rb', line 70

def Currency.resolve(object)
  case object
  when NilClass then nil
  when Currency then object
  when Money    then object.currency
  when String   then Currency.for_code object
  else          raise ArgumentError, "currency must be [Currency], [Money], [String] or nil (#{object})"
  end
end

.resolve!(object) ⇒ Currency

Resolves an object into a Mint::Currency, raising on failure.

Like resolve but raises when the result would be nil.

Parameters:

  • object (String, Currency, Money, nil) —

    a currency code, object, or nil

Returns:

Raises:

  • (ArgumentError) —

    if object cannot be resolved into a registered currency



87
88
89
 
# File 'lib/minting/currency/currency.rb', line 87

def Currency.resolve!(object)
  resolve(object) or raise ArgumentError, "Could not resolve (#{object}) into a currency"
end

.zero(currency) ⇒ Money

Returns a zero Money in the given currency, useful as a default value for discounts, totals, or placeholders.

Parameters:

  • currency (String, Currency) —

    a currency code or object

Returns:

  • (Money) —

    a frozen zero-Money

Raises:

  • (ArgumentError) —

    if the currency can’t be resolved



113
 
# File 'lib/minting/currency/currency.rb', line 113

def Currency.zero(currency) = Registry.zero_for(Currency.resolve!(currency))

Instance Method Details

#inspect ⇒ String

Returns debug representation.

Returns:

  • (String) —

    debug representation



35
 
# File 'lib/minting/currency/currency.rb', line 35

def inspect = "<Currency:(#{code} #{symbol} #{subunit} #{name})>"

#minimum_amount ⇒ Rational

Returns smallest representable amount (1/fractional_multiplier).

Returns:

  • (Rational) —

    smallest representable amount (1/fractional_multiplier)



38
 
# File 'lib/minting/currency/currency.rb', line 38

def minimum_amount = Rational(1, fractional_multiplier)

#normalize_amount(amount) ⇒ Object

Normalizes numeric amounts for this currency

  1. Converts to Rational

  2. Rounds to respect currency subunit



43
 
# File 'lib/minting/currency/currency.rb', line 43

def normalize_amount(amount) = Mint::Rounding.apply(amount, subunit)

#zero ⇒ Object 



45
 
# File 'lib/minting/currency/currency.rb', line 45

def zero = Registry.zero_for(self)