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

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



55
56
57
58
59
60
61
62
63
 
# File 'lib/minting/currency/currency.rb', line 55

def Currency.resolve(object)
  case object
  when NilClass then nil
  when Currency then object
  when Money    then object.currency
  when String   then Mint.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



72
73
74
 
# File 'lib/minting/currency/currency.rb', line 72

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

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) = amount.to_r.round(subunit)