Class: Money::Currency

Inherits:
Object
  • Object
show all
Extended by:
Enumerable, Heuristics, Loader
Includes:
Comparable
Defined in:
lib/money/currency.rb,
lib/money/currency/loader.rb,
lib/money/currency/heuristics.rb

Overview

Represents a specific currency unit.

Defined Under Namespace

Modules: Heuristics, Loader Classes: MissingAttributeError, UnknownCurrency

Constant Summary collapse

@@mutex =

Keeping cached instances in sync between threads

Mutex.new
@@instances =
{}

Constants included from Loader

Loader::DATA_PATH

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Heuristics

analyze

Methods included from Loader

load_currencies

Constructor Details

#initialize(id) ⇒ Money::Currency

Create a new Currency object.

Examples:

Money::Currency.new(:usd) #=> #<Money::Currency id: usd ...>

Parameters:

  • id (String, Symbol, #to_s)

    Used to look into table and retrieve the applicable attributes.


262
263
264
265
# File 'lib/money/currency.rb', line 262

def initialize(id)
  @id = id.to_sym
  initialize_data!
end

Instance Attribute Details

#decimal_markString (readonly) Also known as: separator

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

Returns:

  • (String)

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


245
246
247
# File 'lib/money/currency.rb', line 245

attr_reader :id, :priority, :iso_code, :iso_numeric, :name, :symbol,
:disambiguate_symbol, :html_entity, :subunit, :subunit_to_unit, :decimal_mark,
:thousands_separator, :symbol_first, :smallest_denomination

#disambiguate_symbolString (readonly)

Returns Alternative currency used if symbol is ambiguous.

Returns:

  • (String)

    Alternative currency used if symbol is ambiguous


245
246
247
# File 'lib/money/currency.rb', line 245

attr_reader :id, :priority, :iso_code, :iso_numeric, :name, :symbol,
:disambiguate_symbol, :html_entity, :subunit, :subunit_to_unit, :decimal_mark,
:thousands_separator, :symbol_first, :smallest_denomination

#html_entityString (readonly)

Returns The html entity for the currency symbol.

Returns:

  • (String)

    The html entity for the currency symbol


245
246
247
# File 'lib/money/currency.rb', line 245

attr_reader :id, :priority, :iso_code, :iso_numeric, :name, :symbol,
:disambiguate_symbol, :html_entity, :subunit, :subunit_to_unit, :decimal_mark,
:thousands_separator, :symbol_first, :smallest_denomination

#idSymbol (readonly)

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

Returns:

  • (Symbol)

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


245
246
247
# File 'lib/money/currency.rb', line 245

def id
  @id
end

#iso_codeString (readonly)

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

Returns:

  • (String)

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


245
246
247
# File 'lib/money/currency.rb', line 245

attr_reader :id, :priority, :iso_code, :iso_numeric, :name, :symbol,
:disambiguate_symbol, :html_entity, :subunit, :subunit_to_unit, :decimal_mark,
:thousands_separator, :symbol_first, :smallest_denomination

#iso_numericString (readonly)

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

Returns:

  • (String)

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


245
246
247
# File 'lib/money/currency.rb', line 245

attr_reader :id, :priority, :iso_code, :iso_numeric, :name, :symbol,
:disambiguate_symbol, :html_entity, :subunit, :subunit_to_unit, :decimal_mark,
:thousands_separator, :symbol_first, :smallest_denomination

#nameString (readonly)

Returns The currency name.

Returns:

  • (String)

    The currency name.


245
246
247
# File 'lib/money/currency.rb', line 245

attr_reader :id, :priority, :iso_code, :iso_numeric, :name, :symbol,
:disambiguate_symbol, :html_entity, :subunit, :subunit_to_unit, :decimal_mark,
:thousands_separator, :symbol_first, :smallest_denomination

#priorityInteger (readonly)

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

Returns:

  • (Integer)

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


245
246
247
# File 'lib/money/currency.rb', line 245

attr_reader :id, :priority, :iso_code, :iso_numeric, :name, :symbol,
:disambiguate_symbol, :html_entity, :subunit, :subunit_to_unit, :decimal_mark,
:thousands_separator, :symbol_first, :smallest_denomination

#smallest_denominationObject (readonly)

Returns the value of attribute smallest_denomination


245
246
247
# File 'lib/money/currency.rb', line 245

attr_reader :id, :priority, :iso_code, :iso_numeric, :name, :symbol,
:disambiguate_symbol, :html_entity, :subunit, :subunit_to_unit, :decimal_mark,
:thousands_separator, :symbol_first, :smallest_denomination

#subunitString (readonly)

Returns The name of the fractional monetary unit.

Returns:

  • (String)

    The name of the fractional monetary unit.


245
246
247
# File 'lib/money/currency.rb', line 245

attr_reader :id, :priority, :iso_code, :iso_numeric, :name, :symbol,
:disambiguate_symbol, :html_entity, :subunit, :subunit_to_unit, :decimal_mark,
:thousands_separator, :symbol_first, :smallest_denomination

#subunit_to_unitInteger (readonly)

Returns The proportion between the unit and the subunit.

Returns:

  • (Integer)

    The proportion between the unit and the subunit


245
246
247
# File 'lib/money/currency.rb', line 245

attr_reader :id, :priority, :iso_code, :iso_numeric, :name, :symbol,
:disambiguate_symbol, :html_entity, :subunit, :subunit_to_unit, :decimal_mark,
:thousands_separator, :symbol_first, :smallest_denomination

#symbolString (readonly)

Returns The currency symbol (UTF-8 encoded).

Returns:

  • (String)

    The currency symbol (UTF-8 encoded).


245
246
247
# File 'lib/money/currency.rb', line 245

attr_reader :id, :priority, :iso_code, :iso_numeric, :name, :symbol,
:disambiguate_symbol, :html_entity, :subunit, :subunit_to_unit, :decimal_mark,
:thousands_separator, :symbol_first, :smallest_denomination

#symbol_firstBoolean (readonly)

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

Returns:

  • (Boolean)

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


245
246
247
# File 'lib/money/currency.rb', line 245

attr_reader :id, :priority, :iso_code, :iso_numeric, :name, :symbol,
:disambiguate_symbol, :html_entity, :subunit, :subunit_to_unit, :decimal_mark,
:thousands_separator, :symbol_first, :smallest_denomination

#thousands_separatorString (readonly) Also known as: delimiter

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

Returns:

  • (String)

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


245
246
247
# File 'lib/money/currency.rb', line 245

attr_reader :id, :priority, :iso_code, :iso_numeric, :name, :symbol,
:disambiguate_symbol, :html_entity, :subunit, :subunit_to_unit, :decimal_mark,
:thousands_separator, :symbol_first, :smallest_denomination

Class Method Details

._instancesObject


47
48
49
# File 'lib/money/currency.rb', line 47

def _instances
  @@instances
end

.allArray

List the currencies imported and registered

Examples:

Money::Currency.iso_codes()
[#<Currency ..USD>, 'CAD', 'EUR']...

Returns:

  • (Array)

132
133
134
135
136
137
138
139
140
# File 'lib/money/currency.rb', line 132

def all
  table.keys.map do |curr|
    c = Currency.new(curr)
    if c.priority.nil?
      raise MissingAttributeError.new(:all, c.id, :priority)
    end
    c
  end.sort_by(&:priority)
end

.decimal_places_cacheObject

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


406
407
408
# File 'lib/money/currency.rb', line 406

def self.decimal_places_cache
  @decimal_places_cache ||= {1 => 0, 10 => 1, 100 => 2, 1000 => 3}
end

.eachObject


196
197
198
# File 'lib/money/currency.rb', line 196

def each
  all.each { |c| yield(c) }
end

.find(id) ⇒ Money::Currency

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

retrieve the applicable attributes.

Examples:

Money::Currency.find(:eur) #=> #<Money::Currency id: eur ...>
Money::Currency.find(:foo) #=> nil

Parameters:

  • id (String, Symbol, #to_s)

    Used to look into table and

Returns:


62
63
64
65
66
67
# File 'lib/money/currency.rb', line 62

def find(id)
  id = id.to_s.downcase.to_sym
  new(id)
rescue UnknownCurrency
  nil
end

.find_by_iso_numeric(num) ⇒ Money::Currency

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

the right currency id.

Examples:

Money::Currency.find_by_iso_numeric(978) #=> #<Money::Currency id: eur ...>
Money::Currency.find_by_iso_numeric('001') #=> nil

Parameters:

  • num (#to_s)

    used to look into table in iso_numeric and find

Returns:


80
81
82
83
84
85
86
# File 'lib/money/currency.rb', line 80

def find_by_iso_numeric(num)
  num = num.to_s
  id, _ = self.table.find{|key, currency| currency[:iso_numeric] == num}
  new(id)
rescue UnknownCurrency
  nil
end

.new(id) ⇒ Object


38
39
40
41
42
43
44
45
# File 'lib/money/currency.rb', line 38

def new(id)
  id = id.to_s.downcase
  unless stringified_keys.include?(id)
    raise UnknownCurrency, "Unknown currency '#{id}'"
  end

  _instances[id] || @@mutex.synchronize { _instances[id] ||= super }
end

.register(curr) ⇒ Object

Register a new currency

Parameters:

  • curr (Hash)

    information about the currency

  • priority (Hash)

    a customizable set of options

  • iso_code (Hash)

    a customizable set of options

  • iso_numeric (Hash)

    a customizable set of options

  • name (Hash)

    a customizable set of options

  • symbol (Hash)

    a customizable set of options

  • subunit (Hash)

    a customizable set of options

  • subunit_to_unit (Hash)

    a customizable set of options

  • separator (Hash)

    a customizable set of options

  • delimiter (Hash)

    a customizable set of options


169
170
171
172
173
174
# File 'lib/money/currency.rb', line 169

def register(curr)
  key = curr.fetch(:iso_code).downcase.to_sym
  @@mutex.synchronize { _instances.delete(key.to_s) }
  @table[key] = curr
  @stringified_keys = stringify_keys
end

.stringified_keysSet

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

Returns:

  • (Set)

148
149
150
# File 'lib/money/currency.rb', line 148

def stringified_keys
  @stringified_keys ||= stringify_keys
end

.tableObject

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


122
123
124
# File 'lib/money/currency.rb', line 122

def table
  @table ||= load_currencies
end

.unregister(curr) ⇒ Boolean

Unregister a currency.

Parameters:

  • curr (Object)

    A Hash with the key `:iso_code`, or the ISO code as a String or Symbol.

Returns:

  • (Boolean)

    true if the currency previously existed, false if it didn't.


184
185
186
187
188
189
190
191
192
193
# File 'lib/money/currency.rb', line 184

def unregister(curr)
  if curr.is_a?(Hash)
    key = curr.fetch(:iso_code).downcase.to_sym
  else
    key = curr.downcase.to_sym
  end
  existed = @table.delete(key)
  @stringified_keys = stringify_keys if existed
  existed ? true : false
end

.wrap(object) ⇒ Money::Currency

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

object.

Examples:

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

Parameters:

  • object (Object)

    The object to attempt and wrap as a Currency

Returns:


101
102
103
104
105
106
107
108
109
# File 'lib/money/currency.rb', line 101

def wrap(object)
  if object.nil?
    nil
  elsif object.is_a?(Currency)
    object
  else
    Currency.new(object)
  end
end

Instance Method Details

#<=>(other_currency) ⇒ -1, ...

Compares self with other_currency against the value of priority attribute.

Examples:

c1 = Money::Currency.new(:usd)
c2 = Money::Currency.new(:jpy)
c1 <=> c2 #=> 1
c2 <=> c1 #=> -1
c1 <=> c1 #=> 0

Parameters:

Returns:

  • (-1, 0, 1)

    -1 if less than, 0 is equal to, 1 if greater than


280
281
282
283
284
285
286
287
288
289
# File 'lib/money/currency.rb', line 280

def <=>(other_currency)
  # <=> returns nil when one of the values is nil
  comparison = self.priority <=> other_currency.priority || 0

  if comparison == 0
    self.id <=> other_currency.id
  else
    comparison
  end
end

#==(other_currency) ⇒ Boolean

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

Examples:

c1 = Money::Currency.new(:usd)
c2 = Money::Currency.new(:jpy)
c1 == c1 #=> true
c1 == c2 #=> false

Parameters:

Returns:

  • (Boolean)

303
304
305
# File 'lib/money/currency.rb', line 303

def ==(other_currency)
  self.equal?(other_currency) || compare_ids(other_currency)
end

#codeString

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

Returns:


387
388
389
# File 'lib/money/currency.rb', line 387

def code
  symbol || iso_code
end

#decimal_placesInteger

The number of decimal places needed.

Returns:

  • (Integer)

413
414
415
# File 'lib/money/currency.rb', line 413

def decimal_places
  cache[subunit_to_unit] ||= calculate_decimal_places(subunit_to_unit)
end

#eql?Object


251
# File 'lib/money/currency.rb', line 251

alias_method :eql?, :==

#exponentInteger

Returns the relation between subunit and unit as a base 10 exponent.

Note that MGA and MRO are exceptions and are rounded to 1


401
402
403
# File 'lib/money/currency.rb', line 401

def exponent
  Math.log10(@subunit_to_unit).round
end

#hashInteger

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

Examples:

Money::Currency.new(:usd).hash #=> 428936

Returns:

  • (Integer)

324
325
326
# File 'lib/money/currency.rb', line 324

def hash
  id.hash
end

#inspectString

Returns a human readable representation.

Examples:

Money::Currency.new(:usd) #=> #<Currency id: usd ...>

Returns:


334
335
336
# File 'lib/money/currency.rb', line 334

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}, smallest_denomination: #{smallest_denomination}>"
end

#symbol_first?Boolean

Returns:

  • (Boolean)

391
392
393
# File 'lib/money/currency.rb', line 391

def symbol_first?
  !!@symbol_first
end

#to_currencyself

Conversion to self.

Returns:

  • (self)

380
381
382
# File 'lib/money/currency.rb', line 380

def to_currency
  self
end

#to_sString

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.

Examples:

Money::Currency.new(:usd).to_s #=> "USD"
Money::Currency.new(:eur).to_s #=> "EUR"

Returns:


349
350
351
# File 'lib/money/currency.rb', line 349

def to_s
  id.to_s.upcase
end

#to_strString

Returns a string representation corresponding to the upcase id attribute. Useful in cases where only implicit conversions are made.

Examples:

Money::Currency.new(:usd).to_str #=> "USD"
Money::Currency.new(:eur).to_str #=> "EUR"

Returns:


361
362
363
# File 'lib/money/currency.rb', line 361

def to_str
  id.to_s.upcase
end

#to_symSymbol

Returns a symbol representation corresponding to the upcase id attribute.

Examples:

Money::Currency.new(:usd).to_sym #=> :USD
Money::Currency.new(:eur).to_sym #=> :EUR

Returns:

  • (Symbol)

373
374
375
# File 'lib/money/currency.rb', line 373

def to_sym
  id.to_s.upcase.to_sym
end