A library that handles calculating, rounding, displaying, and parsing units of money according
to ISO 4217 standards. The main items exported by the library are Money
and Currency
.
Money
consists of an amount, which is represented by a Decimal type that it owns and a
Currency
, which is holds a reference to. Currency
represents an ISO-4217 currency, and
stores metadata like its numeric code, full name and symbol.
// Money can be initialized in a few ways:
use rusty_money::{money, Money, Currency};
use rusty_money::Iso::*;
money!(2000, "USD"); // 2000 USD
money!("2000.00", "USD"); // 2000 USD
Money::new(200000, Currency::get(USD)); // 2000 USD
Money::from_major(2000, Currency::get(USD)); // 2000 USD
Money::from_minor(200000, Currency::get(USD)); // 2000 USD
Money::from_str("2,000.00", "USD").unwrap(); // 2000 USD
// Money objects with the same Currency can be compared:
let hundred = money!(100, "USD");
let thousand = money!(1000, "USD");
println!("{}", thousand > hundred); // false
println!("{}", thousand.is_positive()); // true
Money objects are immutable, and operations that change the amount or currency of Money simply create
a new instance. Money uses a 128 bit fixed-precision Decimal
to represents amounts, and it represents values as large as 296 / 1028. By default
operations on Money always retain maximum possible precision. When you do need to round money, you can call
the round
function, which supports three modes:
use rusty_money::{money, Money, Currency, Round};
// Money can be added, subtracted, multiplied and divided:
money!(100, "USD") + money!(100, "USD"); // 200 USD
money!(100, "USD") - money!(100, "USD"); // 0 USD
money!(1, "USD") * 3; // 3 USD
money!(3, "USD") / 3; // 0.333333333... USD
// Money can be rounded by calling the round function:
let usd = money!("-2000.005", "USD"); // 2000.005 USD
usd.round(2, Round::HalfEven); // 2000.00 USD
usd.round(2, Round::HalfUp); // 2000.01 USD
usd.round(0, Round::HalfUp); // 2000 USD
Calling format!
or println!
on Money returns a string with a rounded amount, using separators and symbols
according to the locale of the currency. If you need to customize this output, the Formatter
module
accepts a more detailed set of parameters.
use rusty_money::{money, Money, Currency};
// Money objects can be pretty printed, with appropriate rounding and formatting:
let usd = money!("-2000.009", "USD");
let eur = money!("-2000.009", "EUR");
println!("{}", usd); // -$2,000.01
println!("{}", eur); // -€2.000,01;
The library also provides two additional types - Exchange
and ExchangeRates
to convert Money from one currency
to another.
use rusty_money::{money, Money, Currency, Exchange, ExchangeRate};
use rusty_money::Iso::*;
use rust_decimal_macros::*;
// Convert 1000 USD to EUR at a 2:1 exchange rate.
let rate = ExchangeRate::new(Currency::get(USD), Currency::get(EUR), dec!(0.5)).unwrap();
rate.convert(money!(1000, "USD")); // 500 EUR
// An Exchange can be used to store ExchangeRates for later use
let mut exchange = Exchange::new();
exchange.add_or_update_rate(&rate);
exchange.get_rate(Currency::get(USD), Currency::get(EUR));