logicaffeine_base/

money.rs

//! Money — an exact monetary amount in a specific currency (UNIVERSAL_TYPES Part V).
//!
//! Money rides the exact [`Decimal`] tower, so it **never float-drifts**: `0.10 + 0.20` is exactly
//! `0.30`, not `0.30000000000000004`. The amount is quantised to the currency's minor unit (USD has
//! 2 fractional digits, JPY has 0, BHD has 3), with banker's rounding.
//!
//! Currency is part of the value, and same-currency arithmetic is the only kind that means anything:
//! `5 USD + 1 EUR` has no answer, so `add`/`sub` across currencies return `None` — the exact analogue
//! of the dimensional rule that forbids `meter + gram`. `× ÷` by a plain number scales the amount; a
//! same-currency `Money ÷ Money` is an exact dimensionless ratio.

use core::fmt;
use core::hash::{Hash, Hasher};

use crate::numeric::{Decimal, Rational, RoundingMode};

/// An ISO-4217 currency: its three-letter code and its minor-unit `scale` (the number of fractional
/// digits — `USD`→2, `JPY`→0, `BHD`→3). The code is the identity.
#[derive(Clone, Copy, Debug)]
pub struct Currency {
    pub code: &'static str,
    pub scale: u32,
}

impl PartialEq for Currency {
    fn eq(&self, other: &Self) -> bool {
        self.code == other.code
    }
}
impl Eq for Currency {}
impl Hash for Currency {
    fn hash<H: Hasher>(&self, state: &mut H) {
        self.code.hash(state);
    }
}

/// The currency catalog — resolve an ISO-4217 code (case-insensitive) to its [`Currency`]. A growable
/// data table, mirroring [`crate::quantity::units::by_name`]; the minor-unit scales follow ISO-4217.
pub mod currency {
    use super::Currency;

    /// Look up a currency by its ISO-4217 code (case-insensitive); `None` for an unknown code.
    pub fn by_code(code: &str) -> Option<Currency> {
        let c = code.trim().to_ascii_uppercase();
        let cur = |code, scale| Currency { code, scale };
        Some(match c.as_str() {
            "USD" => cur("USD", 2),
            "EUR" => cur("EUR", 2),
            "GBP" => cur("GBP", 2),
            "CHF" => cur("CHF", 2),
            "CAD" => cur("CAD", 2),
            "AUD" => cur("AUD", 2),
            "NZD" => cur("NZD", 2),
            "SGD" => cur("SGD", 2),
            "HKD" => cur("HKD", 2),
            "CNY" => cur("CNY", 2),
            "INR" => cur("INR", 2),
            "BRL" => cur("BRL", 2),
            "MXN" => cur("MXN", 2),
            "ZAR" => cur("ZAR", 2),
            "SEK" => cur("SEK", 2),
            "NOK" => cur("NOK", 2),
            "DKK" => cur("DKK", 2),
            "RUB" => cur("RUB", 2),
            "TRY" => cur("TRY", 2),
            "PLN" => cur("PLN", 2),
            // Zero-decimal currencies (no minor unit).
            "JPY" => cur("JPY", 0),
            "KRW" => cur("KRW", 0),
            "ISK" => cur("ISK", 0),
            "VND" => cur("VND", 0),
            "CLP" => cur("CLP", 0),
            // Three-decimal currencies.
            "BHD" => cur("BHD", 3),
            "KWD" => cur("KWD", 3),
            "OMR" => cur("OMR", 3),
            "JOD" => cur("JOD", 3),
            "TND" => cur("TND", 3),
            _ => return None,
        })
    }
}

/// An exact monetary amount, quantised to its currency's minor unit.
#[derive(Clone, Debug)]
pub struct Money {
    /// The amount, exact, at `currency.scale` fractional digits.
    pub amount: Decimal,
    pub currency: Currency,
}

impl Money {
    /// Build money, quantising the amount to the currency's minor unit with banker's rounding —
    /// `5 USD` is stored as `5.00`, `19.999 USD` rounds to `20.00`, `100 JPY` stays `100`.
    pub fn of(amount: Decimal, currency: Currency) -> Money {
        Money {
            amount: amount.rescale(currency.scale, RoundingMode::HalfEven),
            currency,
        }
    }

    /// Sum of two amounts in the **same** currency; `None` across currencies (no common meaning).
    pub fn add(&self, other: &Money) -> Option<Money> {
        if self.currency != other.currency {
            return None;
        }
        Some(Money {
            amount: self.amount.add(&other.amount),
            currency: self.currency,
        })
    }

    /// Difference of two amounts in the **same** currency; `None` across currencies.
    pub fn sub(&self, other: &Money) -> Option<Money> {
        if self.currency != other.currency {
            return None;
        }
        Some(Money {
            amount: self.amount.sub(&other.amount),
            currency: self.currency,
        })
    }

