currencies/
lib.rs

1//! # 💰 currencies
2//!
3//! [![Crates.io](https://img.shields.io/crates/v/currencies)](https://crates.io/crates/currencies)
4//! [![docs.rs](https://img.shields.io/docsrs/currencies?label=docs)](https://docs.rs/currencies/latest/currencies/)
5//! [![Build Status](https://img.shields.io/github/actions/workflow/status/sam0x17/currencies/ci.yaml)](https://github.com/sam0x17/currencies/actions/workflows/ci.yaml?query=branch%3Amain)
6//! [![MIT License](https://img.shields.io/github/license/sam0x17/currencies)](https://github.com/sam0x17/currencies/blob/main/LICENSE)
7//!
8//! This crate allows for generic manipulation of currencies (both real-world and
9//! cryptocurrencies) via the [`Amount`] struct and the [`Currency`] trait.
10//!
11//! The [`Amount`] struct is able to represent arbitrary amounts of any supported [`Currency`]
12//! with the ability to restrict the underlying currencies at compile-time to only allow
13//! checked arithmetic operations and requires consuming an [`Option`] in all fallible
14//! circumstances.
15//!
16//! ### Currency math
17//! ```
18//! use currencies::{*, currency::*};
19//!
20//! let apple_cost = amt!(USD, "$3.24");
21//! let orange_cost = Amount::<USD>::from_raw(7_97);
22//! assert!(apple_cost < orange_cost);
23//! assert!(apple_cost + orange_cost > orange_cost);
24//! assert_eq!(format!("{}", apple_cost * orange_cost), "$25.82");
25//! assert_eq!(format!("{}", apple_cost * 3), "$9.72");
26//!
27//! let mut total = amt!(DOT, "57622449841.0000000004 DOT");
28//! total -= amt!(DOT, "1000.0 DOT");
29//! total *= Amount::from_raw(2_0000000000u64.into());
30//! assert_eq!(format!("{}", total), "115244897682.0000000008 DOT");
31//!```
32//!
33//! ### Checked Math
34//! ```
35//! use currencies::{*, currency::*, safety::*};
36//!
37//! // When using currency amounts with `Safety = Checked`, the Amount struct has been specially set
38//! // up so that only checked math will be allowed, and you can still use the normal
39//! // operator-based syntax. Thus currency amounts like this should never panic and are
40//! // suitable for use in critical/infallible environments.
41//!
42//! let drink_cost = amt_checked!(USD, "$6.29");
43//! let movie_cost = Amount::<USD, Checked>::from_raw(24_99);
44//! let Some(outing_cost) = drink_cost + movie_cost else {
45//! 	unimplemented!("compiler forces you to handle this!")
46//! };
47//! assert_eq!(format!("{}", outing_cost), "$31.28");
48//! ```
49
50#![cfg_attr(not(feature = "std"), no_std)]
51#![warn(missing_docs)]
52
53pub use currencies_core::*;
54pub use currencies_macros::*;