Class: Money::Currency
- Inherits:
-
Object
- Object
- Money::Currency
- 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
Instance Attribute Summary collapse
-
#decimal_mark ⇒ String
(also: #separator)
readonly
The decimal mark, or character used to separate the whole unit from the subunit.
-
#disambiguate_symbol ⇒ String
readonly
Alternative currency used if symbol is ambiguous.
-
#html_entity ⇒ String
readonly
The html entity for the currency symbol.
-
#id ⇒ Symbol
readonly
The symbol used to identify the currency, usually THE lowercase
iso_code
attribute. -
#iso_code ⇒ String
readonly
The international 3-letter code as defined by the ISO 4217 standard.
-
#iso_numeric ⇒ String
readonly
The international 3-numeric code as defined by the ISO 4217 standard.
-
#name ⇒ String
readonly
The currency name.
-
#priority ⇒ Integer
readonly
A numerical value you can use to sort/group the currency list.
-
#smallest_denomination ⇒ Object
readonly
Returns the value of attribute smallest_denomination.
-
#subunit ⇒ String
readonly
The name of the fractional monetary unit.
-
#subunit_to_unit ⇒ Integer
readonly
The proportion between the unit and the subunit.
-
#symbol ⇒ String
readonly
The currency symbol (UTF-8 encoded).
-
#symbol_first ⇒ Boolean
readonly
Should the currency symbol precede the amount, or should it come after?.
-
#thousands_separator ⇒ String
(also: #delimiter)
readonly
The character used to separate thousands grouping of the whole unit.
Class Method Summary collapse
- ._instances ⇒ Object
-
.all ⇒ Array
List the currencies imported and registered.
-
.decimal_places_cache ⇒ Object
Cache decimal places for subunit_to_unit values.
- .each ⇒ Object
-
.find(id) ⇒ Money::Currency
Lookup a currency with given
id
an returns aCurrency
instance on success,nil
otherwise. -
.find_by_iso_numeric(num) ⇒ Money::Currency
Lookup a currency with given
num
as an ISO 4217 numeric and returns anCurrency
instance on success,nil
otherwise. - .new(id) ⇒ Object
-
.register(curr) ⇒ Object
Register a new currency.
-
.stringified_keys ⇒ Set
We need a string-based validator before creating an unbounded number of symbols.
-
.table ⇒ Object
List of known currencies.
-
.unregister(curr) ⇒ Boolean
Unregister a currency.
-
.wrap(object) ⇒ Money::Currency
Wraps the object in a
Currency
unless it’s already aCurrency
object.
Instance Method Summary collapse
-
#<=>(other_currency) ⇒ -1, ...
Compares
self
withother_currency
against the value ofpriority
attribute. -
#==(other_currency) ⇒ Boolean
Compares
self
withother_currency
and returnstrue
if the are the same or if theirid
attributes match. -
#code ⇒ String
Returns currency symbol or iso code for currencies with no symbol.
-
#decimal_places ⇒ Integer
The number of decimal places needed.
- #eql? ⇒ Object
-
#exponent ⇒ Integer
Returns the relation between subunit and unit as a base 10 exponent.
-
#hash ⇒ Integer
Returns a Integer hash value based on the
id
attribute in order to use functions like & (intersection), group_by, etc. -
#initialize(id) ⇒ Money::Currency
constructor
Create a new
Currency
object. -
#inspect ⇒ String
Returns a human readable representation.
- #symbol_first? ⇒ Boolean
-
#to_currency ⇒ self
Conversion to
self
. -
#to_s ⇒ String
Returns a string representation corresponding to the upcase
id
attribute. -
#to_str ⇒ String
Returns a string representation corresponding to the upcase
id
attribute. -
#to_sym ⇒ Symbol
Returns a symbol representation corresponding to the upcase
id
attribute.
Methods included from Loader
Methods included from Heuristics
Constructor Details
#initialize(id) ⇒ Money::Currency
Create a new Currency
object.
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_mark ⇒ String (readonly) Also known as: separator
Returns 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_symbol ⇒ String (readonly)
Returns 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_entity ⇒ String (readonly)
Returns 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 |
#id ⇒ Symbol (readonly)
Returns 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_code ⇒ String (readonly)
Returns 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_numeric ⇒ String (readonly)
Returns 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 |
#name ⇒ String (readonly)
Returns 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 |
#priority ⇒ Integer (readonly)
Returns 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_denomination ⇒ Object (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 |
#subunit ⇒ String (readonly)
Returns 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_unit ⇒ Integer (readonly)
Returns 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 |
#symbol ⇒ String (readonly)
Returns 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_first ⇒ Boolean (readonly)
Returns 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_separator ⇒ String (readonly) Also known as: delimiter
Returns 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
._instances ⇒ Object
47 48 49 |
# File 'lib/money/currency.rb', line 47 def _instances @@instances end |
.all ⇒ Array
List the currencies imported and registered
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_cache ⇒ Object
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 |
.each ⇒ Object
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.
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.
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
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_keys ⇒ Set
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
148 149 150 |
# File 'lib/money/currency.rb', line 148 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
122 123 124 |
# File 'lib/money/currency.rb', line 122 def table @table ||= load_currencies end |
.unregister(curr) ⇒ Boolean
Unregister a currency.
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.
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.
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.
303 304 305 |
# File 'lib/money/currency.rb', line 303 def ==(other_currency) self.equal?(other_currency) || compare_ids(other_currency) end |
#code ⇒ String
Returns currency symbol or iso code for currencies with no symbol.
387 388 389 |
# File 'lib/money/currency.rb', line 387 def code symbol || iso_code end |
#decimal_places ⇒ Integer
The number of decimal places needed.
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?, :== |
#exponent ⇒ Integer
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 |
#hash ⇒ Integer
Returns a Integer hash value based on the id
attribute in order to use functions like & (intersection), group_by, etc.
324 325 326 |
# File 'lib/money/currency.rb', line 324 def hash id.hash end |
#inspect ⇒ String
Returns a human readable representation.
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
391 392 393 |
# File 'lib/money/currency.rb', line 391 def symbol_first? !!@symbol_first end |
#to_currency ⇒ self
Conversion to self
.
380 381 382 |
# File 'lib/money/currency.rb', line 380 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.
349 350 351 |
# File 'lib/money/currency.rb', line 349 def to_s id.to_s.upcase end |
#to_str ⇒ String
Returns a string representation corresponding to the upcase id
attribute. Useful in cases where only implicit conversions are made.
361 362 363 |
# File 'lib/money/currency.rb', line 361 def to_str id.to_s.upcase end |
#to_sym ⇒ Symbol
Returns a symbol representation corresponding to the upcase id
attribute.
373 374 375 |
# File 'lib/money/currency.rb', line 373 def to_sym id.to_s.upcase.to_sym end |