class Money::Currency

Represents a specific currency unit.

Attributes

decimal_mark[R]

The decimal mark, or character used to separate the whole unit from the subunit.

@return [String]

delimiter[R]

The character used to separate thousands grouping of the whole unit.

@return [String]

html_entity[R]

The html entity for the currency symbol

@return [String]

id[R]

The symbol used to identify the currency, usually the lowercase iso_code attribute.

@return [Symbol]

iso_code[R]

The international 3-letter code as defined by the ISO 4217 standard.

@return [String]

iso_numeric[R]

The international 3-numeric code as defined by the ISO 4217 standard.

@return [String]

name[R]

The currency name.

@return [String]

priority[R]

A numerical value you can use to sort/group the currency list.

@return [Integer]

separator[R]

The decimal mark, or character used to separate the whole unit from the subunit.

@return [String]

subunit[R]

The name of the fractional monetary unit.

@return [String]

subunit_to_unit[R]

The proportion between the unit and the subunit

@return [Integer]

symbol[R]

The currency symbol (UTF-8 encoded).

@return [String]

symbol_first[R]

Should the currency symbol precede the amount, or should it come after?

@return [Boolean]

thousands_separator[R]

The character used to separate thousands grouping of the whole unit.

@return [String]

Public Class Methods

all() click to toggle source

List the currencies imported and registered @return [Array]

@example

