# Monetized
[](https://travis-ci.org/theocodes/monetized)
[](https://beta.hexfaktor.org/github/theocodes/monetized)
[](http://inch-ci.org/github/theocodes/monetized)
As a general rule, using floats to store money is a [bad idea](http://spin.atomicobject.com/2014/08/14/currency-rounding-errors/).
Enter Monetized. A library that aims to facilitate the handling of money through a safe way to store currency values and
and providing abstractions to perform arithmetical operations on those values.
Monetized leverages [Decimal](https://github.com/ericmj/decimal)'s ability to safely handle arbitrary precision to perform calculations
on money values.
A typical `%Monetized.Money{}` struct will contain a value in the shape of a `Decimal` struct and a currency (if any) as a string.
Requires elixir version 1.3.x or above as per ecto 2.x
## Usage
Monetized also ships with a `Ecto.Type` that gives us an easier way to store money.
```elixir
alias Monetized.Money
schema "transaction" do
field :description, :string
field :balance, Money, default: Money.zero
timestamps
end
```
By doing this we're able to pass a `%Money{}` struct to the changeset and
insert in the `Repo` since Ecto knows how to convert that struct into a primitive
type to save and back when you read from it.
```elixir
balance = Money.make("£ 100.50")
changeset = Transaction.changeset(%Transaction{}, %{description: "Invoice payment", balance: balance})
# Or
balance = %{value: "100.50", currency: "GBP"}
changeset = Transaction.changeset(%Transaction{}, %{description: "Invoice payment", balance: balance})
```
Check the [docs](http://hexdocs.pm/monetized/api-reference.html) for more.
## Other usage
```elixir
alias Monetized.Money
alias Monetized.Math
# Create with a string
iex> item_one = Money.make("£ 200.50")
#Money<200.50GBP>
# Or a float
iex> item_two = Money.make(10.25, [currency: "GBP"])
#Money<10.25GBP>
# Adding two moneys together
iex> Math.add(item_one, item_two)
#Money<210.75GBP>
# Or an integer
iex> balance = Money.make(100_000, [currency: "USD"])
#Money<100000.00USD>
# Substracting from money (currency inferred from balance)
iex> result = Math.sub(balance, 50_000)
#Money<50000.00USD>
# Getting the string representation
iex> Money.to_string(result, [currency_symbol: true])
"$ 50,000.00"
# You can also use `from_integer/2`, `from_float/2`, `from_decimal/2` and `from_string/2`
# respectively if the desired behavior is to raise when the amount is
# not of the expected type.
# If either the symbol or the currency key is found within the string,
# that currency will be used. However, if a different currency is given in the
# options, it will take precedence.
iex> Money.from_string("£ 200")
#Money<200.00GBP>
iex> Money.from_string("200 EUR")
#Money<200.00EUR>
iex> Money.from_integer(200)
#Money<200.00>
iex> Money.from_float(200.50)
#Money<200.50>
iex> decimal = Decimal.new(10.25)
...> Money.from_decimal(decimal, currency: "EUR")
#Money<10.15EUR>
iex> Money.from_integer("10")
** (FunctionClauseError) no function clause matching in Monetized.Money.from_integer/2
(monetized) lib/money.ex:204: Monetized.Money.from_integer("10", [])
```
Check the [docs](http://hexdocs.pm/monetized/api-reference.html) for more examples
## Config
```elixir
config :monetized, config: [
delimiter: ",",
separator: ".",
currency: "USD",
format: "%cs %n%s%d"
]
```
## Installation
Add monetized to your list of dependencies in `mix.exs`:
```elixir
def deps do
[{:monetized, "~> 0.5.0"}]
end
```
## TODO
- [ ] New currencies can be added through the package's config
- [ ] 1.0.0 ! yay!
## Benchmarking
```sh-session
$ mix deps.get
$ MIX_ENV=bench mix compile
$ MIX_ENV=bench mix bench
```
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
## Licensing
See [LICENSE.md](LICENSE.md)
