class Money::Currency
Represents a specific currency unit.
Attributes
The decimal mark, or character used to separate the whole unit from the subunit.
@return [String]
The character used to separate thousands grouping of the whole unit.
@return [String]
The html entity for the currency symbol
@return [String]
The symbol used to identify the currency, usually the lowercase iso_code
attribute.
@return [Symbol]
The international 3-letter code as defined by the ISO 4217 standard.
@return [String]
The international 3-numeric code as defined by the ISO 4217 standard.
@return [String]
The currency name.
@return [String]
A numerical value you can use to sort/group the currency list.
@return [Integer]
The decimal mark, or character used to separate the whole unit from the subunit.
@return [String]
The name of the fractional monetary unit.
@return [String]
The proportion between the unit and the subunit
@return [Integer]
The currency symbol (UTF-8 encoded).
@return [String]
Should the currency symbol precede the amount, or should it come after?
@return [Boolean]
The character used to separate thousands grouping of the whole unit.
@return [String]
Public Class Methods
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
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
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
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
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
# 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
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
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
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
# File lib/money/currency.rb, line 118 def stringify_keys table.keys.map{|k| k.to_s.downcase} end
Public Instance Methods
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
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
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
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
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
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
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
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
# File lib/money/currency.rb, line 307 def symbol_first? !!@symbol_first end
Conversation to self
.
@return [self]
# File lib/money/currency.rb, line 295 def to_currency self end
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
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