Money::Currency.iso_codes()
[#<Currency ..USD>, 'CAD', 'EUR']...
# File lib/money/currency.rb, line 99
def all
  table.keys.map {|curr| Currency.new(curr)}.sort_by(&:priority)
end
decimal_places_cache() click to toggle source

Cache decimal places for subunit_to_unit values. Common ones pre-cached.

# File lib/money/currency.rb, line 319
def self.decimal_places_cache
  @decimal_places_cache ||= {
    1 => 0,
    10 => 1,
    100 => 2,
    1000 => 3
  }
end
find(id) click to toggle source

Lookup a currency with given id an returns a Currency instance on success, nil otherwise.

@param [String, Symbol, to_s] id Used to look into table and retrieve the applicable attributes.

@return [Money::Currency]

@example

Money::Currency.find(:eur) #=> #<Money::Currency id: eur ...>
Money::Currency.find(:foo) #=> nil
# File lib/money/currency.rb, line 33
def find(id)
  id = id.to_s.downcase.to_sym
  new(id) if self.table[id]
end
find_by_iso_numeric(num) click to toggle source

Lookup a currency with given num as an ISO 4217 numeric and returns an Currency instance on success, nil otherwise.

@param [#to_s] num used to look into table in iso_numeric and find the right currency id.

@return [Money::Currency]

@example

Money::Currency.find_by_iso_numeric(978) #=> #<Money::Currency id: eur ...>
Money::Currency.find_by_iso_numeric('001') #=> nil
# File lib/money/currency.rb, line 49
def find_by_iso_numeric(num)
  num = num.to_s
  id, _ = self.table.find{|key, currency| currency[:iso_numeric] == num}
  new(id) if self.table[id]
end
new(id) click to toggle source

Create a new Currency object.

@param [String, Symbol, to_s] id Used to look into table and retrieve

the applicable attributes.

@return [Money::Currency]

@example

Money::Currency.new(:usd) #=> #<Money::Currency id: usd ...>
# File lib/money/currency.rb, line 195
def initialize(id)
  id = id.to_s.downcase
  raise(UnknownCurrency, "Unknown currency `#{id}'") unless self.class.stringified_keys.include?(id)

  @id  = id.to_sym
  data = self.class.table[@id]
  data.each_pair do |key, value|
    instance_variable_set(:"@#{key}", value)
  end
end
register(curr) click to toggle source
# File lib/money/currency.rb, line 110
def register(curr)
  key = curr[:iso_code].downcase.to_sym
  @table[key] = curr
  @stringified_keys = stringify_keys
end
stringified_keys() click to toggle source

We need a string-based validator before creating an unbounded number of symbols. www.randomhacks.net/articles/2007/01/20/13-ways-of-looking-at-a-ruby-symbol#11 github.com/RubyMoney/money/issues/132

# File lib/money/currency.rb, line 106
def stringified_keys
  @stringified_keys ||= stringify_keys
end
table() click to toggle source

List of known currencies.

monetary unit

The standard unit of value of a currency, as the dollar in the United States or the peso in Mexico. www.answers.com/topic/monetary-unit

fractional monetary unit, subunit

A monetary unit that is valued at a fraction (usually one hundredth) of the basic monetary unit www.answers.com/topic/fractional-monetary-unit-subunit

See en.wikipedia.org/wiki/List_of_circulating_currencies and search.cpan.org/~tnguyen/Locale-Currency-Format-1.28/Format.pm

# File lib/money/currency.rb, line 89
def table
  @table ||= load_currencies
end
wrap(object) click to toggle source

Wraps the object in a Currency unless it’s already a Currency object.

@param [Object] object The object to attempt and wrap as a Currency object.

@return [Money::Currency]

@example

c1 = Money::Currency.new(:usd)
Money::Currency.wrap(nil)   #=> nil
Money::Currency.wrap(c1)    #=> #<Money::Currency id: usd ...>
Money::Currency.wrap("usd") #=> #<Money::Currency id: usd ...>
# File lib/money/currency.rb, line 68
def wrap(object)
  if object.nil?
    nil
  elsif object.is_a?(Currency)
    object
  else
    Currency.new(object)
  end
end

Private Class Methods

stringify_keys() click to toggle source
# File lib/money/currency.rb, line 118
def stringify_keys
  table.keys.map{|k| k.to_s.downcase}
end

Public Instance Methods

<=>(other_currency) click to toggle source

Compares self with other_currency against the value of priority attribute.

@param [Money::Currency] other_currency The currency to compare to.

@return [-1,0,1] -1 if less than, 0 is equal to, 1 if greater than

@example

c1 = Money::Currency.new(:usd)
c2 = Money::Currency.new(:jpy)
c1 <=> c2 #=> 1
c2 <=> c1 #=> -1
c1 <=> c1 #=> 0
# File lib/money/currency.rb, line 219
def <=>(other_currency)
  self.priority <=> other_currency.priority
end
==(other_currency) click to toggle source

Compares self with other_currency and returns true if the are the same or if their id attributes match.

@param [Money::Currency] other_currency The currency to compare to.

@return [Boolean]

@example

c1 = Money::Currency.new(:usd)
c2 = Money::Currency.new(:jpy)
c1 == c1 #=> true
c1 == c2 #=> false
# File lib/money/currency.rb, line 235
def ==(other_currency)
  self.equal?(other_currency) ||
  self.id.to_s.downcase == (other_currency.is_a?(Currency) ? other_currency.id.to_s.downcase : other_currency.to_s.downcase)
end
code() click to toggle source

Returns currency symbol or iso code for currencies with no symbol.

@return [String]

# File lib/money/currency.rb, line 303
def code
  symbol || iso_code
end
decimal_places() click to toggle source

The number of decimal places needed.

@return [Integer]

# File lib/money/currency.rb, line 331
def decimal_places
  cache = self.class.decimal_places_cache
  places  = cache[subunit_to_unit]
  unless places
    places = calculate_decimal_places(subunit_to_unit)
    cache[subunit_to_unit] = places
  end
  places
end
eql?(other_currency) click to toggle source

Compares self with other_currency and returns true if the are the same or if their id attributes match.

@param [Money::Currency] other_currency The currency to compare to.

@return [Boolean]

@example

c1 = Money::Currency.new(:usd)
c2 = Money::Currency.new(:jpy)
c1.eql? c1 #=> true
c1.eql? c2 #=> false
# File lib/money/currency.rb, line 252
def eql?(other_currency)
  self == other_currency
end
exponent() click to toggle source

Returns the number of digits after the decimal separator.

@return [Float]

# File lib/money/currency.rb, line 314
def exponent
  Math.log10(@subunit_to_unit)
end
hash() click to toggle source

Returns a Fixnum hash value based on the id attribute in order to use functions like & (intersection), group_by, etc.

@return [Fixnum]

@example

Money::Currency.new(:usd).hash #=> 428936
# File lib/money/currency.rb, line 263
def hash
  id.hash
end
inspect() click to toggle source

Returns a human readable representation.

@return [String]

@example

Money::Currency.new(:usd) #=> #<Currency id: usd ...>
# File lib/money/currency.rb, line 273
def inspect
  "#<#{self.class.name} id: #{id}, priority: #{priority}, symbol_first: #{symbol_first}, thousands_separator: #{thousands_separator}, html_entity: #{html_entity}, decimal_mark: #{decimal_mark}, name: #{name}, symbol: #{symbol}, subunit_to_unit: #{subunit_to_unit}, exponent: #{exponent}, iso_code: #{iso_code}, iso_numeric: #{iso_numeric}, subunit: #{subunit}>"
end
symbol_first?() click to toggle source
# File lib/money/currency.rb, line 307
def symbol_first?
  !!@symbol_first
end
to_currency() click to toggle source

Conversation to self.

@return [self]

# File lib/money/currency.rb, line 295
def to_currency
  self
end
to_s() click to toggle source

Returns a string representation corresponding to the upcase id attribute.

-– DEV: id.to_s.upcase corresponds to iso_code but don’t use ISO_CODE for consistency.

@return [String]

@example

Money::Currency.new(:usd).to_s #=> "USD"
Money::Currency.new(:eur).to_s #=> "EUR"
# File lib/money/currency.rb, line 288
def to_s
  id.to_s.upcase
end

Private Instance Methods

calculate_decimal_places(num) click to toggle source

If we need to figure out how many decimal places we need we use repeated integer division.

# File lib/money/currency.rb, line 343
def calculate_decimal_places(num)
  return 0 if num == 1
  i = 1
  while num >= 10
    num /= 10
    i += 1 if num >= 10
  end
  i
end