rusty_money/lib.rs
1//! rusty_money handles the messy parts of dealing with money like rounding, precision, parsing and internationalization.
2//! It supports [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217) currencies, common crypto currencies and lets you
3//! define your own. The main items exported by the library are `Money` and the `iso` and `crypto` currency sets.
4//!
5//! The main items exported by the library are `Money` and the `iso` and `crypto` currency sets.
6//!
7//! # Usage
8//!
9//! A `Money` object is created by supplying an amount and a currency. Amounts can be specified in numeric or string types
10//! but will be stored as precise decimals internally. You can select a bundled currency or make your own. Here's a
11//! quick example of how you would make your own `Currency` and then create some `Money` with it:
12//!
13//! ```edition2018
14//! use rusty_money::{Money, define_currency_set};
15//!
16//! define_currency_set!(
17//! video_game {
18//! GIL: {
19//! code: "GIL",
20//! exponent: 2,
21//! locale: Locale::EnUs,
22//! minor_units: 100,
23//! name: "GIL",
24//! symbol: "G",
25//! symbol_first: true,
26//! }
27//! }
28//! );
29//!
30//! Money::from_major(2_000, video_game::GIL); // 2000 GIL
31//! Money::from_minor(200_000, video_game::GIL); // 2000 GIL
32//! Money::from_str("2,000.00", video_game::GIL).unwrap(); // 2000 GIL
33//!
34//! // Currencies can be looked up by code.
35//! let gil = video_game::find("GIL").unwrap();
36//! Money::from_major(2_000, gil); // 2000 GIL
37//! ```
38//!
39//! ## Features: Currency Sets
40//!
41//! rusty_money provides two currency sets for convenience : `iso`, which implements ISO-4217 currencies and `crypto` which
42//! implements popular cryptocurencies. `iso` is enabled by default, and you can add `crypto` by enabling the feature:
43//!
44//! ```toml
45//! [dependencies]
46//! rusty_money = { version = "0.4.0", features = ["iso", "crypto"] }
47//! ```
48//! The currency sets can then be used like this:
49//!
50//! ```edition2018
51//! use rusty_money::{Money, iso};
52//!
53//! Money::from_major(2_000, iso::USD); // 2000 U.S Dollars
54//! Money::from_major(2_000, iso::GBP); // 2000 British Pounds
55//! ```
56//!
57//! Money objects of the same currency can be compared:
58//!
59//! ```edition2018
60//! use rusty_money::{Money, iso};
61//!
62//! let hundred = Money::from_minor(10_000, iso::USD);
63//! let thousand = Money::from_minor(100_000, iso::USD);
64//!
65//! println!("{}", thousand > hundred); // false
66//! println!("{}", thousand.is_positive()); // true
67//! ```
68//!
69//! ## Precision, Rounding and Math
70//!
71//! Money objects are immutable, and operations that change amounts create a new instance of Money. Amounts are stored
72//! as 128 bit fixed-precision [Decimals](https://github.com/paupino/rust-decimal), and handle values as large as
73//! 2<sup>96</sup> / 10<sup>28</sup>. Operations on Money retain the maximum possible precision. When you want less
74//! precision, you call the `round` function, which supports three modes:
75//!
76//! * [Half Up](https://en.wikipedia.org/wiki/Rounding#Round_half_up)
77//! * [Half Down](https://en.wikipedia.org/wiki/Rounding#Round_half_down)
78//! * [Half Even](https://en.wikipedia.org/wiki/Rounding#Round_half_even) (default)
79//!
80//! Money can be added, subtracted, multiplied and divided like this:
81//!
82//! ```edition2018
83//! use rusty_money::{Money, Round, iso};
84//!
85//! Money::from_minor(100, iso::USD) + Money::from_minor(100, iso::USD); // 2 USD
86//! Money::from_minor(100, iso::USD) - Money::from_minor(100, iso::USD); // 0 USD
87//! Money::from_minor(100, iso::USD) * 3; // 3 USD
88//! Money::from_minor(100, iso::USD) / 3; // 0.333... USD
89//!
90//! let usd = Money::from_str("-2000.005", iso::USD).unwrap(); // 2000.005 USD
91//! usd.round(2, Round::HalfEven); // 2000.00 USD
92//! usd.round(2, Round::HalfUp); // 2000.01 USD
93//! usd.round(0, Round::HalfUp); // 2000 USD
94//!```
95//!
96//! ## Formatting
97//!
98//! Calling `format!` or `println!` on Money returns a string with a rounded amount, using separators and symbols
99//! according to the locale of the currency. If you need to customize this output, the `Formatter` module
100//! accepts a more detailed set of parameters.
101//!
102//! ```edition2018
103//! use rusty_money::{Money, iso};
104//!
105//! let usd = Money::from_str("-2000.009", iso::USD).unwrap();
106//! let eur = Money::from_str("-2000.009", iso::EUR).unwrap();
107//!
108//! println!("{}", usd); // -$2,000.01
109//! println!("{}", eur); // -€2.000,01;
110//! ```
111//!
112//! ## Exchange
113//!
114//! The library also provides two additional types - `Exchange` and `ExchangeRates` to convert Money from one currency
115//! to another.
116//!
117//! ```edition2018
118//! use rusty_money::{Money, Exchange, ExchangeRate, iso};
119//! use rust_decimal_macros::*;
120//!
121//! // Convert 1000 USD to EUR at a 2:1 exchange rate.
122//! let rate = ExchangeRate::new(iso::USD, iso::EUR, dec!(0.5)).unwrap();
123//! rate.convert(Money::from_minor(100_000, iso::USD)); // 500 EUR
124//!
125//! // An Exchange can be used to store ExchangeRates for later use
126//! let mut exchange = Exchange::new();
127//! exchange.set_rate(&rate);
128//! exchange.get_rate(iso::USD, iso::EUR);
129//! ```
130//!
131
132mod currency;
133mod error;
134mod exchange;
135mod format;
136mod locale;
137mod money;
138
139pub use currency::*;
140pub use error::MoneyError;
141pub use exchange::*;
142pub use format::*;
143pub use locale::*;
144pub use money::*;