Class: Money

Inherits:
Object
  • Object
show all
Extended by:
Constructors
Includes:
Comparable, Arithmetic
Defined in:
lib/money/money.rb,
lib/money/version.rb,
lib/money/currency.rb,
lib/money/bank/base.rb,
lib/money/currency/loader.rb,
lib/money/money/formatter.rb,
lib/money/money/allocation.rb,
lib/money/money/arithmetic.rb,
lib/money/money/constructors.rb,
lib/money/rates_store/memory.rb,
lib/money/currency/heuristics.rb,
lib/money/locale_backend/base.rb,
lib/money/locale_backend/i18n.rb,
lib/money/bank/single_currency.rb,
lib/money/money/locale_backend.rb,
lib/money/locale_backend/errors.rb,
lib/money/locale_backend/legacy.rb,
lib/money/bank/variable_exchange.rb,
lib/money/money/formatting_rules.rb,
lib/money/locale_backend/currency.rb

Overview

“Money is any object or record that is generally accepted as payment for goods and services and repayment of debts in a given socio-economic context or country.” -Wikipedia

An instance of Money represents an amount of a specific currency.

Money is a value object and should be treated as immutable.

Defined Under Namespace

Modules: Arithmetic, Bank, Constructors, LocaleBackend, RatesStore Classes: Allocation, Currency, Formatter, FormattingRules, UndefinedSmallestDenomination

Constant Summary collapse

VERSION =
'6.13.3'

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Constructors

ca_dollar, empty, euro, pound_sterling, us_dollar

Methods included from Arithmetic

#%, #*, #+, #-, #[email protected], #/, #<=>, #==, #abs, #coerce, #div, #divmod, #eql?, #modulo, #negative?, #nonzero?, #positive?, #remainder, #zero?

Constructor Details

#initialize(obj, currency = Money.default_currency, bank = Money.default_bank) ⇒ Money

Creates a new Money object of value given in the fractional unit of the given currency.

Alternatively you can use the convenience methods like Money::Constructors#ca_dollar and Money::Constructors#us_dollar.

Examples:

Money.new(100)        #=> #<Money @fractional=100 @currency="USD">
Money.new(100, "USD") #=> #<Money @fractional=100 @currency="USD">
Money.new(100, "EUR") #=> #<Money @fractional=100 @currency="EUR">

