= Money $

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.
- Represents monetary values as integers, in cents. This avoids floating point
  rounding errors.
- Provides APIs for exchanging money from one currency to another.
- Has the ability to parse a money string into a Money object.
- Provides ActiveRecord "has_money" method.
- Autofetch rates from ECB

== Install

  gem sources -a http://gems.github.com
  gem install <this-fork>-money


== Use

=== Synopsis

  require 'money'

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

  Money.new(880088, "EUR").format # => €8,800.88
  Money.new(-8000).format(:no_cents => true)  # => $-80

  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


=== Rounding

You can use round_to_coin when you don't have currency with coins for cents.
E.g. if the smallest coin is 0.50, then

  Money.new(1448, 'CZK').round_to_coin(50).to_s  # => "14.50"


=== 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("CAD", 0.803115)
  Money.add_rate("USD", 1.24515)

  Money.us_dollar(100_00).exchange_to("CAD")  # => Money.new(15504, "CAD")
  Money.ca_dollar(100_00).exchange_to("USD")  # => Money.new(6450, "USD")

or

  Money.us_dollar(100).as_cad              # => Money.new(155, "CAD")
  Money.ca_dollar(100).as_usd              # => Money.new(64, "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("EUR", 0.5)
  Money.new(1000, "EUR") + Money.new(1000, "USD") == Money.new(1500, "EUR")

Fetch the exchange rates published by the European Bank

  Money.default_bank.fetch_rates          # Fetch the rates
  Money.default_bank.auto_fetch 3600      # Fetch the rates every hour
  Money.default_bank.stop_fetch           # Stop auto-fetch

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

  Money.default_bank = ExchangeBankWhichScrapesXeDotCom.new


=== Default Currency

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

  Money.default_currency = "CAD"

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


=== Autofetch rates

By default, Money won't fetch the rates automatically, you need to call: @bank.fetch_rates

If you have your bank default rates configured, it'll fetch all possible rates from it,
if you don't, It'll fetch all rates to and from your default_currency.

Money uses the ECB XML Feed.


== Webapps

=== Ruby on Rails

Use the +has_money+ method to embed the money object in your models.
The following example requires a +price_cents+ and a +price_currency+
fields on the database.

config/enviroment.rb

  require.gem 'bobek-money', :lib => 'money'

app/models/product.rb

  class Product < ActiveRecord::Base
    belongs_to :product
    has_money :price

    validates_numericality_of :price_cents, :greater_than => 0
  end

migration:

  create_table :products do |t|
    t.integer :price_cents
    t.string  :price_currency
  end


=== jQuery

Check out http://meiaduzia.com.br/cuducos2/priceformat for a nice
mask for webapp's textfields.


== About

Resources:

Orinally developed by:

- Forked from: http://github.com/FooBarWidget/money
- Website: http://money.rubyforge.org
- RDoc API: http://money.rubyforge.org


This branch is part of:

:: http://github.com/bobek/money
:: http://github.com/nofxx/money
:: http://github.com/ShadowBelmove/money