Crate moneta

Expand description

§Currency-safe computations with money amounts.

Money is a special type of quantity. Its unit type is known as Currency.

Money differs from physical quantities mainly in two aspects:

Money amounts are discrete. For each currency there is a smallest fraction that can not be split further.
The relation between different currencies is not fixed, instead, it varies over time.

This package provides types to deal with these specifics. It is based an the package “quantities” with feature “fpdec” (aliasing “AmountT” to “Decimal”).

Currency is an enumeration of all currencies defined in ISO 4217. In addition, for each currency there is a constant named after the 3-character ISO 4217 code.

Currency implements quantities::Unit, so all operations on units can be applied to Currency. Especially, a Currency instance can be multiplied with an AmountT to create a Money instance.

Example:

let amnt = Amnt!(17.95);
let eur_amnt = amnt * EUR;
assert_eq!(eur_amnt.amount(), amnt);
assert_eq!(eur_amnt.unit(), Currency::EUR);

Money implements trait quantities::Quantity, so all operations on quantities can also be applied to instances of Money. Because there is no fixed relation between currencies, there is no implicit conversion between money amounts of different currencies. Resulting values are always quantized to the smallest fraction defined with the currency.

Example:

let qty = Amnt!(3.2);
let price = Money::new(Amnt!(13.58), EUR);
let total = qty * price;
assert_eq!(total.to_string(), "43.46 EUR");

A conversion factor between two currencies can be defined by using the type ExchangeRate. It is given a unit currency (aka base currency), a unit multiple, a term currency (aka price currency) and a term amount, i.e. the amount in term currency equivalent to unit multiple in unit currency.

Multiplying an amount in some currency with an exchange rate with the same currency as unit currency results in the equivalent amount in term currency. Likewise, dividing an amount in some currency with an exchange rate with the same currency as term currency results in the equivalent amount in unit currency.

Examples:

let usd = Dec!(17.95) * USD;
let rate = ExchangeRate::new(USD, 1, EUR, Dec!(0.98078));
let eur = usd * rate;
assert_eq!(eur.to_string(), "17.61 EUR");
let rate = ExchangeRate::new(HKD, 10, EUR, Dec!(1.187253));
let hkd = eur / rate;
assert_eq!(hkd.to_string(), "148.33 HKD");

§Crate features

By default, only the feature std is enabled.

§Ecosystem

std - When enabled, this will cause moneta to use the standard library, so that conversion to string, formatting and printing are available. When disabled, the use of crate alloc together with a system-specific allocator is needed to use that functionality.

§Optional dependencies

serde - When enabled, support for serde is enabled.

Macros§

Amnt: Converts a numeric literal to an AmountT.
Dec: Macro used to convert a number literal into a Decimal.

Structs§

Decimal: Represents a decimal number as a coefficient (i128) combined with a value (u8) specifying the number of fractional decimal digits.
ExchangeRate: Basic representation of a conversion factor between two currencies.
Money: Represents a money amount, i.e. the combination of a numerical value and a money unit, aka. currency.
Rate: The ratio between two related quantity values.

Enums§

Currency: Unit of quantity Money.
SIPrefix: Enum of unit prefixes defined for the System of Units (SI).

Constants§

