Crate currencies 

💰 currencies

This crate allows for generic manipulation of currencies (both real-world and cryptocurrencies) via the Amount struct and the Currency trait.

The Amount struct is able to represent arbitrary amounts of any supported Currency with the ability to restrict the underlying currencies at compile-time to only allow checked arithmetic operations and requires consuming an Option in all fallible circumstances.

Currency math

use currencies::{*, currency::*};

let apple_cost = amt!(USD, "$3.24");
let orange_cost = Amount::<USD>::from_raw(7_97);
assert!(apple_cost < orange_cost);
assert!(apple_cost + orange_cost > orange_cost);
assert_eq!(format!("{}", apple_cost * orange_cost), "$25.82");
assert_eq!(format!("{}", apple_cost * 3), "$9.72");

let mut total = amt!(DOT, "57622449841.0000000004 DOT");
total -= amt!(DOT, "1000.0 DOT");
total *= Amount::from_raw(2_0000000000u64.into());
assert_eq!(format!("{}", total), "115244897682.0000000008 DOT");

Checked Math

use currencies::{*, currency::*, safety::*};

// When using currency amounts with `Safety = Checked`, the Amount struct has been specially set
// up so that only checked math will be allowed, and you can still use the normal
// operator-based syntax. Thus currency amounts like this should never panic and are
// suitable for use in critical/infallible environments.

let drink_cost = amt_checked!(USD, "$6.29");
let movie_cost = Amount::<USD, Checked>::from_raw(24_99);
let Some(outing_cost) = drink_cost + movie_cost else {
	unimplemented!("compiler forces you to handle this!")
};
assert_eq!(format!("{}", outing_cost), "$31.28");

Modules

amount

Home of the Amount struct and supporting types and impls.

currency

Home of the Currency trait, all built-in currencies such as USD, AAVE, ETH, etc., the define_currency! macro, and related/supporting types.

safety

Home of the Safety sealed type and its two variants Checked and Unchecked.

serde_integration

Contains impls for serde integration

u256

Home of the U256 type, which is a heavily modified, wrapped version of primitive_types::U256 with several custom impls and additional traits from num_traits that are necessary for currency manipulation but not included by default.

Macros

amt

amt_checked

define_currency

Shorthand for defining a new Currency. All ISO-4217 currencies already have an entry.

Structs

Amount

Generically represents an amount of a specified Currency.

ParsedAmount

Represents an Amount that has been parsed from a string representation. Includes Span information.

U256

Wraps primitive_types::U256 enhancing it with some extra trait impls needed for currency manipulation.

Traits

Backing

Automatically implemented on types capable of being used as the “base” / backing type for an Amount of Currency.

Currency

Uniquely defines a particular currency, such as USD, BTC, or ETH.