[−][src]Crate rusty_money
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
.
Usage
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
Precision and Rounding
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
Formatting
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;
Exchange
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));
Macros
money | Creates a |
Structs
Currency | A struct which represent an ISO-4127 currency. |
Exchange | A struct to store |
ExchangeRate | A struct to store rates of conversion between two currencies. |
Formatter | A helper struct to convert Money objects into human readable strings. |
LocalFormat | A struct which contains currency formatting metadata for a region. |
Money | A struct which represents an amount of a given currency. |
Params | A struct which contains parameters consumer by |
Enums
Iso | Enumerates ISO-4217 Alphabetic Codes. |
Locale | Enumerates regions which have unique formatting standards for Currencies. |
MoneyError | Standard Error type for this crate. |
Position | Enumerates different items which can be positioned in a Money string. |
Round | Enumerates different strategies that can be used to round Money. |