Class Money::Bank::VariableExchange
In: lib/money/bank/variable_exchange.rb
Parent: Base

Class for aiding in exchanging money between different currencies. By default, the Money class uses an object of this class (accessible through +Money#bank+) for performing currency exchanges.

By default, +Money::Bank::VariableExchange+ has no knowledge about conversion rates. One must manually specify them with add_rate, after which one can perform exchanges with +exchange_with+.

@example

  bank = Money::Bank::VariableExchange.new
  bank.add_rate("USD", "CAD", 1.24515)
  bank.add_rate("CAD", "USD", 0.803115)

  c1 = 100_00.to_money("USD")
  c2 = 100_00.to_money("CAD")

  # Exchange 100 USD to CAD:
  bank.exchange_with(c1, "CAD") #=> #<Money @cents=1245150>

  # Exchange 100 CAD to USD:
  bank.exchange_with(c2, "USD") #=> #<Money @cents=803115>

Methods

Constants

RATE_FORMATS = [:json, :ruby, :yaml]   Available formats for importing/exporting rates.

Attributes

rates  [R] 

Public Instance methods

Registers a conversion rate and returns it (uses +set_rate+).

@param [Currency, String, Symbol] from Currency to exchange from. @param [Currency, String, Symbol] to Currency to exchange to. @param [Numeric] rate Rate to use when exchanging currencies.

@return [Numeric]

@example

  bank = Money::Bank::VariableExchange.new
  bank.add_rate("USD", "CAD", 1.24515)
  bank.add_rate("CAD", "USD", 0.803115)

Exchanges the given Money object to a new Money object in to_currency.

@param [Money] from

        The +Money+ object to exchange.

@param [Currency, String, Symbol] to_currency

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

@raise +Money::Bank::UnknownRate+ if the conversion rate is unknown.

@example

  bank = Money::Bank::VariableExchange.new
  bank.add_rate("USD", "CAD", 1.24515)
  bank.add_rate("CAD", "USD", 0.803115)

  c1 = 100_00.to_money("USD")
  c2 = 100_00.to_money("CAD")

  # Exchange 100 USD to CAD:
  bank.exchange_with(c1, "CAD") #=> #<Money @cents=1245150>

  # Exchange 100 CAD to USD:
  bank.exchange_with(c2, "USD") #=> #<Money @cents=803115>

Return the known rates as a string in the format specified. If file is given will also write the string out to the file specified. Available formats are +:json+, +:ruby+ and +:yaml+.

@param [Symbol] format Request format for the resulting string. @param [String] file Optional file location to write the rates to.

@return [String]

@raise +Money::Bank::UnknownRateFormat+ if format is unknown.

@example

  bank = Money::Bank::VariableExchange.new
  bank.set_rate("USD", "CAD", 1.24515)
  bank.set_rate("CAD", "USD", 0.803115)

  s = bank.export_rates(:json)
  s #=> "{\"USD_TO_CAD\":1.24515,\"CAD_TO_USD\":0.803115}"

Retrieve the rate for the given currencies. Uses Mutex to synchronize data access.

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

@return [Numeric]

@example

  bank = Money::Bank::VariableExchange.new
  bank.set_rate("USD", "CAD", 1.24515)
  bank.set_rate("CAD", "USD", 0.803115)

  bank.get_rate("USD", "CAD") #=> 1.24515
  bank.get_rate("CAD", "USD") #=> 0.803115

Loads rates provided in s given the specified format. Available formats are +:json+, +:ruby+ and +:yaml+.

@param [Symbol] format The format of s. @param [String] s The rates string.

@return [self]

@raise +Money::Bank::UnknownRateFormat+ if format is unknown.

@example

  s = "{\"USD_TO_CAD\":1.24515,\"CAD_TO_USD\":0.803115}"
  bank = Money::Bank::VariableExchange.new
  bank.import_rates(:json, s)

  bank.get_rate("USD", "CAD") #=> 1.24515
  bank.get_rate("CAD", "USD") #=> 0.803115

Set the rate for the given currencies. Uses Mutex to synchronize data access.

@param [Currency, String, Symbol] from Currency to exchange from. @param [Currency, String, Symbol] to Currency to exchange to. @param [Numeric] rate Rate to use when exchanging currencies.

@return [Numeric]

@example

  bank = Money::Bank::VariableExchange.new
  bank.set_rate("USD", "CAD", 1.24515)
  bank.set_rate("CAD", "USD", 0.803115)

Setup rates hash and mutex for rates locking

@return [self]

[Validate]