Principle:Avhz RustQuant Foreign Exchange
| Knowledge Sources | |
|---|---|
| Domains | Foreign_Exchange, Financial_Instruments |
| Last Updated | 2026-02-07 21:00 GMT |
Overview
Foreign exchange primitives providing type-safe representations of currencies, monetary amounts, and exchange rate conversions based on the ISO 4217 standard.
Description
Foreign Exchange in RustQuant is modeled through three core types that work together to represent and manipulate monetary values across different currencies.
Currency is a struct that encodes ISO 4217 currency data including the currency name, symbol, alphabetic and numeric codes, minor unit (decimal places), and fractions per unit. The library defines over 150 world currencies as compile-time constants generated via a Rust macro, ranging from AED (United Arab Emirates Dirham) to ZWL (Zimbabwean Dollar). Each Currency implements the Instrument trait with a default price of 1.0.
Money combines a Currency with an f64 amount, providing a type-safe monetary value. It supports arithmetic operations (addition, subtraction, multiplication, division) but enforces currency matching at runtime -- attempting to add Money of different currencies will panic. Money implements PartialOrd to enable comparison of amounts within the same currency.
ExchangeRate represents a directional conversion rate between two currencies, storing the source currency, target currency, and the numeric rate. The convert method transforms a Money value from the source currency to the target currency by multiplying the amount by the rate. An Exchange struct aggregates multiple ExchangeRate entries in a HashMap keyed by CurrencyPair, enabling lookup and conversion between any pair of registered currencies.
Usage
Use these types when modeling multi-currency financial instruments, performing FX conversions, or building systems that need to enforce currency consistency in arithmetic operations. The Currency constants provide a convenient way to reference standard currencies without manual construction.
Theoretical Basis
The foreign exchange module is grounded in the ISO 4217 standard, which assigns unique alphabetic and numeric codes to each currency. Exchange rates follow the standard quoting convention where a rate of 0.85 for USD/EUR means 1 USD equals 0.85 EUR. The conversion formula is:
amount_target = amount_source * rate
The minor unit field captures the number of decimal places used in each currency (e.g., 2 for USD, 0 for JPY, 3 for BHD), which is important for rounding and display purposes.