Class: Money::Currency

Inherits:
Object
  • Object
show all
Extended by:
Enumerable, Enumerable[Money::Currency], Heuristics
Includes:
Comparable
Defined in:
lib/money/currency.rb,
lib/money/currency/loader.rb,
lib/money/currency/heuristics.rb,
sig/lib/money/currency.rbs,
sig/lib/money/currency/heuristics.rbs

Overview

Represents a specific currency unit.

See Also:

Defined Under Namespace

Modules: Heuristics, Loader Classes: MissingAttributeError, NoCurrency, UnknownCurrency

Constant Summary collapse

@@mutex =

Keeping cached instances in sync between threads

Mutex.new
@@instances = 
{}

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

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.



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

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.

Returns:

  • (String) —

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



277
278
279
 
# File 'lib/money/currency.rb', line 277

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, :format

#disambiguate_symbol ⇒ String (readonly)

Returns Alternative currency used if symbol is ambiguous.

Returns:

  • (String) —

    Alternative currency used if symbol is ambiguous



277
278
279
 
# File 'lib/money/currency.rb', line 277

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, :format

#format ⇒ Object (readonly)

Returns the value of attribute format.

Returns:

  • (Object) 


277
278
279
 
# File 'lib/money/currency.rb', line 277

def format
  @format
end

#html_entity ⇒ String (readonly)

Returns The html entity for the currency symbol.

Returns:

  • (String) —

    The html entity for the currency symbol



277
278
279
 
# File 'lib/money/currency.rb', line 277

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, :format

#id ⇒ Symbol (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.



277
278
279
 
# File 'lib/money/currency.rb', line 277

def id
  @id
end

#iso_code ⇒ String (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.



277
278
279
 
# File 'lib/money/currency.rb', line 277

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, :format

#iso_numeric ⇒ String (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.



277
278
279
 
# File 'lib/money/currency.rb', line 277

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, :format

#name ⇒ String (readonly)

Returns The currency name.

Returns:

  • (String) —

    The currency name.



277
278
279
 
# File 'lib/money/currency.rb', line 277

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, :format

#priority ⇒ Integer (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.



277
278
279
 
# File 'lib/money/currency.rb', line 277

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, :format

#smallest_denomination ⇒ Integer (readonly)

Returns Smallest amount of cash possible (in the subunit of this currency).

Returns:

  • (Integer) —

    Smallest amount of cash possible (in the subunit of this currency)



277
278
279
 
# File 'lib/money/currency.rb', line 277

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, :format

#subunit ⇒ String (readonly)

Returns The name of the fractional monetary unit.

Returns:

  • (String) —

    The name of the fractional monetary unit.



277
278
279
 
# File 'lib/money/currency.rb', line 277

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, :format

#subunit_to_unit ⇒ Integer (readonly)

Returns The proportion between the unit and the subunit.

Returns:

  • (Integer) —

    The proportion between the unit and the subunit



277
278
279
 
# File 'lib/money/currency.rb', line 277

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, :format

#symbol ⇒ String (readonly)

Returns The currency symbol (UTF-8 encoded).

Returns:

  • (String) —

    The currency symbol (UTF-8 encoded).



277
278
279
 
# File 'lib/money/currency.rb', line 277

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, :format

#symbol_first ⇒ Boolean (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?



277
278
279
 
# File 'lib/money/currency.rb', line 277

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, :format

#thousands_separator ⇒ String (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.



277
278
279
 
# File 'lib/money/currency.rb', line 277

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, :format

Class Method Details

._instances ⇒ Object

Returns:

  • (Object) 


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

def _instances
  @@instances
end

.all ⇒ Array

List the currencies imported and registered

Examples:

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

Returns:

  • (Array) 


136
137
138
139
140
141
142
143
144
145
 
# File 'lib/money/currency.rb', line 136

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

.each {|arg0| ... } ⇒ Object

rubocop:enable Naming/PredicateMethod

Yields:

Yield Parameters:

  • arg0 (Object)

Yield Returns:

  • (Object)

Returns:

  • (Object) 


213
214
215
 
# File 'lib/money/currency.rb', line 213

def each(&)
  all.each(&)
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:



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

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(51) #=> #<Money::Currency id: amd ...>
Money::Currency.find_by_iso_numeric('001') #=> nil

Parameters:

  • num (#to_s) —

    used to look into +table+ in +iso_numeric+ and find

Returns:



82
83
84
85
86
87
88
89
90
 
# File 'lib/money/currency.rb', line 82

def find_by_iso_numeric(num)
  num = num.to_s.rjust(3, "0")
  return if num.empty?

  id = iso_numeric_index[num]
  new(id) if id
rescue UnknownCurrency
  nil
end

.inherit(parent_iso_code, curr) ⇒ Object

Inherit a new currency from existing one

Parameters:

  • parent_iso_code (String) —

    the international 3-letter code as defined

  • curr (Hash) —

    See register method for hash structure

Returns:

  • (Object) 


186
187
188
189
190
 
# File 'lib/money/currency.rb', line 186

def inherit(parent_iso_code, curr)
  parent_iso_code = parent_iso_code.downcase.to_sym
  curr = table.fetch(parent_iso_code, {}).merge(curr)
  register(curr)
end

.new(id) ⇒ Object

Parameters:

  • id (Object)

Returns:

  • (Object) 


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

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) ⇒ Money::Currency

Register a new currency

Parameters:

  • curr (Hash) —

    information about the currency

