[][src]Crate rusty_money

A library that handles calculating, rounding, displaying, and parsing units of money according to ISO 4217 standards. The main item exported by the library is Money.

Use

This code runs with edition 2018
use rusty_money::money;
use rusty_money::Money;

// The easiest way to create Money objects is by using the money! macro
// which accepts amounts strings or integers and currencies as strings:

money!("-200.00", "USD") == money!(-200, "USD"); // true

// Money objects can be initialized in a few other convenient ways:

use rusty_money::Currency;
use rusty_money::Iso::*;

Money::new(200000, Currency::get(USD));         // amount = 2000 USD
Money::from_major(2000, Currency::get(USD));    // amount = 2000 USD
Money::from_minor(200000, Currency::get(USD));  // amount = 2000 USD
Money::from_str("2,000.00", "USD").unwrap();    // amount = 2000 USD

// Money objects support arithmetic operations:

money!(100, "USD") + money!(100, "USD"); // amount = 200 USD
money!(100, "USD") - money!(100, "USD"); // amount = 0 USD
money!(1, "USD") * 3;                    // amount = 3 USD
money!(3, "USD") / 3;                    // amount = 0.333333333... USD

// Money objects can be compared:

let hundred = money!(100, "USD");
let thousand = money!(1000, "USD");
println!("{}", thousand > hundred);     // false
println!("{}", thousand.is_positive()); // true

// Money objects format themselves when printed:

let usd = money!("-2000.009", "USD");
let eur = money!("-2000.009", "EUR");
println!("{}", usd); // -$2,000.01
println!("{}", eur); // -€2.000,01;


// Money objects can be exchange from one currency to another by setting up an ExchangeRate:

use rusty_money::Exchange;
use rusty_money::ExchangeRate;
use rust_decimal_macros::*;

let rate = ExchangeRate::new(Currency::get(USD), Currency::get(EUR), dec!(1.1)).unwrap();
rate.convert(money!(1000, "USD")); // 1,100 EUR

// ExchangeRate objects can be stored and retrieved from a central Exchange:

let mut exchange = Exchange::new();
exchange.add_or_update_rate(&rate);
exchange.get_rate(Currency::get(USD), Currency::get(EUR));

Money

Money represents financial amounts through a Decimal (owned) and a Currency (refernce). Operations on Money objects always create new instances of Money.

Currency

Currency represents an ISO-4217 currency, and stores metadata like its numeric code, full name and symbol. Operations on Currencies pass around references, since they are unchanging. Only 117 currencies are supported, though the next release will include all ISO-4217 currencies.

Precision and Rounding

The Decimal used in Money is a 128 bit fixed precision decimal number, and can represent values as large as 296 / 1028. Calculations applied on Money objects do not round until this limit. You can use format!() to display the currency in its native precision, though the Decimal will remain unaffected. .round() will create a new instance with permanently reduced precision.

Money supports three types of rounding modes: Half Up, Half Down and Half Even, which is the default.

Formatting

Money.format!() converts a currency into a string and follows local conventions for formatting and displaying amounts. If you need to format output in a more customized way, Formatter accepts a more detailed set of parameters that lets you customize precisely how currencies are displayed as strings.

Macros

money

Create Money from an amount and an ISO currency code.

Structs

Currency

Represents an ISO-4127 currency and its metadata.

Exchange

Stores a collection of exchange rates pairs between currencies.

ExchangeRate

Stores rates and execute conversions between two currencies.

Formatter

Turns Money objects into human readable strings.

LocalFormat

Contains metadata used to format currencies for a specific Locale.

Money

Represents an amount of a given currency.

Params

Represents the parameters which must be provided to format a Money string.

Enums

Iso
Locale

Represents 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.