    /// Scale an amount by a plain integer (`19.99 USD × 3 = 59.97 USD`), re-quantised to the currency.
    pub fn scale_int(&self, k: i64) -> Money {
        Money::of(self.amount.mul(&Decimal::from_i64(k)), self.currency)
    }

    /// The exact dimensionless ratio of two same-currency amounts (`30 USD ÷ 10 USD = 3`); `None`
    /// across currencies or when the divisor is zero.
    pub fn ratio(&self, other: &Money) -> Option<Rational> {
        if self.currency != other.currency {
            return None;
        }
        self.amount.to_rational().div(&other.amount.to_rational())
    }
}

impl PartialEq for Money {
    /// Value equality: same currency and equal amount (`5 USD == 5.00 USD`, `5 USD ≠ 5 EUR`).
    fn eq(&self, other: &Self) -> bool {
        self.currency == other.currency && self.amount.to_rational() == other.amount.to_rational()
    }
}
impl Eq for Money {}

impl Hash for Money {
    fn hash<H: Hasher>(&self, state: &mut H) {
        self.currency.hash(state);
        self.amount.to_rational().hash(state);
    }
}

impl fmt::Display for Money {
    /// `"19.99 USD"` — the amount at the currency's minor-unit scale, then the code.
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{} {}", self.amount, self.currency.code)
    }
}

/// A pluggable exchange-rate table — the substrate of the **Universal Money Amount** (money's UTC).
/// Each currency code maps to its rate **versus a chosen reference currency**: how many reference
/// units one unit of the currency is worth, exact on the Rational tower (the reference itself is 1).
/// The *source* is interchangeable — a literal table, a CRDT-synced table, an API fetch — they all
/// produce this same value, so with rates in scope money of different currencies shares one
/// coordinate and cross-currency math becomes meaningful (and exact).
#[derive(Clone, Debug, Default)]
pub struct RateTable {
    rates: std::collections::HashMap<String, Rational>,
}

impl RateTable {
    pub fn new() -> Self {
        RateTable {
            rates: std::collections::HashMap::new(),
        }
    }

    /// Record that `1 <code> = rate` reference units (case-insensitive code).
    pub fn set(&mut self, code: &str, rate: Rational) {
        self.rates.insert(code.trim().to_ascii_uppercase(), rate);
    }

    /// The rate of `code` versus the reference, if known.
    pub fn rate(&self, code: &str) -> Option<&Rational> {
        self.rates.get(&code.trim().to_ascii_uppercase())
    }

    /// Convert `m` into `to`, exact via the Rational tower (normalise to the reference, then to the
    /// target), quantised to `to`'s minor unit. `None` if either currency's rate is missing.
    pub fn convert(&self, m: &Money, to: Currency) -> Option<Money> {
        let from_rate = self.rate(m.currency.code)?;
        let to_rate = self.rate(to.code)?;
        let value_in_reference = m.amount.to_rational().mul(from_rate);
        let amount_in_to = value_in_reference.div(to_rate)?;
        Some(Money::of(
            Decimal::from_rational(&amount_in_to, to.scale, RoundingMode::HalfEven),
            to,
        ))
    }
}

thread_local! {
    /// The in-scope exchange-rate context for `<money> in <currency>` conversion. Pluggable: a
    /// program installs it from a literal table, a CRDT-synced table, or an API fetch — they all land
    /// here. `None` until rates are provided (conversion then errors, rather than guessing).
    static AMBIENT_RATES: std::cell::RefCell<Option<RateTable>> =
        const { std::cell::RefCell::new(None) };
}

/// Install (replace) the ambient rate table.
pub fn set_ambient_rates(table: RateTable) {
    AMBIENT_RATES.with(|r| *r.borrow_mut() = Some(table));
}

/// Add or replace one rate in the ambient table (`1 <code> = rate` reference units), creating the
/// table if none is in scope yet.
pub fn set_ambient_rate(code: &str, rate: Rational) {
    AMBIENT_RATES.with(|r| {
        r.borrow_mut()
            .get_or_insert_with(RateTable::new)
            .set(code, rate)
    });
}

/// Drop the ambient rate table (back to "no rates in scope").
pub fn clear_ambient_rates() {
    AMBIENT_RATES.with(|r| *r.borrow_mut() = None);
}

/// True if any rate context is in scope.
pub fn has_ambient_rates() -> bool {
    AMBIENT_RATES.with(|r| r.borrow().is_some())
}

/// Convert `m` to `to` using the ambient rate table. `None` if no rates are in scope or a currency's
/// rate is missing — the caller surfaces a clean error rather than a wrong number.
pub fn ambient_convert(m: &Money, to: Currency) -> Option<Money> {
    AMBIENT_RATES.with(|r| r.borrow().as_ref().and_then(|t| t.convert(m, to)))
}

#[cfg(test)]
#[path = "../../logicaffeine_tests/unit/logicaffeine_base/money/tests.rs"]
mod tests;