Returns:



174
175
176
177
178
179
180
 
# File 'lib/money/currency.rb', line 174

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

.reset! ⇒ Object

Returns:

  • (Object) 


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

def reset!
  @@instances = {}
  @table = Loader.load_currencies
  clear_iso_numeric_cache
end

.stringified_keys ⇒ Set

We need a string-based validator before creating an unbounded number of symbols. http://www.randomhacks.net.s3-website-us-east-1.amazonaws.com/2007/01/20/13-ways-of-looking-at-a-ruby-symbol/#11 https://github.com/RubyMoney/money/issues/132

Returns:

  • (Set) 


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

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. https://www.answers.com/redirectSearch?query=monetary-unit == fractional monetary unit, subunit A monetary unit that is valued at a fraction (usually one hundredth) of the basic monetary unit https://www.answers.com/redirectSearch?query=fractional-monetary-unit-subunit

See https://en.wikipedia.org/wiki/List_of_circulating_currencies and https://metacpan.org/release/TNGUYEN/Locale-Currency-Format-1.28/view/Format.pm

Returns:

  • (Object) 


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

def table
  @table ||= Loader.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.



200
201
202
203
204
205
206
207
208
209
210
 
# File 'lib/money/currency.rb', line 200

def unregister(curr)
  key =
    if curr.is_a?(Hash)
      curr.fetch(:iso_code).downcase.to_sym
    else
      curr.downcase.to_sym
    end
  existed = @table.delete(key)
  @stringified_keys = nil 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:



105
106
107
108
109
110
111
112
113
 
# File 'lib/money/currency.rb', line 105

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

Instance Method Details

#<=>(other) ⇒ -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



312
313
314
315
316
317
318
319
320
321
 
# File 'lib/money/currency.rb', line 312

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

  if comparison == 0
    id <=> other.id
  else
    comparison
  end
end

#==(other) ⇒ 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) 


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

def ==(other)
  equal?(other) || compare_ids(other)
end

#cents_based? ⇒ Boolean

Returns true if a subunit is cents-based.

Examples:

Money::Currency.new(:usd).cents_based?

Returns:

  • (Boolean) 


450
451
452
 
# File 'lib/money/currency.rb', line 450

def cents_based?
  subunit_to_unit == 100
end

#code ⇒ String

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

Returns:

  • (String) 


424
425
426
 
# File 'lib/money/currency.rb', line 424

def code
  symbol || iso_code
end

#compare_ids(other_currency) ⇒ Object

rubocop:disable Naming/PredicateMethod

Parameters:

  • other_currency (Object)

Returns:

  • (Object) 


468
469
470
471
472
473
474
475
476
 
# File 'lib/money/currency.rb', line 468

def compare_ids(other_currency)
  other_currency_id =
    if other_currency.is_a?(Currency)
      other_currency.id.to_s.downcase
    else
      other_currency.to_s.downcase
    end
  id.to_s.downcase == other_currency_id
end

#eql? ⇒ Object 



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

alias eql? ==

#exponent ⇒ Integer Also known as: decimal_places

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

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

Returns:

  • (Integer)

See Also:



460
461
462
 
# File 'lib/money/currency.rb', line 460

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.

Examples:

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

Returns:

  • (Integer) 


346
347
348
 
# File 'lib/money/currency.rb', line 346

def hash
  id.hash
end

#initialize_data! ⇒ Object

rubocop:enable Naming/PredicateMethod

Returns:

  • (Object) 


479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
 
# File 'lib/money/currency.rb', line 479

def initialize_data!
  data = self.class.table[@id]
  @alternate_symbols     = data[:alternate_symbols]
  @decimal_mark          = data[:decimal_mark]
  @disambiguate_symbol   = data[:disambiguate_symbol]
  @html_entity           = data[:html_entity]
  @iso_code              = data[:iso_code]
  @iso_numeric           = data[:iso_numeric]
  @name                  = data[:name]
  @priority              = data[:priority]
  @smallest_denomination = data[:smallest_denomination]
  @subunit               = data[:subunit]
  @subunit_to_unit       = data[:subunit_to_unit]
  @symbol                = data[:symbol]
  @symbol_first          = data[:symbol_first]
  @thousands_separator   = data[:thousands_separator]
  @format                = data[:format]
end

#inspect ⇒ String

Returns a human readable representation.

Examples:

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

Returns:

  • (String) 


356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
 
# File 'lib/money/currency.rb', line 356

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

#iso? ⇒ Boolean

Returns if a code currency is ISO.

Examples:

Money::Currency.new(:usd).iso?

Returns:

  • (Boolean) 


439
440
441
 
# File 'lib/money/currency.rb', line 439

def iso?
  iso_numeric && iso_numeric != ""
end

#symbol_first? ⇒ Boolean

Returns:

  • (Boolean) 


428
429
430
 
# File 'lib/money/currency.rb', line 428

def symbol_first?
  !!@symbol_first
end

#to_currency ⇒ self

Conversion to +self+.

Returns:

  • (self) 


417
418
419
 
# File 'lib/money/currency.rb', line 417

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:

  • (String) 


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

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.

Examples:

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

Returns:

  • (String) 


398
399
400
 
# File 'lib/money/currency.rb', line 398

def to_str
  id.to_s.upcase
end

#to_sym ⇒ Symbol

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) 


410
411
412
 
# File 'lib/money/currency.rb', line 410

def to_sym
  id.to_s.upcase.to_sym
end