Introduction¶ ↑

This library aids one in handling money and different currencies. Features:

• Provides a Money class which encapsulates all information about an certain amount of money, such as its value and its currency.

• Provies a Currency class which encapsulates all information about a monerary unit.

• Represents monetary values as integers, in cents. This avoids floating point rounding errors.

• Represents currency as Currency instances providing an high level of flexibility.

• Provides APIs for exchanging money from one currency to another.

• Has the ability to parse a money and currency strings into the corresponding Money/Currency object.

Resources:

• Website: money.rubyforge.org

• RDoc API: money.rubyforge.org

• Git repository: github.com/FooBarWidget/money

Download¶ ↑

Install stable releases with the following command:

gem install money

The development version (hosted on Github) can be installed with:

git clone git://github.com/FooBarWidget/money.git
cd money
rake install

Usage¶ ↑

Synopsis¶ ↑

require 'money'

# 10.00 USD
money = Money.new(1000, "USD")
money.cents     # => 1000
money.currency  # => Currency.new("USD")

Money.new(1000, "USD") == Money.new(1000, "USD")   # => true
Money.new(1000, "USD") == Money.new(100, "USD")    # => false
Money.new(1000, "USD") == Money.new(1000, "EUR")   # => false

Currency¶ ↑

Currencies are consistently represented as instances of Money::Currency. The most part of Money APIs allows you to supply either a String or a Currency.

Money.new(1000, "USD") == Money.new(900, Currency.new("USD"))
Money.new(1000, "EUR").currency == Currency.new("EUR")

A Money::Currency instance holds all the information about the currency, including the currency symbol, name and much more.

currency = Money.new(1000, "USD")
currency.iso_code
# => "USD"
currency.name
# => "United States Dollar"

To define a new Money::Currency simply add a new item to the Money::Currency::TABLE hash, where the key is the identifier for the Currency object and the value is a hash containing all the currency attributes.

Money::Currency::TABLE[:usd] = {
  :priority => 1,
  :iso_code => "USD",
  :name     => "United States Dollar",
  :symbol   => "$",
  :subunit  => "Cent"
  :subunit_to_unit => "100"
}

The pre-defined set of attributes includes:

* priority: a numerical value you can use to sort/group the currency list
* iso_code: the international 3-letter code as defined by the ISO 4217 standard
* name: the currency name
* symbol: the currency symbol (UTF-8 encoded)
* subunit: the name of the fractional monetary unit
* subunit_to_unit: the proportion between the unit and the subunit

All attributes are optional. Some attributes, such as :symbol, are used by the Money class to print out a representation of the object. Other attributes, such as :name or :priority, exist to provide a basic API you can take advantage of to build your application.

priority¶ ↑

The priority attribute is an arbitrary numerical value you can assign to the Currency and use in sorting/grouping operation.

For instance, let’s assume your Rails application needs to a currency selector like the one available at finance.yahoo.com/currency-converter/ You can create a couple of custom methods to return the list of major_currencies and all_currencies as follows:

# Returns an array of currency id where
# priority < 10
def major_currencies(hash)
  hash.inject([]) do |array, (id, attributes)|
    priority = attributes[:priority]
    if priority && priority < 10
      array[priority] ||= []
      array[priority] << id
    end
    array
  end.compact.flatten
end

# Returns an array of all currency id
def all_currencies(hash)
  hash.keys
end

major_currencies(Money::Currency::TABLE)
# => [ :usd, :eur, :bgp, :cad ]

major_currencies(Money::Currency::TABLE)
# => [ :aed, :afn, all, ... ]

Default Currency¶ ↑

By default Money defaults to USD as its currency. This can be overwritten using

Money.default_currency = Money::Currency.new("CAD")

If you use Rails, then environment.rb is a very good place to put this.

Currency Exchange¶ ↑

Exchanging money is performed through an exchange bank object. The default exchange bank object requires one to manually specify the exchange rate. Here’s an example of how it works:

Money.add_rate("USD", "CAD", 1.24515)
Money.add_rate("CAD", "USD", 0.803115)

Money.us_dollar(100).exchange_to("CAD")  # => Money.new(124, "CAD")
Money.ca_dollar(100).exchange_to("USD")  # => Money.new(80, "USD")

Comparison and arithmetic operations work as expected:

Money.new(1000, "USD") <=> Money.new(900, "USD")   # => 1; 9.00 USD is smaller
Money.new(1000, "EUR") + Money.new(10, "EUR") == Money.new(1010, "EUR")

Money.add_rate("USD", "EUR", 0.5)
Money.new(1000, "EUR") + Money.new(1000, "USD") == Money.new(1500, "EUR")

There is nothing stopping you from creating bank objects which scrapes www.xe.com for the current rates or just returns rand(2):

Money.default_bank = ExchangeBankWhichScrapesXeDotCom.new

Ruby on Rails¶ ↑

Use the compose_of helper to let Active Record deal with embedding the money object in your models. The following example requires a cents and a currency field.

class ProductUnit < ActiveRecord::Base
  belongs_to :product
  composed_of :price, :class_name => "Money", :mapping => [%w(cents cents), %w(currency currency)]

  private        
    validate :cents_not_zero

    def cents_not_zero
      errors.add("cents", "cannot be zero or less") unless cents > 0
    end

    validates_presence_of :sku, :currency
    validates_uniqueness_of :sku        
end