Class Money
In: lib/money/bank/variable_exchange.rb
lib/money/bank/base.rb
lib/money/currency.rb
lib/money/money.rb
lib/money/money/parsing.rb
lib/money/money/formatting.rb
lib/money/money/arithmetic.rb
Parent: Object

encoding: UTF-8

Methods

Included Modules

Comparable Arithmetic Formatting Parsing

Classes and Modules

Module Money::Arithmetic
Module Money::Bank
Module Money::Formatting
Module Money::Parsing
Class Money::Currency

Attributes

assume_from_symbol  [RW]  Use this to enable the ability to assume the currency from a passed symbol

@return [true,false]

bank  [R]  The +Money::Bank+ based object used to perform currency exchanges with.

@return [Money::Bank::*]

cents  [R]  The value of the money in cents.

@return [Integer]

currency  [R]  The currency the money is in.

@return [Currency]

default_bank  [RW]  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.

@return [Money::Bank::*]

default_currency  [RW]  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.

@return [Money::Currency]

use_i18n  [RW]  Use this to disable i18n even if it‘s used by other objects in your app.

@return [true,false]

Public Class methods

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

Creates a new Money object of the given value, using the Canadian dollar currency.

@param [Integer] cents The cents value.

@return [Money]

@example

  n = Money.ca_dollar(100)
  n.cents    #=> 100
  n.currency #=> #<Money::Currency id: cad>

Create a new money object with value 0.

@param [Currency, String, Symbol] currency The currency to use.

@return [Money]

@example

  Money.empty #=> #<Money @cents=0>

Creates a new Money object of the given value, using the Euro currency.

@param [Integer] cents The cents value.

@return [Money]

@example

  n = Money.euro(100)
  n.cents    #=> 100
  n.currency #=> #<Money::Currency id: eur>

Creates a new Money object of cents value in cents, with given currency.

Alternatively you can use the convenience methods like {Money.ca_dollar} and {Money.us_dollar}.

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

@return [Money]

@example

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

@see Money.new_with_dollars

Creates a new Money object of amount value in dollars, with given currency.

The amount value is expressed in dollars where the dollar is the main monetary unit, opposite to the subunit-based representation used internally by this library called cents.

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

@return [Money]

@example

  Money.new_with_dollars(100)
  #=> #<Money @cents=10000 @currency="USD">
  Money.new_with_dollars(100, "USD")
  #=> #<Money @cents=10000 @currency="USD">
  Money.new_with_dollars(100, "EUR")
  #=> #<Money @cents=10000 @currency="EUR">

@see Money.new

Creates a new Money object of the given value, using the American dollar currency.

@param [Integer] cents The cents value.

@return [Money]

@example

  n = Money.us_dollar(100)
  n.cents    #=> 100
  n.currency #=> #<Money::Currency id: usd>

Public Instance methods

Allocates money between different parties without loosing pennies. After the mathmatically split has been performed, left over pennies will be distributed round-robin amongst the parties. This means that parties listed first will likely recieve more pennies then ones that are listed later

@param [0.50, 0.25, 0.25] to give 50% of the cash to party1, 25% ot party2, and 25% to party3.

@return [Array<Money, Money, Money>]

@example

  Money.new(5, "USD").allocate([0.3,0.7)) #=> [Money.new(2), Money.new(3)]
  Money.new(100, "USD").allocate([0.33,0.33,0.33]) #=> [Money.new(34), Money.new(33), Money.new(33)]

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>

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>

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

@return [Money]

@example

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

Return string representation of currency object

@return [String]

@example

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

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>

Returns the value of the money in dollars, instead of in cents.

@return [Float]

@example

  Money.new(100).dollars           # => 1.0
  Money.new_with_dollars(1).dollar # => 1.0

@see to_f @see cents

Receive the amount of this money object in another Currency.

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

@return [Money]

@example

  Money.new(2000, "USD").exchange_to("EUR")
  Money.new(2000, "USD").exchange_to(Currency.new("EUR"))

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

@return [Fixnum]

@example

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

Common inspect function

@return [String]

Split money amongst parties evenly without loosing pennies.

@param [2] number of parties.

@return [Array<Money, Money, Money>]

@example

  Money.new(100, "USD").split(3) #=> [Money.new(34), Money.new(33), Money.new(33)]

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

@return [String]

@example

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

Return the amount of money as a BigDecimal.

@return [BigDecimal]

@example

  Money.us_dollar(100).to_d => BigDecimal.new("1.0")

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

@return [Float]

@example

  Money.us_dollar(100).to_f => 1.0

Conversation to self.

@return [self]

Returns the amount of money as a string.

@return [String]

@example

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

[Validate]