Class: Money::Currency

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

Overview

Represents a specific currency unit.

Defined Under Namespace

Modules: Heuristics, Loader Classes: UnknownCurrency

Constant Summary

Constants included from Loader

Loader::DATA_PATH

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Loader

load_currencies

Methods included from Heuristics

analyze

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.

Raises:



195
196
197
198
199
200
201
202
203
204
 
# 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

Instance Attribute Details

#decimal_mark ⇒ String (readonly) Also known as: separator

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

Returns:



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

def decimal_mark
  @decimal_mark
end

#html_entity ⇒ String (readonly)

The html entity for the currency symbol

Returns:



157
158
159
 
# File 'lib/money/currency.rb', line 157

def html_entity
  @html_entity
end

#id ⇒ Symbol (readonly)

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

Returns:



127
128
129
 
# File 'lib/money/currency.rb', line 127

def id
  @id
end

#iso_code ⇒ String (readonly)

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

Returns:



137
138
139
 
# File 'lib/money/currency.rb', line 137

def iso_code
  @iso_code
end

#iso_numeric ⇒ String (readonly)

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

Returns:



142
143
144
 
# File 'lib/money/currency.rb', line 142

def iso_numeric
  @iso_numeric
end

#name ⇒ String (readonly)

The currency name.

Returns:



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

def name
  @name
end

#priority ⇒ Integer (readonly)

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

Returns:

  • (Integer) 


132
133
134
 
# File 'lib/money/currency.rb', line 132

def priority
  @priority
end

#subunit ⇒ String (readonly)

The name of the fractional monetary unit.

Returns:



162
163
164
 
# File 'lib/money/currency.rb', line 162

def subunit
  @subunit
end

#subunit_to_unit ⇒ Integer (readonly)

The proportion between the unit and the subunit

Returns:

  • (Integer) 


167
168
169
 
# File 'lib/money/currency.rb', line 167

def subunit_to_unit
  @subunit_to_unit
end

#symbol ⇒ String (readonly)

The currency symbol (UTF-8 encoded).

Returns:



152
153
154
 
# File 'lib/money/currency.rb', line 152

def symbol
  @symbol
end

#symbol_first ⇒ Boolean (readonly)

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

Returns:

  • (Boolean) 


184
185
186
 
# File 'lib/money/currency.rb', line 184

def symbol_first
  @symbol_first
end

#thousands_separator ⇒ String (readonly) Also known as: delimiter

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

Returns:



178
179
180
 
# File 'lib/money/currency.rb', line 178

def thousands_separator
  @thousands_separator
end

Class Method Details

.all ⇒ Array

List the currencies imported and registered

Examples:

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

Returns:

  • (Array) 


99
100
101
 
# File 'lib/money/currency.rb', line 99

def all
  table.keys.map {|curr| Currency.new(curr)}.sort_by(&:priority)
end

.decimal_places_cache ⇒ Object

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



319
320
321
322
323
324
325
326
 
# 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) ⇒ 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:

Returns:



33
34
35
36
 
# 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) ⇒ 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:



49
50
51
52
53
 
# 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

.register(curr) ⇒ Object 



110
111
112
113
114
 
# 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 ⇒ Object

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



106
107
108
 
# File 'lib/money/currency.rb', line 106

def stringified_keys
  @stringified_keys ||= stringify_keys
end

.table ⇒ Object

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



89
90
91
 
# File 'lib/money/currency.rb', line 89

def table
  @table ||= load_currencies
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:



68
69
70
71
72
73
74
75
76
 
# 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

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



219
220
221
 
# File 'lib/money/currency.rb', line 219

def <=>(other_currency)
  self.priority <=> other_currency.priority
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) 


235
236
237
238
 
# 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 ⇒ String

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

Returns:



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

def code
  symbol || iso_code
end

#decimal_places ⇒ Integer

The number of decimal places needed.

Returns:

  • (Integer) 


331
332
333
334
335
336
337
338
339
 
# 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) ⇒ 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.eql? c1 #=> true
c1.eql? c2 #=> false

Parameters:

Returns:

  • (Boolean) 


252
253
254
 
# File 'lib/money/currency.rb', line 252

def eql?(other_currency)
  self == other_currency
end

#exponent ⇒ Float

Returns the number of digits after the decimal separator.

Returns:

  • (Float) 


314
315
316
 
# File 'lib/money/currency.rb', line 314

def exponent
  Math.log10(@subunit_to_unit)
end

#hash ⇒ Fixnum

Returns a Fixnum 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:

  • (Fixnum) 


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

def hash
  id.hash
end

#inspect ⇒ String

Returns a human readable representation.

Examples:

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

Returns:



273
274
275
 
# 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? ⇒ Boolean

Returns:

  • (Boolean) 


307
308
309
 
# File 'lib/money/currency.rb', line 307

def symbol_first?
  !!@symbol_first
end

#to_currency ⇒ self

Conversation to self.

Returns:

  • (self) 


295
296
297
 
# File 'lib/money/currency.rb', line 295

def to_currency
  self
end

#to_s ⇒ String

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:



288
289
290
 
# File 'lib/money/currency.rb', line 288

def to_s
  id.to_s.upcase
end