AED: UAE Dirham
AFN: Afghani
ALL: Lek
AMD: Armenian Dram
ANG: Netherlands Antillean Guilder
AOA: Kwanza
ARS: Argentine Peso
AUD: Australian Dollar
AWG: Aruban Florin
AZN: Azerbaijan Manat
BAM: Convertible Mark
BBD: Barbados Dollar
BDT: Taka
BGN: Bulgarian Lev
BHD: Bahraini Dinar
BIF: Burundi Franc
BMD: Bermudian Dollar
BND: Brunei Dollar
BOB: Boliviano
BOV: Mvdol
BRL: Brazilian Real
BSD: Bahamian Dollar
BTN: Ngultrum
BWP: Pula
BYN: Belarusian Ruble
BZD: Belize Dollar
CAD: Canadian Dollar
CDF: Congolese Franc
CHE: WIR Euro
CHF: Swiss Franc
CHW: WIR Franc
CLF: Unidad de Fomento
CLP: Chilean Peso
CNY: Yuan Renminbi
COP: Colombian Peso
COU: Unidad de Valor Real
CRC: Costa Rican Colon
CUC: Peso Convertible
CUP: Cuban Peso
CVE: Cabo Verde Escudo
CZK: Czech Koruna
DJF: Djibouti Franc
DKK: Danish Krone
DOP: Dominican Peso
DZD: Algerian Dinar
EGP: Egyptian Pound
ERN: Nakfa
ETB: Ethiopian Birr
EUR: Euro
FJD: Fiji Dollar
FKP: Falkland Islands Pound
GBP: Pound Sterling
GEL: Lari
GHS: Ghana Cedi
GIP: Gibraltar Pound
GMD: Dalasi
GNF: Guinean Franc
GTQ: Quetzal
GYD: Guyana Dollar
HKD: Hong Kong Dollar
HNL: Lempira
HRK: Kuna
HTG: Gourde
HUF: Forint
IDR: Rupiah
ILS: New Israeli Sheqel
INR: Indian Rupee
IQD: Iraqi Dinar
IRR: Iranian Rial
ISK: Iceland Krona
JMD: Jamaican Dollar
JOD: Jordanian Dinar
JPY: Yen
KES: Kenyan Shilling
KGS: Som
KHR: Riel
KMF: Comorian Franc
KPW: North Korean Won
KRW: Won
KWD: Kuwaiti Dinar
KYD: Cayman Islands Dollar
KZT: Tenge
LAK: Lao Kip
LBP: Lebanese Pound
LKR: Sri Lanka Rupee
LRD: Liberian Dollar
LSL: Loti
LYD: Libyan Dinar
MAD: Moroccan Dirham
MDL: Moldovan Leu
MGA: Malagasy Ariary
MKD: Denar
MMK: Kyat
MNT: Tugrik
MOP: Pataca
MRU: Ouguiya
MUR: Mauritius Rupee
MVR: Rufiyaa
MWK: Malawi Kwacha
MXN: Mexican Peso
MXV: Mexican Unidad de Inversion (UDI)
MYR: Malaysian Ringgit
MZN: Mozambique Metical
NAD: Namibia Dollar
NGN: Naira
NIO: Cordoba Oro
NOK: Norwegian Krone
NPR: Nepalese Rupee
NZD: New Zealand Dollar
OMR: Rial Omani
PAB: Balboa
PEN: Sol
PGK: Kina
PHP: Philippine Peso
PKR: Pakistan Rupee
PLN: Zloty
PYG: Guarani
QAR: Qatari Rial
RON: Romanian Leu
RSD: Serbian Dinar
RUB: Russian Ruble
RWF: Rwanda Franc
SAR: Saudi Riyal
SBD: Solomon Islands Dollar
SCR: Seychelles Rupee
SDG: Sudanese Pound
SEK: Swedish Krona
SGD: Singapore Dollar
SHP: Saint Helena Pound
SLE: Leone
SLL: Leone
SOS: Somali Shilling
SRD: Surinam Dollar
SSP: South Sudanese Pound
STN: Dobra
SVC: El Salvador Colon
SYP: Syrian Pound
SZL: Lilangeni
THB: Baht
TJS: Somoni
TMT: Turkmenistan New Manat
TND: Tunisian Dinar
TOP: Pa’anga
TRY: Turkish Lira
TTD: Trinidad and Tobago Dollar
TWD: New Taiwan Dollar
TZS: Tanzanian Shilling
UAH: Hryvnia
UGX: Uganda Shilling
USD: US Dollar
USN: US Dollar (Next day)
UYI: Uruguay Peso en Unidades Indexadas (UI)
UYU: Peso Uruguayo
UYW: Unidad Previsional
UZS: Uzbekistan Sum
VED: Bolívar Soberano
VES: Bolívar Soberano
VND: Dong
VUV: Vatu
WST: Tala
XAF: CFA Franc BEAC
XCD: East Caribbean Dollar
XOF: CFA Franc BCEAO
XPF: CFP Franc
YER: Yemeni Rial
ZAR: Rand
ZMW: Zambian Kwacha
ZWL: Zimbabwe Dollar

Traits§

Quantity: The abstract type of quantities.
Unit: The abstract type of units used to define quantities.

Type Aliases§

AmountT: Type used for the numerical part of a Quantity.

Crate monetaCopy item path