Class: Money

Classes and Modules

Module Money::Arithmetic
Module Money::Bank
Module Money::Constructors
Module Money::LocaleBackend
Module Money::RatesStore
Class Money::Allocation
Class Money::Currency
Class Money::Formatter
Class Money::FormattingRules
Class Money::UndefinedSmallestDenomination

Constants

VERSION = '6.13.2'

Attributes

bank	[R]	@!attribute [r] currency @return [Currency] The money's currency. @!attribute [r] bank @return [Money::Bank::Base] The +Money::Bank+-based object which currency exchanges are performed with.
conversion_precision	[RW]	@!attribute [rw] default_bank @return [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. @!attribute default_formatting_rules @return [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 +Money::Formatting#format+ for more details. @example Money.default_formatting_rules = { display_free: true } Money.new(0, "USD").format # => "free" Money.new(0, "USD").format(display_free: false) # => "$0.00" @!attribute [rw] use_i18n @return [Boolean] Use this to disable i18n even if it's used by other objects in your app. @!attribute [rw] infinite_precision @return [Boolean] Use this to enable infinite precision cents @!attribute [rw] conversion_precision @return [Integer] Use this to specify precision for converting Rational to BigDecimal
currency	[R]	@!attribute [r] currency @return [Currency] The money's currency. @!attribute [r] bank @return [Money::Bank::Base] The +Money::Bank+-based object which currency exchanges are performed with.
default_bank	[RW]	@!attribute [rw] default_bank @return [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. @!attribute default_formatting_rules @return [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 +Money::Formatting#format+ for more details. @example Money.default_formatting_rules = { display_free: true } Money.new(0, "USD").format # => "free" Money.new(0, "USD").format(display_free: false) # => "$0.00" @!attribute [rw] use_i18n @return [Boolean] Use this to disable i18n even if it's used by other objects in your app. @!attribute [rw] infinite_precision @return [Boolean] Use this to enable infinite precision cents @!attribute [rw] conversion_precision @return [Integer] Use this to specify precision for converting Rational to BigDecimal
default_currency	[W]	@attr_writer rounding_mode Use this to specify the rounding mode @!attribute default_currency @return [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.
default_formatting_rules	[RW]	@!attribute [rw] default_bank @return [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. @!attribute default_formatting_rules @return [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 +Money::Formatting#format+ for more details. @example Money.default_formatting_rules = { display_free: true } Money.new(0, "USD").format # => "free" Money.new(0, "USD").format(display_free: false) # => "$0.00" @!attribute [rw] use_i18n @return [Boolean] Use this to disable i18n even if it's used by other objects in your app. @!attribute [rw] infinite_precision @return [Boolean] Use this to enable infinite precision cents @!attribute [rw] conversion_precision @return [Integer] Use this to specify precision for converting Rational to BigDecimal
infinite_precision	[RW]	@!attribute [rw] default_bank @return [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. @!attribute default_formatting_rules @return [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 +Money::Formatting#format+ for more details. @example Money.default_formatting_rules = { display_free: true } Money.new(0, "USD").format # => "free" Money.new(0, "USD").format(display_free: false) # => "$0.00" @!attribute [rw] use_i18n @return [Boolean] Use this to disable i18n even if it's used by other objects in your app. @!attribute [rw] infinite_precision @return [Boolean] Use this to enable infinite precision cents @!attribute [rw] conversion_precision @return [Integer] Use this to specify precision for converting Rational to BigDecimal
locale_backend	[RW]	@!attribute [rw] default_bank @return [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. @!attribute default_formatting_rules @return [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 +Money::Formatting#format+ for more details. @example Money.default_formatting_rules = { display_free: true } Money.new(0, "USD").format # => "free" Money.new(0, "USD").format(display_free: false) # => "$0.00" @!attribute [rw] use_i18n @return [Boolean] Use this to disable i18n even if it's used by other objects in your app. @!attribute [rw] infinite_precision @return [Boolean] Use this to enable infinite precision cents @!attribute [rw] conversion_precision @return [Integer] Use this to specify precision for converting Rational to BigDecimal
rounding_mode	[W]	@attr_writer rounding_mode Use this to specify the rounding mode @!attribute default_currency @return [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.
use_i18n	[RW]	@!attribute [rw] default_bank @return [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. @!attribute default_formatting_rules @return [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 +Money::Formatting#format+ for more details. @example Money.default_formatting_rules = { display_free: true } Money.new(0, "USD").format # => "free" Money.new(0, "USD").format(display_free: false) # => "$0.00" @!attribute [rw] use_i18n @return [Boolean] Use this to disable i18n even if it's used by other objects in your app. @!attribute [rw] infinite_precision @return [Boolean] Use this to enable infinite precision cents @!attribute [rw] conversion_precision @return [Integer] Use this to specify precision for converting Rational to BigDecimal

Public Class methods

add_rate(from_currency, to_currency, rate)

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

@param [Currency, String, Symbol] from_currency Currency to exchange from. @param [Currency, String, Symbol] to_currency Currency to exchange to. @param [Numeric] rate Rate to exchange with.

@return [Numeric]

@example

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

default_currency()

disallow_currency_conversion!()

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.

from_amount(amount, currency = default_currency, bank = default_bank)

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

@param [Numeric] amount The numerical value of the money. @param [Currency, String, Symbol] currency The currency format. @param [Money::Bank::*] bank The exchange bank to use.

@example

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

@return [Money]

@see initialize

inherited(base)

locale_backend=(value)

new(obj, currency = Money.default_currency, bank = Money.default_bank)

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.ca_dollar} and {Money.us_dollar}.

@param [Object] obj 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.

@param [Currency, String, Symbol] currency The currency format. @param [Money::Bank::*] bank The exchange bank to use.

@return [Money]

@example

  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">

rounding_mode(mode = nil) {|| ...}

Use this to return the rounding mode. You may also pass a rounding mode and a block to temporarily change it. It will then return the results of the block instead.

@param [BigDecimal::ROUND_MODE] mode

@return [BigDecimal::ROUND_MODE,Yield] rounding mode or block results

@example

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

setup_defaults()

use_i18n=(value)

Public Instance methods

allocate(parts)

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.

@param [Array<Numeric>, Numeric] pass [2, 1, 1] to give twice as much to party1 as party2 or 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).

@return [Array<Money>]

@example

  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)]

amount()

Returns the numerical value of the money

@return [BigDecimal]

@example

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

@see to_d @see fractional

as_ca_dollar()

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

@return [Money]

@example

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

as_euro()

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

@return [Money]

@example

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

as_us_dollar()

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

@return [Money]

@example

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

cents()

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

@return [Integer] when infinite_precision is false @return [BigDecimal] when infinite_precision is true

@see infinite_precision

currency_as_string()

Return string representation of currency object

@return [String]

@example

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

currency_as_string=(val)

Set currency object using a string

@param [String] val The currency string.

@return [Money::Currency]

@example

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

decimal_mark()

Returns a decimal mark according to the locale

@return [String]

dollars()

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

Synonym of amount

@return [BigDecimal]

@example

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

@see amount @see to_d @see cents

exchange_to(other_currency, &rounding_method)

Receive the amount of this money object in another Currency.

@param [Currency, String, Symbol] other_currency Currency to exchange to.

@yield [n] Optional block to use when rounding after exchanging one currency

 for another.

@yieldparam [Float] n The resulting float after exchanging one currency for

 another.

@yieldreturn [Integer]

@return [Money]

@example

  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"))

format(*rules)

Creates a formatted price string according to several rules.

@param [Hash] See Money::Formatter for the list of formatting options

@return [String]

fractional()

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.

@return [Integer] when infinite_precision is false @return [BigDecimal] when infinite_precision is true

@see infinite_precision

hash()

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

@return [Integer]

@example

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

inspect()

Common inspect function

@return [String]

round(rounding_mode = self.class.rounding_mode, rounding_precision = 0)

Round the monetary amount to smallest unit of coinage.

@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.

@return [Money]

@example

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

@see

  Money.infinite_precision

round_to_nearest_cash_value()

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.

@return [Integer] when infinite_precision is false @return [BigDecimal] when infinite_precision is true

@see infinite_precision

split(parts)

Alias for allocate

symbol()

Uses +Currency#symbol+. If nil is returned, defaults to "¤".

@return [String]

@example

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

thousands_separator()

Returns a thousands separator according to the locale

@return [String]

to_d()

Return the amount of money as a BigDecimal.

@return [BigDecimal]

@example

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

to_f()

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.

@return [Float]

@example

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

to_i()

Return the amount of money as a Integer.

@return [Integer]

@example

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

to_money(given_currency = nil)

Conversion to self.

@return [self]

to_s()

Returns the amount of money as a string.

@return [String]

@example

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

with_currency(new_currency)

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

@param [Currency, String, Symbol] new_currency Currency of the new object.

@return [self]

Methods

Included Modules

Classes and Modules

Constants

Attributes

Public Class methods

Public Instance methods