# DecimalMoney

## Introduction

This is a fork of the [RubyMoney](http://rubymoney.github.com/money) gem,
that uses BigDecimal instead of Integer to store the amount.

BigDecimal was preferred because we found it more intuitive to deal with amounts
as whole values with decimal places than integers representing sub-units, and
wanted a library that used this approach consistently.

### Features

- Provides a `Money` class which encapsulates all information about a certain
  amount of money, such as its value and its currency.
- Provides a `Money::Currency` class which encapsulates all information about
  a monetary unit.
- Represents monetary values as BigDecimal.
- Represents currency as `Money::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.

### Note

Your app must use UTF-8 to function with this library. There are a number of non-ASCII currency attributes.

## Downloading

Install stable releases with the following command:

    gem install decimal-money

## Usage

``` ruby
require 'decimal-money'

# Rounding
money = Money.new(10.125, "USD")
money.amount    #=> 10.13
money.currency  #=> Currency.new("USD")

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

# Arithmetic
Money.new(1.2, "USD") + Money.new(2.3, "USD") == Money.new(3.5, "USD")
Money.new(1000, "USD") - Money.new(200, "USD") == Money.new(800, "USD")
Money.new(1000, "USD") / 5                     == Money.new(200, "USD")
Money.new(1000, "USD") * 5                     == Money.new(5000, "USD")

# Assumptive Currencies
Money.assume_from_symbol = true
Money.new("$100") == Money.new(100, "USD")
Money.new("€100") == Money.new(100, "EUR")
Money.new("£100") == Money.new(100, "GBP")

# Currency conversions
some_code_to_setup_exchange_rates
Money.new(1000, "USD").exchange_to("EUR") == Money.new(some_value, "EUR")
```

## 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
`Money::Currency`.

``` ruby
Money.new(1000, "USD") == Money.new(1000, 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.

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

To define a new `Money::Currency` use `Money::Currency.register` as shown
below.

``` ruby
curr = {
  :priority        => 1,
  :iso_code        => "USD",
  :iso_numeric     => "840",
  :name            => "United States Dollar",
  :symbol          => "$",
  :subunit         => "Cent"
  :subunit_to_unit => 100,
  :separator       => ".",
  :delimiter       => ","
}

Money::Currency.register(curr)
```

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
- `:iso_numeric` the international 3-digit 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
- `:separator` character between the whole and fraction amounts
- `:delimiter` character between each thousands place

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
`Money::Currency` and use in sorting/grouping operation.

For instance, let's assume your Rails application needs to render a currency
selector like the one available
[here](http://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:

``` ruby
# 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 ]

all_currencies(Money::Currency.table)
# => [ :aed, :afn, all, ... ]
```

### Default Currency

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

``` ruby
Money.default_currency = Money::Currency.new("INR")
```

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:

``` ruby
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:

``` ruby
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
[XE](http://www.xe.com) for the current rates or just returns `rand(2)`:

``` ruby
Money.default_bank = ExchangeBankWhichScrapesXeDotCom.new
```

### Implementations

The following is a list of Money.gem compatible currency exchange rate
implementations.

- [eu_central_bank](http://github.com/RubyMoney/eu_central_bank)
- [google_currency](http://github.com/RubyMoney/google_currency)
- [nordea](https://github.com/k33l0r/nordea)
- [nbrb_currency](https://github.com/slbug/nbrb_currency)
- [money-open-exchange-rates](https://github.com/spk/money-open-exchange-rates)
- [money-historical-bank](https://github.com/coutud/money-historical-bank)

## Ruby on Rails

To integrate money in a rails application use [money-rails](http://github.com/RubyMoney/money-rails)
gem or follow the instructions below.

Use the `composed_of` helper to let Active Record deal with embedding the money
object in your models. The following example requires 2 columns:

### If you want to store only the amount (and use default currency)
``` ruby
:price, :decimal, :precision => 18, :scale => 3, :null => false
```

Ensure Money.default_currency is set:

``` ruby
Money.default_currency = "INR"
```

Then in your model file use the convenience method composed_of_money:

``` ruby
composed_of_money :price
composed_of_money :price, :total
```

Which does the following for each symbol passed to it:

``` ruby
composed_of :price,
  :class_name => "Money",
  :mapping => [%w(price amount)],
  :constructor => Proc.new { |amount| Money.new(amount || 0, Money.default_currency) },
  :converter => Proc.new { |value| value.respond_to?(:to_money) ? value.to_money : raise(ArgumentError, "Can't convert #{value.class} to Money") }
```

### If you want to store amount and currency
``` ruby
:price, :decimal, :precision => 18, :scale => 3, :null => false
:currency, :string
```

Then in your model file:

``` ruby
composed_of :price,
  :class_name => "Money",
  :mapping => [%w(price amount), %w(currency currency_as_string)],
  :constructor => Proc.new { |amount, currency| Money.new(amount || 0, currency || Money.default_currency) },
  :converter => Proc.new { |value| value.respond_to?(:to_money) ? value.to_money : raise(ArgumentError, "Can't convert #{value.class} to Money") }
```