[−][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. |