Parameters:

  • obj (Object)

    Either the fractional value of the money, a Money object, or a currency. (If passed a currency as the first argument, a Money will be created in that currency with fractional value

    0.

  • currency (Currency, String, Symbol) (defaults to: Money.default_currency)

    The currency format.

  • bank (Money::Bank::*) (defaults to: Money.default_bank)

    The exchange bank to use.

Raises:

  • (ArgumentError)

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

def initialize(obj, currency = Money.default_currency, bank = Money.default_bank)
  @fractional = as_d(obj.respond_to?(:fractional) ? obj.fractional : obj)
  @currency   = obj.respond_to?(:currency) ? obj.currency : Currency.wrap(currency)
  @currency ||= Money.default_currency
  @bank       = obj.respond_to?(:bank) ? obj.bank : bank

  # BigDecimal can be Infinity and NaN, money of that amount does not make sense
  raise ArgumentError, 'must be initialized with a finite value' unless @fractional.finite?
end

Class Attribute Details

.conversion_precisionInteger

Returns Use this to specify precision for converting Rational to BigDecimal.

Returns:

  • (Integer)

    Use this to specify precision for converting Rational to BigDecimal


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

attr_accessor :default_bank, :default_formatting_rules,
:use_i18n, :infinite_precision, :conversion_precision,
:locale_backend

.default_bankMoney::Bank::Base

Returns Each Money object is associated to a bank object, which is responsible for currency exchange. This property allows you to specify the default bank object. The default value for this property is an instance of Bank::VariableExchange. It allows one to specify custom exchange rates.

Returns:

  • (Money::Bank::Base)

    Each Money object is associated to a bank object, which is responsible for currency exchange. This property allows you to specify the default bank object. The default value for this property is an instance of Bank::VariableExchange. It allows one to specify custom exchange rates.


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

def default_bank
  @default_bank
end

.default_currencyMoney::Currency

Returns The default currency, which is used when Money.new is called without an explicit currency argument. The default value is Currency.new(“USD”). The value must be a valid Money::Currency instance.

Returns:

  • (Money::Currency)

    The default currency, which is used when Money.new is called without an explicit currency argument. The default value is Currency.new(“USD”). The value must be a valid Money::Currency instance.


134
# File 'lib/money/money.rb', line 134

attr_writer :rounding_mode, :default_currency

.default_formatting_rulesHash

Returns Use this to define a default hash of rules for every time Money#format is called. Rules provided on method call will be merged with the default ones. To overwrite a rule, just provide the intended value while calling format.

Examples:

Money.default_formatting_rules = { display_free: true }
Money.new(0, "USD").format                          # => "free"
Money.new(0, "USD").format(display_free: false)  # => "$0.00"

Returns:

  • (Hash)

    Use this to define a default hash of rules for every time Money#format is called. Rules provided on method call will be merged with the default ones. To overwrite a rule, just provide the intended value while calling format.

See Also:

  • for more details.

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

attr_accessor :default_bank, :default_formatting_rules,
:use_i18n, :infinite_precision, :conversion_precision,
:locale_backend

.infinite_precisionBoolean

Returns Use this to enable infinite precision cents.

Returns:

  • (Boolean)

    Use this to enable infinite precision cents


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

attr_accessor :default_bank, :default_formatting_rules,
:use_i18n, :infinite_precision, :conversion_precision,
:locale_backend

.locale_backendObject

Returns the value of attribute locale_backend


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

def locale_backend
  @locale_backend
end

.rounding_mode(mode = nil) ⇒ BigDecimal::ROUND_MODE

Use this to return the rounding mode.

Parameters:

  • mode (BigDecimal::ROUND_MODE) (defaults to: nil)

Returns:

  • (BigDecimal::ROUND_MODE)

    rounding mode


194
195
196
197
198
199
# File 'lib/money/money.rb', line 194

def self.rounding_mode(mode = nil)
  return Thread.current[:money_rounding_mode] || @rounding_mode unless mode

  warn "[DEPRECATION] calling `rounding_mode` with a block is deprecated. Please use `.with_rounding_mode` instead."
  with_rounding_mode(mode) { yield }
end

.use_i18nBoolean

Returns Use this to disable i18n even if it's used by other objects in your app.

Returns:

  • (Boolean)

    Use this to disable i18n even if it's used by other objects in your app.


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

attr_accessor :default_bank, :default_formatting_rules,
:use_i18n, :infinite_precision, :conversion_precision,
:locale_backend

Instance Attribute Details

#bankObject (readonly)

Returns the value of attribute bank


88
# File 'lib/money/money.rb', line 88

attr_reader :currency, :bank

#currencyCurrency (readonly)

Returns The money's currency.

Returns:


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

def currency
  @currency
end

Class Method Details

.add_rate(from_currency, to_currency, rate) ⇒ Numeric

Adds a new exchange rate to the default bank and return the rate.

Examples:

Money.add_rate("USD", "CAD", 1.25) #=> 1.25

Parameters:

  • from_currency (Currency, String, Symbol)

    Currency to exchange from.

  • to_currency (Currency, String, Symbol)

    Currency to exchange to.

  • rate (Numeric)

    Rate to exchange with.

Returns:

  • (Numeric)

229
230
231
# File 'lib/money/money.rb', line 229

def self.add_rate(from_currency, to_currency, rate)
  Money.default_bank.add_rate(from_currency, to_currency, rate)
end

.disallow_currency_conversion!Object

Sets the default bank to be a SingleCurrency bank that raises on currency exchange. Useful when apps operate in a single currency at a time.


235
236
237
# File 'lib/money/money.rb', line 235

def self.disallow_currency_conversion!
  self.default_bank = Bank::SingleCurrency.instance
end

.from_amount(amount, currency = default_currency, bank = default_bank) ⇒ Money

Creates a new Money object of value given in the unit of the given currency.

Examples:

Money.from_amount(23.45, "USD") # => #<Money fractional:2345 currency:USD>
Money.from_amount(23.45, "JPY") # => #<Money fractional:23 currency:JPY>

Parameters:

  • amount (Numeric)

    The numerical value of the money.

  • currency (Currency, String, Symbol) (defaults to: default_currency)

    The currency format.

  • bank (Money::Bank::*) (defaults to: default_bank)

    The exchange bank to use.

Returns:

Raises:

  • (ArgumentError)

See Also:


253
254
255
256
257
258
259
260
# File 'lib/money/money.rb', line 253

def self.from_amount(amount, currency = default_currency, bank = default_bank)
  raise ArgumentError, "'amount' must be numeric" unless Numeric === amount

  currency = Currency.wrap(currency) || Money.default_currency
  value = amount.to_d * currency.subunit_to_unit
  value = value.round(0, rounding_mode) unless infinite_precision
  new(value, currency, bank)
end

.inherited(base) ⇒ Object


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

def self.inherited(base)
  base.setup_defaults
end

.setup_defaultsObject


160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
# File 'lib/money/money.rb', line 160

def self.setup_defaults
  # Set the default bank for creating new +Money+ objects.
  self.default_bank = Bank::VariableExchange.instance

  # Set the default currency for creating new +Money+ object.
  self.default_currency = Currency.new("USD")

  # Default to using i18n
  @use_i18n = true

  # Default to using legacy locale backend
  self.locale_backend = :legacy

  # Default to not using infinite precision cents
  self.infinite_precision = false

  # Default to bankers rounding
  self.rounding_mode = BigDecimal::ROUND_HALF_EVEN

  # Default the conversion of Rationals precision to 16
  self.conversion_precision = 16
end

.with_rounding_mode(mode) ⇒ BigDecimal::ROUND_MODE, Yield

This method temporarily changes the rounding mode. It will then return the results of the block instead.

Examples:

fee = Money.with_rounding_mode(BigDecimal::ROUND_HALF_UP) do
  Money.new(1200) * BigDecimal('0.029')
end

Parameters:

  • mode (BigDecimal::ROUND_MODE)

Returns:

  • (BigDecimal::ROUND_MODE, Yield)

    block results


212
213
214
215
216
217
# File 'lib/money/money.rb', line 212

def self.with_rounding_mode(mode)
  Thread.current[:money_rounding_mode] = mode
  yield
ensure
  Thread.current[:money_rounding_mode] = nil
end

Instance Method Details

#allocate(parts) ⇒ Array<Money> Also known as: split

Splits a given amount in parts without loosing pennies. The left-over pennies will be distributed round-robin amongst the parties. This means that parties listed first will likely receive more pennies than ones that are listed later.

party3 which results in 50% of the cash to party1, 25% to party2, and 25% to party3. Passing a number instead of an array will split the amount evenly (without loosing pennies when rounding).

Examples:

Money.new(5,   "USD").allocate([3, 7]) #=> [Money.new(2), Money.new(3)]
Money.new(100, "USD").allocate([1, 1, 1]) #=> [Money.new(34), Money.new(33), Money.new(33)]
Money.new(100, "USD").allocate(2) #=> [Money.new(50), Money.new(50)]
Money.new(100, "USD").allocate(3) #=> [Money.new(34), Money.new(33), Money.new(33)]

Parameters:

  • pass (Array<Numeric>, Numeric)
    2, 1, 1

    to give twice as much to party1 as party2 or

Returns:


528
529
530
531
# File 'lib/money/money.rb', line 528

def allocate(parts)
  amounts = Money::Allocation.generate(fractional, parts, !Money.infinite_precision)
  amounts.map { |amount| self.class.new(amount, currency) }
end

#amountBigDecimal

Returns the numerical value of the money

Examples:

Money.new(1_00, "USD").amount    # => BigDecimal("1.00")

Returns:

  • (BigDecimal)

See Also:


321
322
323
# File 'lib/money/money.rb', line 321

def amount
  to_d
end

#as_ca_dollarMoney

Receive a money object with the same amount as the current Money object in Canadian dollar.

Examples:

n = Money.new(100, "USD").as_ca_dollar
n.currency #=> #<Money::Currency id: cad>

Returns:


496
497
498
# File 'lib/money/money.rb', line 496

def as_ca_dollar
  exchange_to("CAD")
end

#as_euroMoney

Receive a money object with the same amount as the current Money object in euro.

Examples:

n = Money.new(100, "USD").as_euro
n.currency #=> #<Money::Currency id: eur>

Returns:


508
509
510
# File 'lib/money/money.rb', line 508

def as_euro
  exchange_to("EUR")
end

#as_us_dollarMoney

Receive a money object with the same amount as the current Money object in United States dollar.

Examples:

n = Money.new(100, "CAD").as_us_dollar
n.currency #=> #<Money::Currency id: usd>

Returns:


484
485
486
# File 'lib/money/money.rb', line 484

def as_us_dollar
  exchange_to("USD")
end

#centsInteger, BigDecimal

Convenience method for fractional part of the amount. Synonym of #fractional

Returns:

  • (Integer)

    when infinite_precision is false

  • (BigDecimal)

    when infinite_precision is true

See Also:


33
34
35
# File 'lib/money/money.rb', line 33

def cents
  fractional
end

#currency_as_stringString

Return string representation of currency object

Examples:

Money.new(100, :USD).currency_as_string #=> "USD"

Returns:

  • (String)

331
332
333
334
# File 'lib/money/money.rb', line 331

def currency_as_string
  warn "[DEPRECATION] `currency_as_string` is deprecated. Please use `.currency.to_s` instead."
  currency.to_s
end

#currency_as_string=(val) ⇒ Money::Currency

Set currency object using a string

Examples:

Money.new(100).currency_as_string("CAD") #=> #<Money::Currency id: cad>

Parameters:

  • val (String)

    The currency string.

Returns:


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

def currency_as_string=(val)
  warn "[DEPRECATION] `currency_as_string=` is deprecated - Money instances are immutable." \
    " Please use `with_currency` instead."
  @currency = Currency.wrap(val)
end

#decimal_markString

Returns a decimal mark according to the locale

Returns:

  • (String)

577
578
579
580
# File 'lib/money/money.rb', line 577

def decimal_mark
  (locale_backend && locale_backend.lookup(:decimal_mark, currency)) ||
    Money::Formatter::DEFAULTS[:decimal_mark]
end

#dollarsBigDecimal

Assuming using a currency using dollars: Returns the value of the money in dollars, instead of in the fractional unit cents.

Synonym of #amount

Examples:

Money.new(1_00, "USD").dollars   # => BigDecimal("1.00")

Returns:

  • (BigDecimal)

See Also:


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

def dollars
  amount
end

#exchange_to(other_currency) {|n| ... } ⇒ Money

Receive the amount of this money object in another Currency.

Examples:

Money.new(2000, "USD").exchange_to("EUR")
Money.new(2000, "USD").exchange_to("EUR") {|x| x.round}
Money.new(2000, "USD").exchange_to(Currency.new("EUR"))

Parameters:

  • other_currency (Currency, String, Symbol)

    Currency to exchange to.

Yields:

  • (n)

    Optional block to use when rounding after exchanging one currency for another.

Yield Parameters:

  • n (Float)

    The resulting float after exchanging one currency for another.

Yield Returns:

  • (Integer)

Returns:


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

def exchange_to(other_currency, &rounding_method)
  other_currency = Currency.wrap(other_currency)
  if self.currency == other_currency
    self
  else
    @bank.exchange_with(self, other_currency, &rounding_method)
  end
end

#format(*rules) ⇒ String

Creates a formatted price string according to several rules.

Parameters:

  • See (Hash)

    Money::Formatter for the list of formatting options

Returns:

  • (String)

560
561
562
# File 'lib/money/money.rb', line 560

def format(*rules)
  Money::Formatter.new(self, *rules).to_s
end

#fractionalInteger, BigDecimal

The value of the monetary amount represented in the fractional or subunit of the currency.

For example, in the US dollar currency the fractional unit is cents, and there are 100 cents in one US dollar. So given the Money representation of one US dollar, the fractional interpretation is 100.

Another example is that of the Kuwaiti dinar. In this case the fractional unit is the fils and there 1000 fils to one Kuwaiti dinar. So given the Money representation of one Kuwaiti dinar, the fractional interpretation is 1000.

Returns:

  • (Integer)

    when infinite_precision is false

  • (BigDecimal)

    when infinite_precision is true

See Also:


53
54
55
56
57
58
59
# File 'lib/money/money.rb', line 53

def fractional
  # Ensure we have a BigDecimal. If the Money object is created
  # from YAML, @fractional can end up being set to a Float.
  fractional = as_d(@fractional)

  return_value(fractional)
end

#hashInteger

Returns a Integer hash value based on the fractional and currency attributes in order to use functions like & (intersection), group_by, etc.

Examples:

Money.new(100).hash #=> 908351

Returns:

  • (Integer)

357
358
359
# File 'lib/money/money.rb', line 357

def hash
  [fractional.hash, currency.hash].hash
end

#inspectString

Common inspect function

Returns:

  • (String)

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

def inspect
  "#<#{self.class.name} fractional:#{fractional} currency:#{currency}>"
end

#round(rounding_mode = self.class.rounding_mode, rounding_precision = 0) ⇒ Money

Note:

This method is only useful when operating with infinite_precision turned on. Without infinite_precision values are rounded to the smallest unit of coinage automatically.

Round the monetary amount to smallest unit of coinage.

Examples:

Money.new(10.1, 'USD').round #=> Money.new(10, 'USD')

Returns:

See Also:


549
550
551
552
# File 'lib/money/money.rb', line 549

def round(rounding_mode = self.class.rounding_mode, rounding_precision = 0)
  rounded_amount = as_d(@fractional).round(rounding_precision, rounding_mode)
  self.class.new(rounded_amount, currency, bank)
end

#round_to_nearest_cash_valueInteger, BigDecimal

Round a given amount of money to the nearest possible amount in cash value. For example, in Swiss franc (CHF), the smallest possible amount of cash value is CHF 0.05. Therefore, this method rounds CHF 0.07 to CHF 0.05, and CHF 0.08 to CHF 0.10.

Returns:

  • (Integer)

    when infinite_precision is false

  • (BigDecimal)

    when infinite_precision is true

See Also:


70
71
72
73
74
75
76
77
78
79
80
# File 'lib/money/money.rb', line 70

def round_to_nearest_cash_value
  unless self.currency.smallest_denomination
    raise UndefinedSmallestDenomination, 'Smallest denomination of this currency is not defined'
  end

  fractional = as_d(@fractional)
  smallest_denomination = as_d(self.currency.smallest_denomination)
  rounded_value = (fractional / smallest_denomination).round(0, self.class.rounding_mode) * smallest_denomination

  return_value(rounded_value)
end

#symbolString

Uses Currency#symbol. If nil is returned, defaults to “¤”.

Examples:

Money.new(100, "USD").symbol #=> "$"

Returns:

  • (String)

367
368
369
# File 'lib/money/money.rb', line 367

def symbol
  currency.symbol || "¤"
end

#thousands_separatorString

Returns a thousands separator according to the locale

Returns:

  • (String)

568
569
570
571
# File 'lib/money/money.rb', line 568

def thousands_separator
  (locale_backend && locale_backend.lookup(:thousands_separator, currency)) ||
    Money::Formatter::DEFAULTS[:thousands_separator]
end

#to_dBigDecimal

Return the amount of money as a BigDecimal.

Examples:

Money.us_dollar(1_00).to_d #=> BigDecimal("1.00")

Returns:

  • (BigDecimal)

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

def to_d
  as_d(fractional) / as_d(currency.subunit_to_unit)
end

#to_fFloat

Return the amount of money as a float. Floating points cannot guarantee precision. Therefore, this function should only be used when you no longer need to represent currency or working with another system that requires floats.

Examples:

Money.us_dollar(100).to_f #=> 1.0

Returns:

  • (Float)

420
421
422
# File 'lib/money/money.rb', line 420

def to_f
  to_d.to_f
end

#to_iInteger

Return the amount of money as a Integer.

Examples:

Money.us_dollar(1_00).to_i #=> 1

Returns:

  • (Integer)

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

def to_i
  to_d.to_i
end

#to_money(given_currency = nil) ⇒ self

Conversion to self.

Returns:

  • (self)

442
443
444
445
446
447
448
449
# File 'lib/money/money.rb', line 442

def to_money(given_currency = nil)
  given_currency = Currency.wrap(given_currency)
  if given_currency.nil? || self.currency == given_currency
    self
  else
    exchange_to(given_currency)
  end
end

#to_sString

Returns the amount of money as a string.

Examples:

Money.ca_dollar(100).to_s #=> "1.00"

Returns:

  • (String)

384
385
386
387
388
389
# File 'lib/money/money.rb', line 384

def to_s
  format thousands_separator: '',
         no_cents_if_whole: currency.decimal_places == 0,
         symbol: false,
         ignore_defaults: true
end

#with_currency(new_currency) ⇒ self

Returns a new Money instance in a given currency leaving the amount intact and not performing currency conversion.

Parameters:

  • new_currency (Currency, String, Symbol)

    Currency of the new object.

Returns:

  • (self)

430
431
432
433
434
435
436
437
# File 'lib/money/money.rb', line 430

def with_currency(new_currency)
  new_currency = Currency.wrap(new_currency)
  if !new_currency || currency == new_currency
    self
  else
    self.class.new(fractional, new_currency, bank)
  end
end