Struct Rate 

pub struct Rate<From: Currency, To: Currency> {
    rate: Decimal,
    metadata_timestamp_unix_secs: Option<u64>,
    metadata_source: Option<&'static str>,
    _from: PhantomData<From>,
    _to: PhantomData<To>,
}

An exchange rate from one currency to another.

Exchange rates are immutable after construction and use phantom types to ensure type-safe conversions at compile time.

Type Parameters

• From - The source currency
• To - The target currency

Examples

use typed_money::{Rate, USD, EUR};

// Create a rate: 1 USD = 0.85 EUR
let rate = Rate::<USD, EUR>::new(0.85);

Immutability

Rates are immutable after creation to ensure auditability and prevent accidental modifications that could lead to financial errors.

Fields

rate: Decimal

The exchange rate value (always positive)

metadata_timestamp_unix_secs: Option<u64>

Optional UNIX timestamp (seconds) representing when the rate was observed

Kept optional to avoid forcing callers to provide a timestamp. Using a primitive preserves Copy and avoids allocations.

metadata_source: Option<&'static str>

Optional static source identifier for auditability (e.g., “ECB”, “Manual”)

Using &'static str preserves Copy. Callers can pass string literals for simple source tagging without allocations.

_from: PhantomData<From>

Phantom data for source currency (zero runtime cost)

_to: PhantomData<To>

Phantom data for target currency (zero runtime cost)

Implementations

impl<From: Currency, To: Currency> Rate<From, To>

pub fn try_new(rate: f64) -> MoneyResult<Self>

Tries to create a new exchange rate from a floating-point value.

Returns an error if the rate is zero, negative, NaN, or infinite.

Examples

use typed_money::{Rate, USD, EUR};

let rate = Rate::<USD, EUR>::try_new(0.85)?;  // 1 USD = 0.85 EUR
assert!(rate.value() > &rust_decimal::Decimal::ZERO);

// Invalid rates return an error
assert!(Rate::<USD, EUR>::try_new(0.0).is_err());
assert!(Rate::<USD, EUR>::try_new(-1.0).is_err());

Examples found in repository

examples/error_handling.rs (line 81)

fn main() {
    println!("=== Error Handling Examples ===\n");

    // ========================================
    // Parse Errors
    // ========================================
    println!("1. PARSING ERRORS");
    println!("-----------------");

    // Valid parsing
    match Amount::<USD>::from_str("123.45") {
        Ok(amount) => println!("✓ Parsed: {}", amount),
        Err(e) => println!("✗ Error: {}", e),
    }

    // Invalid formats
    let invalid_inputs = vec!["invalid", "12.34.56", "abc123", "", "  "];

    println!("\nInvalid inputs:");
    for input in invalid_inputs {
        match Amount::<USD>::from_str(input) {
            Ok(amount) => println!("  '{}' → {}", input, amount),
            Err(MoneyError::ParseError { input: inp, .. }) => {
                println!("  '{}' → Parse error (input: '{}')", input, inp);
            }
            Err(e) => println!("  '{}' → Error: {}", input, e),
        }
    }

    // ========================================
    // Precision Errors
    // ========================================
    println!("\n2. PRECISION ERRORS");
    println!("-------------------");

    // Division creates excess precision
    let amount = Amount::<USD>::from_major(10) / 3; // $3.333...
    println!("After division: {}", amount);
    println!("Decimal places: {}", amount.precision());
    println!("Currency expects: {}", Amount::<USD>::currency_precision());

    // Check for precision issues
    match amount.check_precision() {
        Ok(()) => println!("✓ Precision OK"),
        Err(MoneyError::PrecisionError {
            expected,
            actual,
            suggestion,
            ..
        }) => {
            println!("✗ Precision error:");
            println!("  Expected: {} decimals", expected);
            println!("  Actual: {} decimals", actual);
            println!("  Suggestion: {}", suggestion);

            // Recover by normalizing
            let normalized = amount.normalize();
            println!("\n✓ After normalizing: {}", normalized);
            println!("  Precision OK: {}", normalized.check_precision().is_ok());
        }
        Err(e) => println!("✗ Unexpected error: {}", e),
    }

    // ========================================
    // Invalid Rate Errors
    // ========================================
    println!("\n3. INVALID RATE ERRORS");
    println!("----------------------");

    // Valid rate
    match Rate::<USD, EUR>::try_new(0.85) {
        Ok(rate) => println!("✓ Valid rate: {}", rate.value()),
        Err(e) => println!("✗ Error: {}", e),
    }

    // Invalid rates
    let invalid_rates = vec![
        ("negative", -1.0),
        ("zero", 0.0),
        ("NaN", f64::NAN),
        ("infinity", f64::INFINITY),
    ];

    println!("\nInvalid rates:");
    for (desc, value) in invalid_rates {
        match Rate::<USD, EUR>::try_new(value) {
            Ok(rate) => println!(
                "  {} ({}) → Unexpected success: {}",
                desc,
                value,
                rate.value()
            ),
            Err(MoneyError::InvalidRate { reason, .. }) => {
                println!("  {} ({}) → {}", desc, value, reason);
            }
            Err(e) => println!("  {} ({}) → Error: {}", desc, value, e),
        }
    }

    // ========================================
    // Error Suggestions
    // ========================================
    println!("\n4. ERROR RECOVERY SUGGESTIONS");
    println!("------------------------------");

    let errors = vec![
        MoneyError::PrecisionError {
            currency: "USD",
            expected: 2,
            actual: 5,
            suggestion: "Use normalize() or round() to adjust precision".to_string(),
        },
        MoneyError::InvalidRate {
            value: "-1.0".to_string(),
            reason: "Rate must be positive".to_string(),
        },
        MoneyError::ParseError {
            input: "abc".to_string(),
            expected_currency: Some("USD"),
            reason: "Invalid number format".to_string(),
        },
    ];

    for error in errors {
        println!("\nError: {}", error);
        println!("Suggestion: {}", error.suggestion());
        if let Some(currency) = error.currency() {
            println!("Currency: {}", currency);
        }
    }

    // ========================================
    // Safe Division
    // ========================================
    println!("\n5. SAFE DIVISION");
    println!("----------------");

    let amount = Amount::<USD>::from_major(100);

    // Division by zero is handled
    let divisor = 0;
    println!("Dividing {} by {}...", amount, divisor);

    if divisor == 0 {
        println!("✗ Cannot divide by zero!");
        println!("  Handled before attempting division");
    } else {
        let result = amount / divisor;
        println!("✓ Result: {}", result);
    }

    // Safe division with non-zero
    let safe_divisor = 3;
    let result = amount / safe_divisor;
    println!("\nDividing {} by {}: {}", amount, safe_divisor, result);

    // ========================================
    // Pattern Matching on Errors
    // ========================================
    println!("\n6. PATTERN MATCHING");
    println!("-------------------");

    fn parse_and_handle(input: &str) -> MoneyResult<Amount<USD>> {
        Amount::<USD>::from_str(input)
    }

    let inputs = vec!["123.45", "invalid", "999.99"];

    for input in inputs {
        print!("Parsing '{}': ", input);

        match parse_and_handle(input) {
            Ok(amount) => {
                println!("✓ Success: {}", amount);
            }
            Err(MoneyError::ParseError { input, reason, .. }) => {
                println!("✗ Parse error");
                println!("  Input: '{}'", input);
                println!("  Reason: {}", reason);
            }
            Err(e) => {
                println!("✗ Other error: {}", e);
            }
        }
    }

    // ========================================
    // Error Propagation with ?
    // ========================================
    println!("\n7. ERROR PROPAGATION");
    println!("--------------------");

    fn calculate_total(price_str: &str, quantity: i64) -> MoneyResult<Amount<USD>> {
        let price = Amount::<USD>::from_str(price_str)?;
        let total = price * quantity;
        total.check_precision()?;
        Ok(total)
    }

    match calculate_total("29.99", 3) {
        Ok(total) => println!("✓ Total: {}", total),
        Err(e) => println!("✗ Error: {}", e),
    }

    match calculate_total("invalid", 3) {
        Ok(total) => println!("✓ Total: {}", total),
        Err(e) => println!("✗ Error: {}", e),
    }

    // ========================================
    // Recovering from Errors
    // ========================================
    println!("\n8. ERROR RECOVERY");
    println!("-----------------");

    fn parse_with_fallback(input: &str, fallback: Amount<USD>) -> Amount<USD> {
        Amount::<USD>::from_str(input).unwrap_or(fallback)
    }

    let fallback = Amount::<USD>::from_major(0);

    let inputs = vec!["123.45", "invalid", "67.89"];
    for input in inputs {
        let amount = parse_with_fallback(input, fallback);
        println!("'{}' → {}", input, amount);
    }

    // ========================================
    // Validation Before Operations
    // ========================================
    println!("\n9. VALIDATION");
    println!("-------------");

    fn safe_divide(amount: Amount<USD>, divisor: i64) -> MoneyResult<Amount<USD>> {
        if divisor == 0 {
            return Err(MoneyError::InvalidAmount {
                currency: Some("USD"),
                reason: "Cannot divide by zero".to_string(),
            });
        }

        let result = amount / divisor;

        // Check precision after division
        result.check_precision()?;

        Ok(result)
    }

    let amount = Amount::<USD>::from_major(100);

    match safe_divide(amount, 0) {
        Ok(result) => println!("  Division by 0: {}", result),
        Err(e) => println!("  Division by 0: Error - {}", e),
    }

    match safe_divide(amount, 3) {
        Ok(result) => println!("  Division by 3: {}", result),
        Err(e) => println!("  Division by 3: Error - {}", e),
    }

    // ========================================
    // Real-World: Parsing User Input
    // ========================================
    println!("\n10. REAL-WORLD: PARSING USER INPUT");
    println!("-----------------------------------");

    fn process_payment(amount_str: &str) -> MoneyResult<String> {
        // Parse the amount
        let amount = Amount::<USD>::from_str(amount_str)?;

        // Validate it's positive
        if amount.to_minor() <= 0 {
            return Err(MoneyError::InvalidAmount {
                currency: Some("USD"),
                reason: "Payment amount must be positive".to_string(),
            });
        }

        // Process the payment
        let fee = (amount * 3) / 100; // 3% fee
        let total = amount + fee;

        Ok(format!(
            "Payment: {}, Fee: {}, Total: {}",
            amount, fee, total
        ))
    }

    let test_inputs = vec!["100.00", "0", "-50", "abc", "250.50"];

    for input in test_inputs {
        println!("\nProcessing payment: '{}'", input);
        match process_payment(input) {
            Ok(summary) => println!("  ✓ {}", summary),
            Err(e) => {
                println!("  ✗ Error: {}", e);
                let suggestion = e.suggestion();
                println!("    Hint: {}", suggestion);
            }
        }
    }

    // ========================================
    // Rounding to Fix Precision
    // ========================================
    println!("\n11. FIXING PRECISION WITH ROUNDING");
    println!("-----------------------------------");

    let amount = Amount::<USD>::from_major(10) / 3; // Creates excess precision

    println!("Original: {}", amount);
    println!(
        "Precision check: {}",
        if amount.check_precision().is_ok() {
            "✓ OK"
        } else {
            "✗ Excess precision"
        }
    );

    // Fix with rounding
    let rounded = amount.round(RoundingMode::HalfUp);
    println!("\nRounded: {}", rounded);
    println!(
        "Precision check: {}",
        if rounded.check_precision().is_ok() {
            "✓ OK"
        } else {
            "✗ Excess precision"
        }
    );

    // Or normalize (uses banker's rounding)
    let normalized = amount.normalize();
    println!("\nNormalized: {}", normalized);
    println!(
        "Precision check: {}",
        if normalized.check_precision().is_ok() {
            "✓ OK"
        } else {
            "✗ Excess precision"
        }
    );

    println!("\n=== All error handling examples completed! ===");
}

pub fn new(rate: f64) -> Self

Creates a new exchange rate from a floating-point value.

Panics

Panics if the rate is zero, negative, NaN, or infinite. For a non-panicking version, use try_new.

Examples

use typed_money::{Rate, USD, EUR};

let rate = Rate::<USD, EUR>::new(0.85);  // 1 USD = 0.85 EUR

Panics Examples

use typed_money::{Rate, USD, EUR};

let rate = Rate::<USD, EUR>::new(0.0);  // Panics: rate must be positive

Examples found in repository

examples/conversions.rs (line 23)

fn main() {
    println!("=== Currency Conversion Examples ===\n");

    // ========================================
    // Basic Conversion
    // ========================================
    println!("1. BASIC CONVERSION");
    println!("-------------------");

    let usd_amount = Amount::<USD>::from_major(100);
    println!("Starting amount: {}", usd_amount);

    // Create an exchange rate: 1 USD = 0.85 EUR
    let usd_to_eur = Rate::<USD, EUR>::new(0.85);
    println!("Exchange rate: 1 USD = 0.85 EUR");

    // Convert
    let eur_amount = usd_amount.convert(&usd_to_eur);
    println!("Converted amount: {}", eur_amount);
    println!("(${} × 0.85 = €{})\n", 100, eur_amount.to_major_floor());

    // ========================================
    // Inverse Rates
    // ========================================
    println!("2. INVERSE RATES");
    println!("----------------");

    let usd_to_eur = Rate::<USD, EUR>::new(0.85);
    println!("USD → EUR rate: {}", usd_to_eur.value());

    // Get the inverse rate automatically
    let eur_to_usd = usd_to_eur.inverse();
    println!("EUR → USD rate (inverse): {}", eur_to_usd.value());
    println!("(1 / 0.85 = ~1.176)\n");

    // Converting back
    let original_usd = Amount::<USD>::from_major(100);
    let eur = original_usd.convert(&usd_to_eur);
    let back_to_usd = eur.convert(&eur_to_usd);

    println!("Original: {}", original_usd);
    println!("To EUR:   {}", eur);
    println!("Back to USD: {}", back_to_usd);
    println!("(Should be approximately the same)\n");

    // ========================================
    // Multiple Conversions
    // ========================================
    println!("3. MULTIPLE CONVERSIONS");
    println!("-----------------------");

    let usd = Amount::<USD>::from_major(1000);
    println!("Starting with: {}", usd);

    // Define multiple rates
    let usd_to_eur = Rate::<USD, EUR>::new(0.85);
    let usd_to_gbp = Rate::<USD, GBP>::new(0.73);
    let usd_to_jpy = Rate::<USD, JPY>::new(110.0);

    println!("\nExchange rates:");
    println!("  1 USD = {} EUR", usd_to_eur.value());
    println!("  1 USD = {} GBP", usd_to_gbp.value());
    println!("  1 USD = {} JPY", usd_to_jpy.value());

    println!("\nConversions:");
    let eur = usd.convert(&usd_to_eur);
    let gbp = usd.convert(&usd_to_gbp);
    let jpy = usd.convert(&usd_to_jpy);

    println!("  {} → {}", usd, eur);
    println!("  {} → {}", usd, gbp);
    println!("  {} → {}", usd, jpy);

    // ========================================
    // Chained Conversions
    // ========================================
    println!("\n4. CHAINED CONVERSIONS");
    println!("----------------------");

    println!("Converting USD → EUR → GBP");

    let usd = Amount::<USD>::from_major(100);
    let usd_to_eur = Rate::<USD, EUR>::new(0.85);
    let eur_to_gbp = Rate::<EUR, GBP>::new(0.86);

    println!("Starting: {}", usd);
    let eur = usd.convert(&usd_to_eur);
    println!("After USD→EUR: {}", eur);
    let gbp = eur.convert(&eur_to_gbp);
    println!("After EUR→GBP: {}", gbp);
    println!("(${} × 0.85 × 0.86 = £{})\n", 100, gbp.to_major_floor());

    // ========================================
    // Rate Metadata for Auditability
    // ========================================
    println!("5. RATE METADATA FOR AUDITABILITY");
    println!("----------------------------------");

    // Create a rate with metadata
    let rate = Rate::<USD, EUR>::new(0.85)
        .with_timestamp_unix_secs(1700000000)
        .with_source("ECB"); // European Central Bank

    println!("Rate: {}", rate.value());
    println!("Timestamp: {:?}", rate.timestamp_unix_secs());
    println!("Source: {:?}", rate.source());

    let amount = Amount::<USD>::from_major(1000);
    let converted = amount.convert(&rate);
    println!(
        "\nConverted {} to {} using rate from {:?}",
        amount,
        converted,
        rate.source().unwrap_or("unknown")
    );

    // ========================================
    // Real-World Example: International Payment
    // ========================================
    println!("\n6. REAL-WORLD EXAMPLE: INTERNATIONAL PAYMENT");
    println!("---------------------------------------------");

    // Customer pays in USD
    let payment_usd = Amount::<USD>::from_major(250);
    println!("Customer payment: {}", payment_usd);

    // Current exchange rate (would come from an API in production)
    let current_rate = Rate::<USD, EUR>::new(0.92)
        .with_timestamp_unix_secs(1700000000)
        .with_source("API");

    // Convert to EUR
    let payment_eur = payment_usd.convert(&current_rate);
    println!("Converted to EUR: {}", payment_eur);

    // Calculate fees
    let fee_percentage = 3; // 3% transaction fee
    let fee = (payment_eur * fee_percentage) / 100;
    println!("Transaction fee ({}%): {}", fee_percentage, fee);

    let final_amount = payment_eur - fee;
    println!("Final amount to recipient: {}", final_amount);

    println!("\nTransaction summary:");
    println!("  Original: {}", payment_usd);
    println!(
        "  Rate: {} (from {:?})",
        current_rate.value(),
        current_rate.source().unwrap_or("N/A")
    );
    println!("  Converted: {}", payment_eur);
    println!("  Fee: -{}", fee);
    println!("  Final: {}", final_amount);

    // ========================================
    // Type Safety with Conversions
    // ========================================
    println!("\n7. TYPE SAFETY");
    println!("--------------");

    println!("✓ Can only convert with matching rate types");
    println!("✓ USD amount requires Rate<USD, X>");
    println!("✗ Cannot use Rate<EUR, GBP> on USD amount (compile error!)");
    println!("\nThe type system ensures you always use the correct exchange rate!");

    // This would NOT compile:
    // let usd = Amount::<USD>::from_major(100);
    // let wrong_rate = Rate::<EUR, GBP>::new(0.86);
    // let invalid = usd.convert(&wrong_rate);  // Compile error!

    println!("\n=== All conversion examples completed! ===");
}

examples/global_currencies.rs (line 157)

fn main() {
    println!("=== Typed Money - Global Currencies Example ===\n");

    // 1. MAJOR FIAT CURRENCIES
    println!("1. MAJOR FIAT CURRENCIES");
    println!("------------------------");
    let usd = Amount::<USD>::from_major(100);
    let cad = Amount::<CAD>::from_major(135);
    let chf = Amount::<CHF>::from_major(90);
    let aud = Amount::<AUD>::from_major(150);
    let nzd = Amount::<NZD>::from_major(160);

    println!("USD: {} ({} decimals)", usd, USD::DECIMALS);
    println!("CAD: {} ({} decimals)", cad, CAD::DECIMALS);
    println!("CHF: {} ({} decimals)", chf, CHF::DECIMALS);
    println!("AUD: {} ({} decimals)", aud, AUD::DECIMALS);
    println!("NZD: {} ({} decimals)", nzd, NZD::DECIMALS);
    println!();

    // 2. ASIAN CURRENCIES
    println!("2. ASIAN CURRENCIES");
    println!("-------------------");
    let cny = Amount::<CNY>::from_major(720);
    let krw = Amount::<KRW>::from_major(130_000);
    let sgd = Amount::<SGD>::from_major(135);
    let hkd = Amount::<HKD>::from_major(780);
    let twd = Amount::<TWD>::from_major(3100);
    let inr = Amount::<INR>::from_major(8300);

    println!("CNY: {} ({} decimals)", cny, CNY::DECIMALS);
    println!("KRW: {} ({} decimals)", krw, KRW::DECIMALS);
    println!("SGD: {} ({} decimals)", sgd, SGD::DECIMALS);
    println!("HKD: {} ({} decimals)", hkd, HKD::DECIMALS);
    println!("TWD: {} ({} decimals)", twd, TWD::DECIMALS);
    println!("INR: {} ({} decimals)", inr, INR::DECIMALS);
    println!();

    // 3. EUROPEAN CURRENCIES
    println!("3. EUROPEAN CURRENCIES");
    println!("----------------------");
    let eur = Amount::<EUR>::from_major(85);
    let gbp = Amount::<GBP>::from_major(75);
    let sek = Amount::<SEK>::from_major(1050);
    let nok = Amount::<NOK>::from_major(1100);
    let dkk = Amount::<DKK>::from_major(650);
    let pln = Amount::<PLN>::from_major(400);
    let czk = Amount::<CZK>::from_major(2300);
    let huf = Amount::<HUF>::from_major(36_000);

    println!("EUR: {} ({} decimals)", eur, EUR::DECIMALS);
    println!("GBP: {} ({} decimals)", gbp, GBP::DECIMALS);
    println!("SEK: {} ({} decimals)", sek, SEK::DECIMALS);
    println!("NOK: {} ({} decimals)", nok, NOK::DECIMALS);
    println!("DKK: {} ({} decimals)", dkk, DKK::DECIMALS);
    println!("PLN: {} ({} decimals)", pln, PLN::DECIMALS);
    println!("CZK: {} ({} decimals)", czk, CZK::DECIMALS);
    println!("HUF: {} ({} decimals)", huf, HUF::DECIMALS);
    println!();

    // 4. AMERICAN CURRENCIES
    println!("4. AMERICAN CURRENCIES");
    println!("----------------------");
    let brl = Amount::<BRL>::from_major(500);
    let mxn = Amount::<MXN>::from_major(1700);
    let ars = Amount::<ARS>::from_major(85_000);
    let clp = Amount::<CLP>::from_major(90_000);

    println!("BRL: {} ({} decimals)", brl, BRL::DECIMALS);
    println!("MXN: {} ({} decimals)", mxn, MXN::DECIMALS);
    println!("ARS: {} ({} decimals)", ars, ARS::DECIMALS);
    println!("CLP: {} ({} decimals)", clp, CLP::DECIMALS);
    println!();

    // 5. AFRICAN/MIDDLE EASTERN CURRENCIES
    println!("5. AFRICAN/MIDDLE EASTERN CURRENCIES");
    println!("------------------------------------");
    let zar = Amount::<ZAR>::from_major(1800);
    let egp = Amount::<EGP>::from_major(3100);
    let aed = Amount::<AED>::from_major(370);
    let sar = Amount::<SAR>::from_major(375);
    let ils = Amount::<ILS>::from_major(360);
    let try_currency = Amount::<TRY>::from_major(3000);

    println!("ZAR: {} ({} decimals)", zar, ZAR::DECIMALS);
    println!("EGP: {} ({} decimals)", egp, EGP::DECIMALS);
    println!("AED: {} ({} decimals)", aed, AED::DECIMALS);
    println!("SAR: {} ({} decimals)", sar, SAR::DECIMALS);
    println!("ILS: {} ({} decimals)", ils, ILS::DECIMALS);
    println!("TRY: {} ({} decimals)", try_currency, TRY::DECIMALS);
    println!();

    // 6. CRYPTOCURRENCIES
    println!("6. CRYPTOCURRENCIES");
    println!("-------------------");
    let btc = Amount::<BTC>::from_minor(100_000_000); // 1.00000000 BTC
    let eth = Amount::<ETH>::from_minor(1_000_000_000_000_000_000); // 1.000000000000000000 ETH

    println!("BTC: {} ({} decimals)", btc, BTC::DECIMALS);
    println!("ETH: {} ({} decimals)", eth, ETH::DECIMALS);
    println!();

    // 7. CURRENCY CONVERSION EXAMPLES
    println!("7. CURRENCY CONVERSION EXAMPLES");
    println!("-------------------------------");

    // USD to EUR
    let usd_to_eur = Rate::<USD, EUR>::new(0.85)
        .with_timestamp_unix_secs(1_700_000_000)
        .with_source("ECB");
    let eur_converted = usd.convert(&usd_to_eur);
    println!(
        "USD to EUR: {} → {} (rate: {})",
        usd,
        eur_converted,
        usd_to_eur.value()
    );

    // EUR to GBP
    let eur_to_gbp = Rate::<EUR, GBP>::new(0.87);
    let gbp_converted = eur_converted.convert(&eur_to_gbp);
    println!(
        "EUR to GBP: {} → {} (rate: {})",
        eur_converted,
        gbp_converted,
        eur_to_gbp.value()
    );

    // USD to JPY
    let usd_to_jpy = Rate::<USD, JPY>::new(150.0);
    let jpy_converted = usd.convert(&usd_to_jpy);
    println!(
        "USD to JPY: {} → {} (rate: {})",
        usd,
        jpy_converted,
        usd_to_jpy.value()
    );
    println!();

    // 8. ROUNDING EXAMPLES
    println!("8. ROUNDING EXAMPLES");
    println!("--------------------");
    let usd_amount = Amount::<USD>::from_minor(12345); // $123.45
    println!("Original: {}", usd_amount);
    println!("Half Up: {}", usd_amount.round(RoundingMode::HalfUp));
    println!("Half Down: {}", usd_amount.round(RoundingMode::HalfDown));
    println!("Half Even: {}", usd_amount.round(RoundingMode::HalfEven));
    println!("Floor: {}", usd_amount.round(RoundingMode::Floor));
    println!("Ceiling: {}", usd_amount.round(RoundingMode::Ceiling));
    println!();

    // 9. CURRENCY METADATA
    println!("9. CURRENCY METADATA");
    println!("--------------------");
    let currencies = [
        ("USD", USD::CODE, USD::SYMBOL, USD::DECIMALS),
        ("EUR", EUR::CODE, EUR::SYMBOL, EUR::DECIMALS),
        ("JPY", JPY::CODE, JPY::SYMBOL, JPY::DECIMALS),
        ("CNY", CNY::CODE, CNY::SYMBOL, CNY::DECIMALS),
        ("BRL", BRL::CODE, BRL::SYMBOL, BRL::DECIMALS),
        ("AED", AED::CODE, AED::SYMBOL, AED::DECIMALS),
    ];

    for (name, code, symbol, decimals) in currencies {
        println!("{}: {} {} ({} decimals)", name, symbol, code, decimals);
    }
    println!();

    // 10. TYPE SAFETY DEMONSTRATION
    println!("10. TYPE SAFETY DEMONSTRATION");
    println!("-----------------------------");
    println!("✓ USD + USD = Valid");
    println!("✓ EUR + EUR = Valid");
    println!("✓ CAD + CAD = Valid");
    println!("✗ USD + EUR = Compile Error!");
    println!("✗ CAD + JPY = Compile Error!");
    println!("✗ BRL + TRY = Compile Error!");
    println!();

    println!("=== Global Currencies Example Completed! ===");
    println!("Total currencies supported: 30+");
    println!("Regions covered: North America, Europe, Asia, South America, Africa, Middle East");
    println!("Type safety: 100% compile-time currency mixing prevention");
}

examples/custom_currency.rs (line 158)

fn main() {
    println!("=== Custom Currency Examples ===\n");

    // ========================================
    // Using Custom Fiat Currencies
    // ========================================
    println!("1. CUSTOM FIAT CURRENCIES");
    println!("-------------------------");

    let cad = Amount::<CAD>::from_major(100);
    let chf = Amount::<CHF>::from_major(85);
    let aud = Amount::<AUD>::from_major(150);

    println!("Canadian Dollar: {}", cad);
    println!("Swiss Franc:     {}", chf);
    println!("Australian Dollar: {}", aud);

    // Arithmetic works the same
    let total_cad = cad + Amount::<CAD>::from_major(50);
    println!("\nC$100 + C$50 = {}", total_cad);

    // ========================================
    // Currency Properties
    // ========================================
    println!("\n2. CURRENCY PROPERTIES");
    println!("----------------------");

    println!(
        "CAD: code={}, symbol={}, decimals={}",
        CAD::CODE,
        CAD::SYMBOL,
        CAD::DECIMALS
    );
    println!(
        "CHF: code={}, symbol={}, decimals={}",
        CHF::CODE,
        CHF::SYMBOL,
        CHF::DECIMALS
    );
    println!(
        "DOGE: code={}, symbol={}, decimals={}",
        DOGE::CODE,
        DOGE::SYMBOL,
        DOGE::DECIMALS
    );
    println!(
        "GOLD: code={}, symbol={}, decimals={}",
        GOLD::CODE,
        GOLD::SYMBOL,
        GOLD::DECIMALS
    );

    // ========================================
    // Converting Between Custom Currencies
    // ========================================
    println!("\n3. CONVERTING CUSTOM CURRENCIES");
    println!("--------------------------------");

    let _cad_amount = Amount::<CAD>::from_major(100);
    let cad_to_aud = Rate::<CAD, AUD>::new(1.08); // 1 CAD = 1.08 AUD

    println!("Example: C$100 at rate {} CAD→AUD", cad_to_aud.value());

    // ========================================
    // Cryptocurrency Example
    // ========================================
    println!("\n4. CRYPTOCURRENCY (DOGECOIN)");
    println!("-----------------------------");

    // Dogecoin with 8 decimal places (like Bitcoin)
    let doge = Amount::<DOGE>::from_minor(100_000_000); // 1 DOGE
    println!("Amount: {} (1 DOGE)", doge);

    let small_amount = Amount::<DOGE>::from_minor(12_345_678); // 0.12345678 DOGE
    println!("Small amount: {} (0.12345678 DOGE)", small_amount);

    let total = doge + small_amount;
    println!("Total: {}", total);

    // ========================================
    // Video Game Currency
    // ========================================
    println!("\n5. VIDEO GAME CURRENCIES");
    println!("------------------------");

    // Gold coins (no fractional amounts)
    let gold = Amount::<GOLD>::from_major(1000);
    println!("Gold coins: {}", gold);

    let loot = Amount::<GOLD>::from_major(150);
    let total_gold = gold + loot;
    println!(
        "After looting: {} (was {}, found {})",
        total_gold, gold, loot
    );

    // Premium gems (with fractional amounts for bonuses)
    let gems = Amount::<GEMS>::from_major(50);
    println!("\nPremium gems: {}", gems);

    // 10% bonus
    let bonus = (gems * 10) / 100;
    println!("Bonus (10%): {}", bonus);

    let total_gems = gems + bonus;
    println!("Total with bonus: {}", total_gems);

    // ========================================
    // Loyalty Points System
    // ========================================
    println!("\n6. LOYALTY POINTS SYSTEM");
    println!("------------------------");

    let purchase = Amount::<POINTS>::from_major(100);
    println!("Purchase: {}", purchase);

    // Earn 5% back in points
    let earn_rate = 5;
    let points_earned = (purchase * earn_rate) / 100;
    println!("Points earned ({}%): {}", earn_rate, points_earned);

    // Accumulate points
    let existing_points = Amount::<POINTS>::from_major(237);
    let new_balance = existing_points + points_earned;
    println!("\nPrevious balance: {}", existing_points);
    println!("New balance: {}", new_balance);

    // Redeem points
    let redemption = Amount::<POINTS>::from_major(50);
    let final_balance = new_balance - redemption;
    println!("\nAfter redeeming {}: {}", redemption, final_balance);

    // ========================================
    // Exchange Rate Between Custom Currencies
    // ========================================
    println!("\n7. EXCHANGE RATES BETWEEN CUSTOM CURRENCIES");
    println!("--------------------------------------------");

    // Define exchange rates
    let cad_to_aud = Rate::<CAD, AUD>::new(1.08); // 1 CAD = 1.08 AUD

    let cad_amount = Amount::<CAD>::from_major(100);
    println!("Canadian Dollars: {}", cad_amount);
    println!("Exchange rate: 1 CAD = {} AUD", cad_to_aud.value());

    let aud_amount = cad_amount.convert(&cad_to_aud);
    println!("Australian Dollars: {}", aud_amount);

    // ========================================
    // Type Safety Still Works
    // ========================================
    println!("\n8. TYPE SAFETY");
    println!("--------------");

    println!("✓ Can add CAD + CAD");
    println!("✓ Can add GOLD + GOLD");
    println!("✗ Cannot add CAD + CHF (compile error!)");
    println!("✗ Cannot add GOLD + GEMS (compile error!)");
    println!("\nCustom currencies have the same type safety as built-in ones!");

    // These would NOT compile:
    // let invalid = cad + chf;      // Compile error: different currencies
    // let invalid2 = gold + gems;   // Compile error: different currencies

    // ========================================
    // Rounding with Custom Currencies
    // ========================================
    println!("\n9. ROUNDING");
    println!("-----------");

    let cad = Amount::<CAD>::from_major(100) / 3; // C$33.333...
    println!("CAD (exact): {}", cad);
    println!("CAD (rounded): {}", cad.round(RoundingMode::HalfUp));

    let doge = Amount::<DOGE>::from_minor(100_000_000) / 3; // 0.33333333 DOGE
    println!("\nDOGE (exact): {}", doge);
    println!("DOGE (rounded): {}", doge.round(RoundingMode::HalfUp));

    let gold = Amount::<GOLD>::from_major(1000) / 3; // 333.333... coins
    println!("\nGOLD (exact): {}", gold);
    println!(
        "GOLD (rounded): {} (no decimals)",
        gold.round(RoundingMode::HalfUp)
    );

    // ========================================
    // Real-World: Multi-Currency Wallet
    // ========================================
    println!("\n10. REAL-WORLD: MULTI-CURRENCY WALLET");
    println!("--------------------------------------");

    println!("Wallet balances:");
    let cad_balance = Amount::<CAD>::from_major(500);
    let aud_balance = Amount::<AUD>::from_major(300);
    let chf_balance = Amount::<CHF>::from_major(200);

    println!("  CAD: {}", cad_balance);
    println!("  AUD: {}", aud_balance);
    println!("  CHF: {}", chf_balance);

    println!("\nTransaction: Spend C$50");
    let new_cad = cad_balance - Amount::<CAD>::from_major(50);
    println!("  New CAD balance: {}", new_cad);

    println!("\nType system ensures you can't accidentally mix currencies!");

    println!("\n=== All custom currency examples completed! ===");
}

pub fn try_from_decimal(rate: Decimal) -> MoneyResult<Self>

Tries to create a new exchange rate from a Decimal value.

This is useful when you already have a precise decimal rate. Returns an error if the rate is zero or negative.

Examples

use typed_money::{Rate, USD, EUR};
use rust_decimal::Decimal;

let decimal_rate = Decimal::new(85, 2);  // 0.85
let rate = Rate::<USD, EUR>::try_from_decimal(decimal_rate)?;

// Invalid rates return an error
assert!(Rate::<USD, EUR>::try_from_decimal(Decimal::ZERO).is_err());

pub fn from_decimal(rate: Decimal) -> Self

Creates a new exchange rate from a Decimal value.

Panics

Panics if the rate is zero or negative. For a non-panicking version, use try_from_decimal.

Examples

use typed_money::{Rate, USD, EUR};
use rust_decimal::Decimal;

let decimal_rate = Decimal::new(85, 2);  // 0.85
let rate = Rate::<USD, EUR>::from_decimal(decimal_rate);

pub const fn value(&self) -> &Decimal

Returns the exchange rate value.

Examples

use typed_money::{Rate, USD, EUR};

let rate = Rate::<USD, EUR>::new(0.85);
println!("Rate: {}", rate.value());

Examples found in repository

examples/conversions.rs (line 38)

fn main() {
    println!("=== Currency Conversion Examples ===\n");

    // ========================================
    // Basic Conversion
    // ========================================
    println!("1. BASIC CONVERSION");
    println!("-------------------");

    let usd_amount = Amount::<USD>::from_major(100);
    println!("Starting amount: {}", usd_amount);

    // Create an exchange rate: 1 USD = 0.85 EUR
    let usd_to_eur = Rate::<USD, EUR>::new(0.85);
    println!("Exchange rate: 1 USD = 0.85 EUR");

    // Convert
    let eur_amount = usd_amount.convert(&usd_to_eur);
    println!("Converted amount: {}", eur_amount);
    println!("(${} × 0.85 = €{})\n", 100, eur_amount.to_major_floor());

    // ========================================
    // Inverse Rates
    // ========================================
    println!("2. INVERSE RATES");
    println!("----------------");

    let usd_to_eur = Rate::<USD, EUR>::new(0.85);
    println!("USD → EUR rate: {}", usd_to_eur.value());

    // Get the inverse rate automatically
    let eur_to_usd = usd_to_eur.inverse();
    println!("EUR → USD rate (inverse): {}", eur_to_usd.value());
    println!("(1 / 0.85 = ~1.176)\n");

    // Converting back
    let original_usd = Amount::<USD>::from_major(100);
    let eur = original_usd.convert(&usd_to_eur);
    let back_to_usd = eur.convert(&eur_to_usd);

    println!("Original: {}", original_usd);
    println!("To EUR:   {}", eur);
    println!("Back to USD: {}", back_to_usd);
    println!("(Should be approximately the same)\n");

    // ========================================
    // Multiple Conversions
    // ========================================
    println!("3. MULTIPLE CONVERSIONS");
    println!("-----------------------");

    let usd = Amount::<USD>::from_major(1000);
    println!("Starting with: {}", usd);

    // Define multiple rates
    let usd_to_eur = Rate::<USD, EUR>::new(0.85);
    let usd_to_gbp = Rate::<USD, GBP>::new(0.73);
    let usd_to_jpy = Rate::<USD, JPY>::new(110.0);

    println!("\nExchange rates:");
    println!("  1 USD = {} EUR", usd_to_eur.value());
    println!("  1 USD = {} GBP", usd_to_gbp.value());
    println!("  1 USD = {} JPY", usd_to_jpy.value());

    println!("\nConversions:");
    let eur = usd.convert(&usd_to_eur);
    let gbp = usd.convert(&usd_to_gbp);
    let jpy = usd.convert(&usd_to_jpy);

    println!("  {} → {}", usd, eur);
    println!("  {} → {}", usd, gbp);
    println!("  {} → {}", usd, jpy);

    // ========================================
    // Chained Conversions
    // ========================================
    println!("\n4. CHAINED CONVERSIONS");
    println!("----------------------");

    println!("Converting USD → EUR → GBP");

    let usd = Amount::<USD>::from_major(100);
    let usd_to_eur = Rate::<USD, EUR>::new(0.85);
    let eur_to_gbp = Rate::<EUR, GBP>::new(0.86);

    println!("Starting: {}", usd);
    let eur = usd.convert(&usd_to_eur);
    println!("After USD→EUR: {}", eur);
    let gbp = eur.convert(&eur_to_gbp);
    println!("After EUR→GBP: {}", gbp);
    println!("(${} × 0.85 × 0.86 = £{})\n", 100, gbp.to_major_floor());

    // ========================================
    // Rate Metadata for Auditability
    // ========================================
    println!("5. RATE METADATA FOR AUDITABILITY");
    println!("----------------------------------");

    // Create a rate with metadata
    let rate = Rate::<USD, EUR>::new(0.85)
        .with_timestamp_unix_secs(1700000000)
        .with_source("ECB"); // European Central Bank

    println!("Rate: {}", rate.value());
    println!("Timestamp: {:?}", rate.timestamp_unix_secs());
    println!("Source: {:?}", rate.source());

    let amount = Amount::<USD>::from_major(1000);
    let converted = amount.convert(&rate);
    println!(
        "\nConverted {} to {} using rate from {:?}",
        amount,
        converted,
        rate.source().unwrap_or("unknown")
    );

    // ========================================
    // Real-World Example: International Payment
    // ========================================
    println!("\n6. REAL-WORLD EXAMPLE: INTERNATIONAL PAYMENT");
    println!("---------------------------------------------");

    // Customer pays in USD
    let payment_usd = Amount::<USD>::from_major(250);
    println!("Customer payment: {}", payment_usd);

    // Current exchange rate (would come from an API in production)
    let current_rate = Rate::<USD, EUR>::new(0.92)
        .with_timestamp_unix_secs(1700000000)
        .with_source("API");

    // Convert to EUR
    let payment_eur = payment_usd.convert(&current_rate);
    println!("Converted to EUR: {}", payment_eur);

    // Calculate fees
    let fee_percentage = 3; // 3% transaction fee
    let fee = (payment_eur * fee_percentage) / 100;
    println!("Transaction fee ({}%): {}", fee_percentage, fee);

    let final_amount = payment_eur - fee;
    println!("Final amount to recipient: {}", final_amount);

    println!("\nTransaction summary:");
    println!("  Original: {}", payment_usd);
    println!(
        "  Rate: {} (from {:?})",
        current_rate.value(),
        current_rate.source().unwrap_or("N/A")
    );
    println!("  Converted: {}", payment_eur);
    println!("  Fee: -{}", fee);
    println!("  Final: {}", final_amount);

    // ========================================
    // Type Safety with Conversions
    // ========================================
    println!("\n7. TYPE SAFETY");
    println!("--------------");

    println!("✓ Can only convert with matching rate types");
    println!("✓ USD amount requires Rate<USD, X>");
    println!("✗ Cannot use Rate<EUR, GBP> on USD amount (compile error!)");
    println!("\nThe type system ensures you always use the correct exchange rate!");

    // This would NOT compile:
    // let usd = Amount::<USD>::from_major(100);
    // let wrong_rate = Rate::<EUR, GBP>::new(0.86);
    // let invalid = usd.convert(&wrong_rate);  // Compile error!

    println!("\n=== All conversion examples completed! ===");
}

examples/global_currencies.rs (line 165)

fn main() {
    println!("=== Typed Money - Global Currencies Example ===\n");

    // 1. MAJOR FIAT CURRENCIES
    println!("1. MAJOR FIAT CURRENCIES");
    println!("------------------------");
    let usd = Amount::<USD>::from_major(100);
    let cad = Amount::<CAD>::from_major(135);
    let chf = Amount::<CHF>::from_major(90);
    let aud = Amount::<AUD>::from_major(150);
    let nzd = Amount::<NZD>::from_major(160);

    println!("USD: {} ({} decimals)", usd, USD::DECIMALS);
    println!("CAD: {} ({} decimals)", cad, CAD::DECIMALS);
    println!("CHF: {} ({} decimals)", chf, CHF::DECIMALS);
    println!("AUD: {} ({} decimals)", aud, AUD::DECIMALS);
    println!("NZD: {} ({} decimals)", nzd, NZD::DECIMALS);
    println!();

    // 2. ASIAN CURRENCIES
    println!("2. ASIAN CURRENCIES");
    println!("-------------------");
    let cny = Amount::<CNY>::from_major(720);
    let krw = Amount::<KRW>::from_major(130_000);
    let sgd = Amount::<SGD>::from_major(135);
    let hkd = Amount::<HKD>::from_major(780);
    let twd = Amount::<TWD>::from_major(3100);
    let inr = Amount::<INR>::from_major(8300);

    println!("CNY: {} ({} decimals)", cny, CNY::DECIMALS);
    println!("KRW: {} ({} decimals)", krw, KRW::DECIMALS);
    println!("SGD: {} ({} decimals)", sgd, SGD::DECIMALS);
    println!("HKD: {} ({} decimals)", hkd, HKD::DECIMALS);
    println!("TWD: {} ({} decimals)", twd, TWD::DECIMALS);
    println!("INR: {} ({} decimals)", inr, INR::DECIMALS);
    println!();

    // 3. EUROPEAN CURRENCIES
    println!("3. EUROPEAN CURRENCIES");
    println!("----------------------");
    let eur = Amount::<EUR>::from_major(85);
    let gbp = Amount::<GBP>::from_major(75);
    let sek = Amount::<SEK>::from_major(1050);
    let nok = Amount::<NOK>::from_major(1100);
    let dkk = Amount::<DKK>::from_major(650);
    let pln = Amount::<PLN>::from_major(400);
    let czk = Amount::<CZK>::from_major(2300);
    let huf = Amount::<HUF>::from_major(36_000);

    println!("EUR: {} ({} decimals)", eur, EUR::DECIMALS);
    println!("GBP: {} ({} decimals)", gbp, GBP::DECIMALS);
    println!("SEK: {} ({} decimals)", sek, SEK::DECIMALS);
    println!("NOK: {} ({} decimals)", nok, NOK::DECIMALS);
    println!("DKK: {} ({} decimals)", dkk, DKK::DECIMALS);
    println!("PLN: {} ({} decimals)", pln, PLN::DECIMALS);
    println!("CZK: {} ({} decimals)", czk, CZK::DECIMALS);
    println!("HUF: {} ({} decimals)", huf, HUF::DECIMALS);
    println!();

    // 4. AMERICAN CURRENCIES
    println!("4. AMERICAN CURRENCIES");
    println!("----------------------");
    let brl = Amount::<BRL>::from_major(500);
    let mxn = Amount::<MXN>::from_major(1700);
    let ars = Amount::<ARS>::from_major(85_000);
    let clp = Amount::<CLP>::from_major(90_000);

    println!("BRL: {} ({} decimals)", brl, BRL::DECIMALS);
    println!("MXN: {} ({} decimals)", mxn, MXN::DECIMALS);
    println!("ARS: {} ({} decimals)", ars, ARS::DECIMALS);
    println!("CLP: {} ({} decimals)", clp, CLP::DECIMALS);
    println!();

    // 5. AFRICAN/MIDDLE EASTERN CURRENCIES
    println!("5. AFRICAN/MIDDLE EASTERN CURRENCIES");
    println!("------------------------------------");
    let zar = Amount::<ZAR>::from_major(1800);
    let egp = Amount::<EGP>::from_major(3100);
    let aed = Amount::<AED>::from_major(370);
    let sar = Amount::<SAR>::from_major(375);
    let ils = Amount::<ILS>::from_major(360);
    let try_currency = Amount::<TRY>::from_major(3000);

    println!("ZAR: {} ({} decimals)", zar, ZAR::DECIMALS);
    println!("EGP: {} ({} decimals)", egp, EGP::DECIMALS);
    println!("AED: {} ({} decimals)", aed, AED::DECIMALS);
    println!("SAR: {} ({} decimals)", sar, SAR::DECIMALS);
    println!("ILS: {} ({} decimals)", ils, ILS::DECIMALS);
    println!("TRY: {} ({} decimals)", try_currency, TRY::DECIMALS);
    println!();

    // 6. CRYPTOCURRENCIES
    println!("6. CRYPTOCURRENCIES");
    println!("-------------------");
    let btc = Amount::<BTC>::from_minor(100_000_000); // 1.00000000 BTC
    let eth = Amount::<ETH>::from_minor(1_000_000_000_000_000_000); // 1.000000000000000000 ETH

    println!("BTC: {} ({} decimals)", btc, BTC::DECIMALS);
    println!("ETH: {} ({} decimals)", eth, ETH::DECIMALS);
    println!();

    // 7. CURRENCY CONVERSION EXAMPLES
    println!("7. CURRENCY CONVERSION EXAMPLES");
    println!("-------------------------------");

    // USD to EUR
    let usd_to_eur = Rate::<USD, EUR>::new(0.85)
        .with_timestamp_unix_secs(1_700_000_000)
        .with_source("ECB");
    let eur_converted = usd.convert(&usd_to_eur);
    println!(
        "USD to EUR: {} → {} (rate: {})",
        usd,
        eur_converted,
        usd_to_eur.value()
    );

    // EUR to GBP
    let eur_to_gbp = Rate::<EUR, GBP>::new(0.87);
    let gbp_converted = eur_converted.convert(&eur_to_gbp);
    println!(
        "EUR to GBP: {} → {} (rate: {})",
        eur_converted,
        gbp_converted,
        eur_to_gbp.value()
    );

    // USD to JPY
    let usd_to_jpy = Rate::<USD, JPY>::new(150.0);
    let jpy_converted = usd.convert(&usd_to_jpy);
    println!(
        "USD to JPY: {} → {} (rate: {})",
        usd,
        jpy_converted,
        usd_to_jpy.value()
    );
    println!();

    // 8. ROUNDING EXAMPLES
    println!("8. ROUNDING EXAMPLES");
    println!("--------------------");
    let usd_amount = Amount::<USD>::from_minor(12345); // $123.45
    println!("Original: {}", usd_amount);
    println!("Half Up: {}", usd_amount.round(RoundingMode::HalfUp));
    println!("Half Down: {}", usd_amount.round(RoundingMode::HalfDown));
    println!("Half Even: {}", usd_amount.round(RoundingMode::HalfEven));
    println!("Floor: {}", usd_amount.round(RoundingMode::Floor));
    println!("Ceiling: {}", usd_amount.round(RoundingMode::Ceiling));
    println!();

    // 9. CURRENCY METADATA
    println!("9. CURRENCY METADATA");
    println!("--------------------");
    let currencies = [
        ("USD", USD::CODE, USD::SYMBOL, USD::DECIMALS),
        ("EUR", EUR::CODE, EUR::SYMBOL, EUR::DECIMALS),
        ("JPY", JPY::CODE, JPY::SYMBOL, JPY::DECIMALS),
        ("CNY", CNY::CODE, CNY::SYMBOL, CNY::DECIMALS),
        ("BRL", BRL::CODE, BRL::SYMBOL, BRL::DECIMALS),
        ("AED", AED::CODE, AED::SYMBOL, AED::DECIMALS),
    ];

    for (name, code, symbol, decimals) in currencies {
        println!("{}: {} {} ({} decimals)", name, symbol, code, decimals);
    }
    println!();

    // 10. TYPE SAFETY DEMONSTRATION
    println!("10. TYPE SAFETY DEMONSTRATION");
    println!("-----------------------------");
    println!("✓ USD + USD = Valid");
    println!("✓ EUR + EUR = Valid");
    println!("✓ CAD + CAD = Valid");
    println!("✗ USD + EUR = Compile Error!");
    println!("✗ CAD + JPY = Compile Error!");
    println!("✗ BRL + TRY = Compile Error!");
    println!();

    println!("=== Global Currencies Example Completed! ===");
    println!("Total currencies supported: 30+");
    println!("Regions covered: North America, Europe, Asia, South America, Africa, Middle East");
    println!("Type safety: 100% compile-time currency mixing prevention");
}

examples/custom_currency.rs (line 160)

fn main() {
    println!("=== Custom Currency Examples ===\n");

    // ========================================
    // Using Custom Fiat Currencies
    // ========================================
    println!("1. CUSTOM FIAT CURRENCIES");
    println!("-------------------------");

    let cad = Amount::<CAD>::from_major(100);
    let chf = Amount::<CHF>::from_major(85);
    let aud = Amount::<AUD>::from_major(150);

    println!("Canadian Dollar: {}", cad);
    println!("Swiss Franc:     {}", chf);
    println!("Australian Dollar: {}", aud);

    // Arithmetic works the same
    let total_cad = cad + Amount::<CAD>::from_major(50);
    println!("\nC$100 + C$50 = {}", total_cad);

    // ========================================
    // Currency Properties
    // ========================================
    println!("\n2. CURRENCY PROPERTIES");
    println!("----------------------");

    println!(
        "CAD: code={}, symbol={}, decimals={}",
        CAD::CODE,
        CAD::SYMBOL,
        CAD::DECIMALS
    );
    println!(
        "CHF: code={}, symbol={}, decimals={}",
        CHF::CODE,
        CHF::SYMBOL,
        CHF::DECIMALS
    );
    println!(
        "DOGE: code={}, symbol={}, decimals={}",
        DOGE::CODE,
        DOGE::SYMBOL,
        DOGE::DECIMALS
    );
    println!(
        "GOLD: code={}, symbol={}, decimals={}",
        GOLD::CODE,
        GOLD::SYMBOL,
        GOLD::DECIMALS
    );

    // ========================================
    // Converting Between Custom Currencies
    // ========================================
    println!("\n3. CONVERTING CUSTOM CURRENCIES");
    println!("--------------------------------");

    let _cad_amount = Amount::<CAD>::from_major(100);
    let cad_to_aud = Rate::<CAD, AUD>::new(1.08); // 1 CAD = 1.08 AUD

    println!("Example: C$100 at rate {} CAD→AUD", cad_to_aud.value());

    // ========================================
    // Cryptocurrency Example
    // ========================================
    println!("\n4. CRYPTOCURRENCY (DOGECOIN)");
    println!("-----------------------------");

    // Dogecoin with 8 decimal places (like Bitcoin)
    let doge = Amount::<DOGE>::from_minor(100_000_000); // 1 DOGE
    println!("Amount: {} (1 DOGE)", doge);

    let small_amount = Amount::<DOGE>::from_minor(12_345_678); // 0.12345678 DOGE
    println!("Small amount: {} (0.12345678 DOGE)", small_amount);

    let total = doge + small_amount;
    println!("Total: {}", total);

    // ========================================
    // Video Game Currency
    // ========================================
    println!("\n5. VIDEO GAME CURRENCIES");
    println!("------------------------");

    // Gold coins (no fractional amounts)
    let gold = Amount::<GOLD>::from_major(1000);
    println!("Gold coins: {}", gold);

    let loot = Amount::<GOLD>::from_major(150);
    let total_gold = gold + loot;
    println!(
        "After looting: {} (was {}, found {})",
        total_gold, gold, loot
    );

    // Premium gems (with fractional amounts for bonuses)
    let gems = Amount::<GEMS>::from_major(50);
    println!("\nPremium gems: {}", gems);

    // 10% bonus
    let bonus = (gems * 10) / 100;
    println!("Bonus (10%): {}", bonus);

    let total_gems = gems + bonus;
    println!("Total with bonus: {}", total_gems);

    // ========================================
    // Loyalty Points System
    // ========================================
    println!("\n6. LOYALTY POINTS SYSTEM");
    println!("------------------------");

    let purchase = Amount::<POINTS>::from_major(100);
    println!("Purchase: {}", purchase);

    // Earn 5% back in points
    let earn_rate = 5;
    let points_earned = (purchase * earn_rate) / 100;
    println!("Points earned ({}%): {}", earn_rate, points_earned);

    // Accumulate points
    let existing_points = Amount::<POINTS>::from_major(237);
    let new_balance = existing_points + points_earned;
    println!("\nPrevious balance: {}", existing_points);
    println!("New balance: {}", new_balance);

    // Redeem points
    let redemption = Amount::<POINTS>::from_major(50);
    let final_balance = new_balance - redemption;
    println!("\nAfter redeeming {}: {}", redemption, final_balance);

    // ========================================
    // Exchange Rate Between Custom Currencies
    // ========================================
    println!("\n7. EXCHANGE RATES BETWEEN CUSTOM CURRENCIES");
    println!("--------------------------------------------");

    // Define exchange rates
    let cad_to_aud = Rate::<CAD, AUD>::new(1.08); // 1 CAD = 1.08 AUD

    let cad_amount = Amount::<CAD>::from_major(100);
    println!("Canadian Dollars: {}", cad_amount);
    println!("Exchange rate: 1 CAD = {} AUD", cad_to_aud.value());

    let aud_amount = cad_amount.convert(&cad_to_aud);
    println!("Australian Dollars: {}", aud_amount);

    // ========================================
    // Type Safety Still Works
    // ========================================
    println!("\n8. TYPE SAFETY");
    println!("--------------");

    println!("✓ Can add CAD + CAD");
    println!("✓ Can add GOLD + GOLD");
    println!("✗ Cannot add CAD + CHF (compile error!)");
    println!("✗ Cannot add GOLD + GEMS (compile error!)");
    println!("\nCustom currencies have the same type safety as built-in ones!");

    // These would NOT compile:
    // let invalid = cad + chf;      // Compile error: different currencies
    // let invalid2 = gold + gems;   // Compile error: different currencies

    // ========================================
    // Rounding with Custom Currencies
    // ========================================
    println!("\n9. ROUNDING");
    println!("-----------");

    let cad = Amount::<CAD>::from_major(100) / 3; // C$33.333...
    println!("CAD (exact): {}", cad);
    println!("CAD (rounded): {}", cad.round(RoundingMode::HalfUp));

    let doge = Amount::<DOGE>::from_minor(100_000_000) / 3; // 0.33333333 DOGE
    println!("\nDOGE (exact): {}", doge);
    println!("DOGE (rounded): {}", doge.round(RoundingMode::HalfUp));

    let gold = Amount::<GOLD>::from_major(1000) / 3; // 333.333... coins
    println!("\nGOLD (exact): {}", gold);
    println!(
        "GOLD (rounded): {} (no decimals)",
        gold.round(RoundingMode::HalfUp)
    );

    // ========================================
    // Real-World: Multi-Currency Wallet
    // ========================================
    println!("\n10. REAL-WORLD: MULTI-CURRENCY WALLET");
    println!("--------------------------------------");

    println!("Wallet balances:");
    let cad_balance = Amount::<CAD>::from_major(500);
    let aud_balance = Amount::<AUD>::from_major(300);
    let chf_balance = Amount::<CHF>::from_major(200);

    println!("  CAD: {}", cad_balance);
    println!("  AUD: {}", aud_balance);
    println!("  CHF: {}", chf_balance);

    println!("\nTransaction: Spend C$50");
    let new_cad = cad_balance - Amount::<CAD>::from_major(50);
    println!("  New CAD balance: {}", new_cad);

    println!("\nType system ensures you can't accidentally mix currencies!");

    println!("\n=== All custom currency examples completed! ===");
}

examples/error_handling.rs (line 82)

fn main() {
    println!("=== Error Handling Examples ===\n");

    // ========================================
    // Parse Errors
    // ========================================
    println!("1. PARSING ERRORS");
    println!("-----------------");

    // Valid parsing
    match Amount::<USD>::from_str("123.45") {
        Ok(amount) => println!("✓ Parsed: {}", amount),
        Err(e) => println!("✗ Error: {}", e),
    }

    // Invalid formats
    let invalid_inputs = vec!["invalid", "12.34.56", "abc123", "", "  "];

    println!("\nInvalid inputs:");
    for input in invalid_inputs {
        match Amount::<USD>::from_str(input) {
            Ok(amount) => println!("  '{}' → {}", input, amount),
            Err(MoneyError::ParseError { input: inp, .. }) => {
                println!("  '{}' → Parse error (input: '{}')", input, inp);
            }
            Err(e) => println!("  '{}' → Error: {}", input, e),
        }
    }

    // ========================================
    // Precision Errors
    // ========================================
    println!("\n2. PRECISION ERRORS");
    println!("-------------------");

    // Division creates excess precision
    let amount = Amount::<USD>::from_major(10) / 3; // $3.333...
    println!("After division: {}", amount);
    println!("Decimal places: {}", amount.precision());
    println!("Currency expects: {}", Amount::<USD>::currency_precision());

    // Check for precision issues
    match amount.check_precision() {
        Ok(()) => println!("✓ Precision OK"),
        Err(MoneyError::PrecisionError {
            expected,
            actual,
            suggestion,
            ..
        }) => {
            println!("✗ Precision error:");
            println!("  Expected: {} decimals", expected);
            println!("  Actual: {} decimals", actual);
            println!("  Suggestion: {}", suggestion);

            // Recover by normalizing
            let normalized = amount.normalize();
            println!("\n✓ After normalizing: {}", normalized);
            println!("  Precision OK: {}", normalized.check_precision().is_ok());
        }
        Err(e) => println!("✗ Unexpected error: {}", e),
    }

    // ========================================
    // Invalid Rate Errors
    // ========================================
    println!("\n3. INVALID RATE ERRORS");
    println!("----------------------");

    // Valid rate
    match Rate::<USD, EUR>::try_new(0.85) {
        Ok(rate) => println!("✓ Valid rate: {}", rate.value()),
        Err(e) => println!("✗ Error: {}", e),
    }

    // Invalid rates
    let invalid_rates = vec![
        ("negative", -1.0),
        ("zero", 0.0),
        ("NaN", f64::NAN),
        ("infinity", f64::INFINITY),
    ];

    println!("\nInvalid rates:");
    for (desc, value) in invalid_rates {
        match Rate::<USD, EUR>::try_new(value) {
            Ok(rate) => println!(
                "  {} ({}) → Unexpected success: {}",
                desc,
                value,
                rate.value()
            ),
            Err(MoneyError::InvalidRate { reason, .. }) => {
                println!("  {} ({}) → {}", desc, value, reason);
            }
            Err(e) => println!("  {} ({}) → Error: {}", desc, value, e),
        }
    }

    // ========================================
    // Error Suggestions
    // ========================================
    println!("\n4. ERROR RECOVERY SUGGESTIONS");
    println!("------------------------------");

    let errors = vec![
        MoneyError::PrecisionError {
            currency: "USD",
            expected: 2,
            actual: 5,
            suggestion: "Use normalize() or round() to adjust precision".to_string(),
        },
        MoneyError::InvalidRate {
            value: "-1.0".to_string(),
            reason: "Rate must be positive".to_string(),
        },
        MoneyError::ParseError {
            input: "abc".to_string(),
            expected_currency: Some("USD"),
            reason: "Invalid number format".to_string(),
        },
    ];

    for error in errors {
        println!("\nError: {}", error);
        println!("Suggestion: {}", error.suggestion());
        if let Some(currency) = error.currency() {
            println!("Currency: {}", currency);
        }
    }

    // ========================================
    // Safe Division
    // ========================================
    println!("\n5. SAFE DIVISION");
    println!("----------------");

    let amount = Amount::<USD>::from_major(100);

    // Division by zero is handled
    let divisor = 0;
    println!("Dividing {} by {}...", amount, divisor);

    if divisor == 0 {
        println!("✗ Cannot divide by zero!");
        println!("  Handled before attempting division");
    } else {
        let result = amount / divisor;
        println!("✓ Result: {}", result);
    }

    // Safe division with non-zero
    let safe_divisor = 3;
    let result = amount / safe_divisor;
    println!("\nDividing {} by {}: {}", amount, safe_divisor, result);

    // ========================================
    // Pattern Matching on Errors
    // ========================================
    println!("\n6. PATTERN MATCHING");
    println!("-------------------");

    fn parse_and_handle(input: &str) -> MoneyResult<Amount<USD>> {
        Amount::<USD>::from_str(input)
    }

    let inputs = vec!["123.45", "invalid", "999.99"];

    for input in inputs {
        print!("Parsing '{}': ", input);

        match parse_and_handle(input) {
            Ok(amount) => {
                println!("✓ Success: {}", amount);
            }
            Err(MoneyError::ParseError { input, reason, .. }) => {
                println!("✗ Parse error");
                println!("  Input: '{}'", input);
                println!("  Reason: {}", reason);
            }
            Err(e) => {
                println!("✗ Other error: {}", e);
            }
        }
    }

    // ========================================
    // Error Propagation with ?
    // ========================================
    println!("\n7. ERROR PROPAGATION");
    println!("--------------------");

    fn calculate_total(price_str: &str, quantity: i64) -> MoneyResult<Amount<USD>> {
        let price = Amount::<USD>::from_str(price_str)?;
        let total = price * quantity;
        total.check_precision()?;
        Ok(total)
    }

    match calculate_total("29.99", 3) {
        Ok(total) => println!("✓ Total: {}", total),
        Err(e) => println!("✗ Error: {}", e),
    }

    match calculate_total("invalid", 3) {
        Ok(total) => println!("✓ Total: {}", total),
        Err(e) => println!("✗ Error: {}", e),
    }

    // ========================================
    // Recovering from Errors
    // ========================================
    println!("\n8. ERROR RECOVERY");
    println!("-----------------");

    fn parse_with_fallback(input: &str, fallback: Amount<USD>) -> Amount<USD> {
        Amount::<USD>::from_str(input).unwrap_or(fallback)
    }

    let fallback = Amount::<USD>::from_major(0);

    let inputs = vec!["123.45", "invalid", "67.89"];
    for input in inputs {
        let amount = parse_with_fallback(input, fallback);
        println!("'{}' → {}", input, amount);
    }

    // ========================================
    // Validation Before Operations
    // ========================================
    println!("\n9. VALIDATION");
    println!("-------------");

    fn safe_divide(amount: Amount<USD>, divisor: i64) -> MoneyResult<Amount<USD>> {
        if divisor == 0 {
            return Err(MoneyError::InvalidAmount {
                currency: Some("USD"),
                reason: "Cannot divide by zero".to_string(),
            });
        }

        let result = amount / divisor;

        // Check precision after division
        result.check_precision()?;

        Ok(result)
    }

    let amount = Amount::<USD>::from_major(100);

    match safe_divide(amount, 0) {
        Ok(result) => println!("  Division by 0: {}", result),
        Err(e) => println!("  Division by 0: Error - {}", e),
    }

    match safe_divide(amount, 3) {
        Ok(result) => println!("  Division by 3: {}", result),
        Err(e) => println!("  Division by 3: Error - {}", e),
    }

    // ========================================
    // Real-World: Parsing User Input
    // ========================================
    println!("\n10. REAL-WORLD: PARSING USER INPUT");
    println!("-----------------------------------");

    fn process_payment(amount_str: &str) -> MoneyResult<String> {
        // Parse the amount
        let amount = Amount::<USD>::from_str(amount_str)?;

        // Validate it's positive
        if amount.to_minor() <= 0 {
            return Err(MoneyError::InvalidAmount {
                currency: Some("USD"),
                reason: "Payment amount must be positive".to_string(),
            });
        }

        // Process the payment
        let fee = (amount * 3) / 100; // 3% fee
        let total = amount + fee;

        Ok(format!(
            "Payment: {}, Fee: {}, Total: {}",
            amount, fee, total
        ))
    }

    let test_inputs = vec!["100.00", "0", "-50", "abc", "250.50"];

    for input in test_inputs {
        println!("\nProcessing payment: '{}'", input);
        match process_payment(input) {
            Ok(summary) => println!("  ✓ {}", summary),
            Err(e) => {
                println!("  ✗ Error: {}", e);
                let suggestion = e.suggestion();
                println!("    Hint: {}", suggestion);
            }
        }
    }

    // ========================================
    // Rounding to Fix Precision
    // ========================================
    println!("\n11. FIXING PRECISION WITH ROUNDING");
    println!("-----------------------------------");

    let amount = Amount::<USD>::from_major(10) / 3; // Creates excess precision

    println!("Original: {}", amount);
    println!(
        "Precision check: {}",
        if amount.check_precision().is_ok() {
            "✓ OK"
        } else {
            "✗ Excess precision"
        }
    );

    // Fix with rounding
    let rounded = amount.round(RoundingMode::HalfUp);
    println!("\nRounded: {}", rounded);
    println!(
        "Precision check: {}",
        if rounded.check_precision().is_ok() {
            "✓ OK"
        } else {
            "✗ Excess precision"
        }
    );

    // Or normalize (uses banker's rounding)
    let normalized = amount.normalize();
    println!("\nNormalized: {}", normalized);
    println!(
        "Precision check: {}",
        if normalized.check_precision().is_ok() {
            "✓ OK"
        } else {
            "✗ Excess precision"
        }
    );

    println!("\n=== All error handling examples completed! ===");
}

pub const fn timestamp_unix_secs(&self) -> Option<u64>

Returns the optional UNIX timestamp (seconds) metadata.

Examples found in repository

examples/conversions.rs (line 114)

fn main() {
    println!("=== Currency Conversion Examples ===\n");

    // ========================================
    // Basic Conversion
    // ========================================
    println!("1. BASIC CONVERSION");
    println!("-------------------");

    let usd_amount = Amount::<USD>::from_major(100);
    println!("Starting amount: {}", usd_amount);

    // Create an exchange rate: 1 USD = 0.85 EUR
    let usd_to_eur = Rate::<USD, EUR>::new(0.85);
    println!("Exchange rate: 1 USD = 0.85 EUR");

    // Convert
    let eur_amount = usd_amount.convert(&usd_to_eur);
    println!("Converted amount: {}", eur_amount);
    println!("(${} × 0.85 = €{})\n", 100, eur_amount.to_major_floor());

    // ========================================
    // Inverse Rates
    // ========================================
    println!("2. INVERSE RATES");
    println!("----------------");

    let usd_to_eur = Rate::<USD, EUR>::new(0.85);
    println!("USD → EUR rate: {}", usd_to_eur.value());

    // Get the inverse rate automatically
    let eur_to_usd = usd_to_eur.inverse();
    println!("EUR → USD rate (inverse): {}", eur_to_usd.value());
    println!("(1 / 0.85 = ~1.176)\n");

    // Converting back
    let original_usd = Amount::<USD>::from_major(100);
    let eur = original_usd.convert(&usd_to_eur);
    let back_to_usd = eur.convert(&eur_to_usd);

    println!("Original: {}", original_usd);
    println!("To EUR:   {}", eur);
    println!("Back to USD: {}", back_to_usd);
    println!("(Should be approximately the same)\n");

    // ========================================
    // Multiple Conversions
    // ========================================
    println!("3. MULTIPLE CONVERSIONS");
    println!("-----------------------");

    let usd = Amount::<USD>::from_major(1000);
    println!("Starting with: {}", usd);

    // Define multiple rates
    let usd_to_eur = Rate::<USD, EUR>::new(0.85);
    let usd_to_gbp = Rate::<USD, GBP>::new(0.73);
    let usd_to_jpy = Rate::<USD, JPY>::new(110.0);

    println!("\nExchange rates:");
    println!("  1 USD = {} EUR", usd_to_eur.value());
    println!("  1 USD = {} GBP", usd_to_gbp.value());
    println!("  1 USD = {} JPY", usd_to_jpy.value());

    println!("\nConversions:");
    let eur = usd.convert(&usd_to_eur);
    let gbp = usd.convert(&usd_to_gbp);
    let jpy = usd.convert(&usd_to_jpy);

    println!("  {} → {}", usd, eur);
    println!("  {} → {}", usd, gbp);
    println!("  {} → {}", usd, jpy);

    // ========================================
    // Chained Conversions
    // ========================================
    println!("\n4. CHAINED CONVERSIONS");
    println!("----------------------");

    println!("Converting USD → EUR → GBP");

    let usd = Amount::<USD>::from_major(100);
    let usd_to_eur = Rate::<USD, EUR>::new(0.85);
    let eur_to_gbp = Rate::<EUR, GBP>::new(0.86);

    println!("Starting: {}", usd);
    let eur = usd.convert(&usd_to_eur);
    println!("After USD→EUR: {}", eur);
    let gbp = eur.convert(&eur_to_gbp);
    println!("After EUR→GBP: {}", gbp);
    println!("(${} × 0.85 × 0.86 = £{})\n", 100, gbp.to_major_floor());

    // ========================================
    // Rate Metadata for Auditability
    // ========================================
    println!("5. RATE METADATA FOR AUDITABILITY");
    println!("----------------------------------");

    // Create a rate with metadata
    let rate = Rate::<USD, EUR>::new(0.85)
        .with_timestamp_unix_secs(1700000000)
        .with_source("ECB"); // European Central Bank

    println!("Rate: {}", rate.value());
    println!("Timestamp: {:?}", rate.timestamp_unix_secs());
    println!("Source: {:?}", rate.source());

    let amount = Amount::<USD>::from_major(1000);
    let converted = amount.convert(&rate);
    println!(
        "\nConverted {} to {} using rate from {:?}",
        amount,
        converted,
        rate.source().unwrap_or("unknown")
    );

    // ========================================
    // Real-World Example: International Payment
    // ========================================
    println!("\n6. REAL-WORLD EXAMPLE: INTERNATIONAL PAYMENT");
    println!("---------------------------------------------");

    // Customer pays in USD
    let payment_usd = Amount::<USD>::from_major(250);
    println!("Customer payment: {}", payment_usd);

    // Current exchange rate (would come from an API in production)
    let current_rate = Rate::<USD, EUR>::new(0.92)
        .with_timestamp_unix_secs(1700000000)
        .with_source("API");

    // Convert to EUR
    let payment_eur = payment_usd.convert(&current_rate);
    println!("Converted to EUR: {}", payment_eur);

    // Calculate fees
    let fee_percentage = 3; // 3% transaction fee
    let fee = (payment_eur * fee_percentage) / 100;
    println!("Transaction fee ({}%): {}", fee_percentage, fee);

    let final_amount = payment_eur - fee;
    println!("Final amount to recipient: {}", final_amount);

    println!("\nTransaction summary:");
    println!("  Original: {}", payment_usd);
    println!(
        "  Rate: {} (from {:?})",
        current_rate.value(),
        current_rate.source().unwrap_or("N/A")
    );
    println!("  Converted: {}", payment_eur);
    println!("  Fee: -{}", fee);
    println!("  Final: {}", final_amount);

    // ========================================
    // Type Safety with Conversions
    // ========================================
    println!("\n7. TYPE SAFETY");
    println!("--------------");

    println!("✓ Can only convert with matching rate types");
    println!("✓ USD amount requires Rate<USD, X>");
    println!("✗ Cannot use Rate<EUR, GBP> on USD amount (compile error!)");
    println!("\nThe type system ensures you always use the correct exchange rate!");

    // This would NOT compile:
    // let usd = Amount::<USD>::from_major(100);
    // let wrong_rate = Rate::<EUR, GBP>::new(0.86);
    // let invalid = usd.convert(&wrong_rate);  // Compile error!

    println!("\n=== All conversion examples completed! ===");
}

pub const fn source(&self) -> Option<&'static str>

Returns the optional static source identifier metadata.

Examples found in repository

examples/conversions.rs (line 115)

fn main() {
    println!("=== Currency Conversion Examples ===\n");

    // ========================================
    // Basic Conversion
    // ========================================
    println!("1. BASIC CONVERSION");
    println!("-------------------");

    let usd_amount = Amount::<USD>::from_major(100);
    println!("Starting amount: {}", usd_amount);

    // Create an exchange rate: 1 USD = 0.85 EUR
    let usd_to_eur = Rate::<USD, EUR>::new(0.85);
    println!("Exchange rate: 1 USD = 0.85 EUR");

    // Convert
    let eur_amount = usd_amount.convert(&usd_to_eur);
    println!("Converted amount: {}", eur_amount);
    println!("(${} × 0.85 = €{})\n", 100, eur_amount.to_major_floor());

    // ========================================
    // Inverse Rates
    // ========================================
    println!("2. INVERSE RATES");
    println!("----------------");

    let usd_to_eur = Rate::<USD, EUR>::new(0.85);
    println!("USD → EUR rate: {}", usd_to_eur.value());

    // Get the inverse rate automatically
    let eur_to_usd = usd_to_eur.inverse();
    println!("EUR → USD rate (inverse): {}", eur_to_usd.value());
    println!("(1 / 0.85 = ~1.176)\n");

    // Converting back
    let original_usd = Amount::<USD>::from_major(100);
    let eur = original_usd.convert(&usd_to_eur);
    let back_to_usd = eur.convert(&eur_to_usd);

    println!("Original: {}", original_usd);
    println!("To EUR:   {}", eur);
    println!("Back to USD: {}", back_to_usd);
    println!("(Should be approximately the same)\n");

    // ========================================
    // Multiple Conversions
    // ========================================
    println!("3. MULTIPLE CONVERSIONS");
    println!("-----------------------");

    let usd = Amount::<USD>::from_major(1000);
    println!("Starting with: {}", usd);

    // Define multiple rates
    let usd_to_eur = Rate::<USD, EUR>::new(0.85);
    let usd_to_gbp = Rate::<USD, GBP>::new(0.73);
    let usd_to_jpy = Rate::<USD, JPY>::new(110.0);

    println!("\nExchange rates:");
    println!("  1 USD = {} EUR", usd_to_eur.value());
    println!("  1 USD = {} GBP", usd_to_gbp.value());
    println!("  1 USD = {} JPY", usd_to_jpy.value());

    println!("\nConversions:");
    let eur = usd.convert(&usd_to_eur);
    let gbp = usd.convert(&usd_to_gbp);
    let jpy = usd.convert(&usd_to_jpy);

    println!("  {} → {}", usd, eur);
    println!("  {} → {}", usd, gbp);
    println!("  {} → {}", usd, jpy);

    // ========================================
    // Chained Conversions
    // ========================================
    println!("\n4. CHAINED CONVERSIONS");
    println!("----------------------");

    println!("Converting USD → EUR → GBP");

    let usd = Amount::<USD>::from_major(100);
    let usd_to_eur = Rate::<USD, EUR>::new(0.85);
    let eur_to_gbp = Rate::<EUR, GBP>::new(0.86);

    println!("Starting: {}", usd);
    let eur = usd.convert(&usd_to_eur);
    println!("After USD→EUR: {}", eur);
    let gbp = eur.convert(&eur_to_gbp);
    println!("After EUR→GBP: {}", gbp);
    println!("(${} × 0.85 × 0.86 = £{})\n", 100, gbp.to_major_floor());

    // ========================================
    // Rate Metadata for Auditability
    // ========================================
    println!("5. RATE METADATA FOR AUDITABILITY");
    println!("----------------------------------");

    // Create a rate with metadata
    let rate = Rate::<USD, EUR>::new(0.85)
        .with_timestamp_unix_secs(1700000000)
        .with_source("ECB"); // European Central Bank

    println!("Rate: {}", rate.value());
    println!("Timestamp: {:?}", rate.timestamp_unix_secs());
    println!("Source: {:?}", rate.source());

    let amount = Amount::<USD>::from_major(1000);
    let converted = amount.convert(&rate);
    println!(
        "\nConverted {} to {} using rate from {:?}",
        amount,
        converted,
        rate.source().unwrap_or("unknown")
    );

    // ========================================
    // Real-World Example: International Payment
    // ========================================
    println!("\n6. REAL-WORLD EXAMPLE: INTERNATIONAL PAYMENT");
    println!("---------------------------------------------");

    // Customer pays in USD
    let payment_usd = Amount::<USD>::from_major(250);
    println!("Customer payment: {}", payment_usd);

    // Current exchange rate (would come from an API in production)
    let current_rate = Rate::<USD, EUR>::new(0.92)
        .with_timestamp_unix_secs(1700000000)
        .with_source("API");

    // Convert to EUR
    let payment_eur = payment_usd.convert(&current_rate);
    println!("Converted to EUR: {}", payment_eur);

    // Calculate fees
    let fee_percentage = 3; // 3% transaction fee
    let fee = (payment_eur * fee_percentage) / 100;
    println!("Transaction fee ({}%): {}", fee_percentage, fee);

    let final_amount = payment_eur - fee;
    println!("Final amount to recipient: {}", final_amount);

    println!("\nTransaction summary:");
    println!("  Original: {}", payment_usd);
    println!(
        "  Rate: {} (from {:?})",
        current_rate.value(),
        current_rate.source().unwrap_or("N/A")
    );
    println!("  Converted: {}", payment_eur);
    println!("  Fee: -{}", fee);
    println!("  Final: {}", final_amount);

    // ========================================
    // Type Safety with Conversions
    // ========================================
    println!("\n7. TYPE SAFETY");
    println!("--------------");

    println!("✓ Can only convert with matching rate types");
    println!("✓ USD amount requires Rate<USD, X>");
    println!("✗ Cannot use Rate<EUR, GBP> on USD amount (compile error!)");
    println!("\nThe type system ensures you always use the correct exchange rate!");

    // This would NOT compile:
    // let usd = Amount::<USD>::from_major(100);
    // let wrong_rate = Rate::<EUR, GBP>::new(0.86);
    // let invalid = usd.convert(&wrong_rate);  // Compile error!

    println!("\n=== All conversion examples completed! ===");
}

pub const fn with_timestamp_unix_secs(self, timestamp_unix_secs: u64) -> Self

Returns a new Rate with the given UNIX timestamp (seconds) metadata set.

Existing metadata values not provided by this method are preserved.

Examples found in repository

examples/conversions.rs (line 110)

fn main() {
    println!("=== Currency Conversion Examples ===\n");

    // ========================================
    // Basic Conversion
    // ========================================
    println!("1. BASIC CONVERSION");
    println!("-------------------");

    let usd_amount = Amount::<USD>::from_major(100);
    println!("Starting amount: {}", usd_amount);

    // Create an exchange rate: 1 USD = 0.85 EUR
    let usd_to_eur = Rate::<USD, EUR>::new(0.85);
    println!("Exchange rate: 1 USD = 0.85 EUR");

    // Convert
    let eur_amount = usd_amount.convert(&usd_to_eur);
    println!("Converted amount: {}", eur_amount);
    println!("(${} × 0.85 = €{})\n", 100, eur_amount.to_major_floor());

    // ========================================
    // Inverse Rates
    // ========================================
    println!("2. INVERSE RATES");
    println!("----------------");

    let usd_to_eur = Rate::<USD, EUR>::new(0.85);
    println!("USD → EUR rate: {}", usd_to_eur.value());

    // Get the inverse rate automatically
    let eur_to_usd = usd_to_eur.inverse();
    println!("EUR → USD rate (inverse): {}", eur_to_usd.value());
    println!("(1 / 0.85 = ~1.176)\n");

    // Converting back
    let original_usd = Amount::<USD>::from_major(100);
    let eur = original_usd.convert(&usd_to_eur);
    let back_to_usd = eur.convert(&eur_to_usd);

    println!("Original: {}", original_usd);
    println!("To EUR:   {}", eur);
    println!("Back to USD: {}", back_to_usd);
    println!("(Should be approximately the same)\n");

    // ========================================
    // Multiple Conversions
    // ========================================
    println!("3. MULTIPLE CONVERSIONS");
    println!("-----------------------");

    let usd = Amount::<USD>::from_major(1000);
    println!("Starting with: {}", usd);

    // Define multiple rates
    let usd_to_eur = Rate::<USD, EUR>::new(0.85);
    let usd_to_gbp = Rate::<USD, GBP>::new(0.73);
    let usd_to_jpy = Rate::<USD, JPY>::new(110.0);

    println!("\nExchange rates:");
    println!("  1 USD = {} EUR", usd_to_eur.value());
    println!("  1 USD = {} GBP", usd_to_gbp.value());
    println!("  1 USD = {} JPY", usd_to_jpy.value());

    println!("\nConversions:");
    let eur = usd.convert(&usd_to_eur);
    let gbp = usd.convert(&usd_to_gbp);
    let jpy = usd.convert(&usd_to_jpy);

    println!("  {} → {}", usd, eur);
    println!("  {} → {}", usd, gbp);
    println!("  {} → {}", usd, jpy);

    // ========================================
    // Chained Conversions
    // ========================================
    println!("\n4. CHAINED CONVERSIONS");
    println!("----------------------");

    println!("Converting USD → EUR → GBP");

    let usd = Amount::<USD>::from_major(100);
    let usd_to_eur = Rate::<USD, EUR>::new(0.85);
    let eur_to_gbp = Rate::<EUR, GBP>::new(0.86);

    println!("Starting: {}", usd);
    let eur = usd.convert(&usd_to_eur);
    println!("After USD→EUR: {}", eur);
    let gbp = eur.convert(&eur_to_gbp);
    println!("After EUR→GBP: {}", gbp);
    println!("(${} × 0.85 × 0.86 = £{})\n", 100, gbp.to_major_floor());

    // ========================================
    // Rate Metadata for Auditability
    // ========================================
    println!("5. RATE METADATA FOR AUDITABILITY");
    println!("----------------------------------");

    // Create a rate with metadata
    let rate = Rate::<USD, EUR>::new(0.85)
        .with_timestamp_unix_secs(1700000000)
        .with_source("ECB"); // European Central Bank

    println!("Rate: {}", rate.value());
    println!("Timestamp: {:?}", rate.timestamp_unix_secs());
    println!("Source: {:?}", rate.source());

    let amount = Amount::<USD>::from_major(1000);
    let converted = amount.convert(&rate);
    println!(
        "\nConverted {} to {} using rate from {:?}",
        amount,
        converted,
        rate.source().unwrap_or("unknown")
    );

    // ========================================
    // Real-World Example: International Payment
    // ========================================
    println!("\n6. REAL-WORLD EXAMPLE: INTERNATIONAL PAYMENT");
    println!("---------------------------------------------");

    // Customer pays in USD
    let payment_usd = Amount::<USD>::from_major(250);
    println!("Customer payment: {}", payment_usd);

    // Current exchange rate (would come from an API in production)
    let current_rate = Rate::<USD, EUR>::new(0.92)
        .with_timestamp_unix_secs(1700000000)
        .with_source("API");

    // Convert to EUR
    let payment_eur = payment_usd.convert(&current_rate);
    println!("Converted to EUR: {}", payment_eur);

    // Calculate fees
    let fee_percentage = 3; // 3% transaction fee
    let fee = (payment_eur * fee_percentage) / 100;
    println!("Transaction fee ({}%): {}", fee_percentage, fee);

    let final_amount = payment_eur - fee;
    println!("Final amount to recipient: {}", final_amount);

    println!("\nTransaction summary:");
    println!("  Original: {}", payment_usd);
    println!(
        "  Rate: {} (from {:?})",
        current_rate.value(),
        current_rate.source().unwrap_or("N/A")
    );
    println!("  Converted: {}", payment_eur);
    println!("  Fee: -{}", fee);
    println!("  Final: {}", final_amount);

    // ========================================
    // Type Safety with Conversions
    // ========================================
    println!("\n7. TYPE SAFETY");
    println!("--------------");

    println!("✓ Can only convert with matching rate types");
    println!("✓ USD amount requires Rate<USD, X>");
    println!("✗ Cannot use Rate<EUR, GBP> on USD amount (compile error!)");
    println!("\nThe type system ensures you always use the correct exchange rate!");

    // This would NOT compile:
    // let usd = Amount::<USD>::from_major(100);
    // let wrong_rate = Rate::<EUR, GBP>::new(0.86);
    // let invalid = usd.convert(&wrong_rate);  // Compile error!

    println!("\n=== All conversion examples completed! ===");
}

examples/global_currencies.rs (line 158)

fn main() {
    println!("=== Typed Money - Global Currencies Example ===\n");

    // 1. MAJOR FIAT CURRENCIES
    println!("1. MAJOR FIAT CURRENCIES");
    println!("------------------------");
    let usd = Amount::<USD>::from_major(100);
    let cad = Amount::<CAD>::from_major(135);
    let chf = Amount::<CHF>::from_major(90);
    let aud = Amount::<AUD>::from_major(150);
    let nzd = Amount::<NZD>::from_major(160);

    println!("USD: {} ({} decimals)", usd, USD::DECIMALS);
    println!("CAD: {} ({} decimals)", cad, CAD::DECIMALS);
    println!("CHF: {} ({} decimals)", chf, CHF::DECIMALS);
    println!("AUD: {} ({} decimals)", aud, AUD::DECIMALS);
    println!("NZD: {} ({} decimals)", nzd, NZD::DECIMALS);
    println!();

    // 2. ASIAN CURRENCIES
    println!("2. ASIAN CURRENCIES");
    println!("-------------------");
    let cny = Amount::<CNY>::from_major(720);
    let krw = Amount::<KRW>::from_major(130_000);
    let sgd = Amount::<SGD>::from_major(135);
    let hkd = Amount::<HKD>::from_major(780);
    let twd = Amount::<TWD>::from_major(3100);
    let inr = Amount::<INR>::from_major(8300);

    println!("CNY: {} ({} decimals)", cny, CNY::DECIMALS);
    println!("KRW: {} ({} decimals)", krw, KRW::DECIMALS);
    println!("SGD: {} ({} decimals)", sgd, SGD::DECIMALS);
    println!("HKD: {} ({} decimals)", hkd, HKD::DECIMALS);
    println!("TWD: {} ({} decimals)", twd, TWD::DECIMALS);
    println!("INR: {} ({} decimals)", inr, INR::DECIMALS);
    println!();

    // 3. EUROPEAN CURRENCIES
    println!("3. EUROPEAN CURRENCIES");
    println!("----------------------");
    let eur = Amount::<EUR>::from_major(85);
    let gbp = Amount::<GBP>::from_major(75);
    let sek = Amount::<SEK>::from_major(1050);
    let nok = Amount::<NOK>::from_major(1100);
    let dkk = Amount::<DKK>::from_major(650);
    let pln = Amount::<PLN>::from_major(400);
    let czk = Amount::<CZK>::from_major(2300);
    let huf = Amount::<HUF>::from_major(36_000);

    println!("EUR: {} ({} decimals)", eur, EUR::DECIMALS);
    println!("GBP: {} ({} decimals)", gbp, GBP::DECIMALS);
    println!("SEK: {} ({} decimals)", sek, SEK::DECIMALS);
    println!("NOK: {} ({} decimals)", nok, NOK::DECIMALS);
    println!("DKK: {} ({} decimals)", dkk, DKK::DECIMALS);
    println!("PLN: {} ({} decimals)", pln, PLN::DECIMALS);
    println!("CZK: {} ({} decimals)", czk, CZK::DECIMALS);
    println!("HUF: {} ({} decimals)", huf, HUF::DECIMALS);
    println!();

    // 4. AMERICAN CURRENCIES
    println!("4. AMERICAN CURRENCIES");
    println!("----------------------");
    let brl = Amount::<BRL>::from_major(500);
    let mxn = Amount::<MXN>::from_major(1700);
    let ars = Amount::<ARS>::from_major(85_000);
    let clp = Amount::<CLP>::from_major(90_000);

    println!("BRL: {} ({} decimals)", brl, BRL::DECIMALS);
    println!("MXN: {} ({} decimals)", mxn, MXN::DECIMALS);
    println!("ARS: {} ({} decimals)", ars, ARS::DECIMALS);
    println!("CLP: {} ({} decimals)", clp, CLP::DECIMALS);
    println!();

    // 5. AFRICAN/MIDDLE EASTERN CURRENCIES
    println!("5. AFRICAN/MIDDLE EASTERN CURRENCIES");
    println!("------------------------------------");
    let zar = Amount::<ZAR>::from_major(1800);
    let egp = Amount::<EGP>::from_major(3100);
    let aed = Amount::<AED>::from_major(370);
    let sar = Amount::<SAR>::from_major(375);
    let ils = Amount::<ILS>::from_major(360);
    let try_currency = Amount::<TRY>::from_major(3000);

    println!("ZAR: {} ({} decimals)", zar, ZAR::DECIMALS);
    println!("EGP: {} ({} decimals)", egp, EGP::DECIMALS);
    println!("AED: {} ({} decimals)", aed, AED::DECIMALS);
    println!("SAR: {} ({} decimals)", sar, SAR::DECIMALS);
    println!("ILS: {} ({} decimals)", ils, ILS::DECIMALS);
    println!("TRY: {} ({} decimals)", try_currency, TRY::DECIMALS);
    println!();

    // 6. CRYPTOCURRENCIES
    println!("6. CRYPTOCURRENCIES");
    println!("-------------------");
    let btc = Amount::<BTC>::from_minor(100_000_000); // 1.00000000 BTC
    let eth = Amount::<ETH>::from_minor(1_000_000_000_000_000_000); // 1.000000000000000000 ETH

    println!("BTC: {} ({} decimals)", btc, BTC::DECIMALS);
    println!("ETH: {} ({} decimals)", eth, ETH::DECIMALS);
    println!();

    // 7. CURRENCY CONVERSION EXAMPLES
    println!("7. CURRENCY CONVERSION EXAMPLES");
    println!("-------------------------------");

    // USD to EUR
    let usd_to_eur = Rate::<USD, EUR>::new(0.85)
        .with_timestamp_unix_secs(1_700_000_000)
        .with_source("ECB");
    let eur_converted = usd.convert(&usd_to_eur);
    println!(
        "USD to EUR: {} → {} (rate: {})",
        usd,
        eur_converted,
        usd_to_eur.value()
    );

    // EUR to GBP
    let eur_to_gbp = Rate::<EUR, GBP>::new(0.87);
    let gbp_converted = eur_converted.convert(&eur_to_gbp);
    println!(
        "EUR to GBP: {} → {} (rate: {})",
        eur_converted,
        gbp_converted,
        eur_to_gbp.value()
    );

    // USD to JPY
    let usd_to_jpy = Rate::<USD, JPY>::new(150.0);
    let jpy_converted = usd.convert(&usd_to_jpy);
    println!(
        "USD to JPY: {} → {} (rate: {})",
        usd,
        jpy_converted,
        usd_to_jpy.value()
    );
    println!();

    // 8. ROUNDING EXAMPLES
    println!("8. ROUNDING EXAMPLES");
    println!("--------------------");
    let usd_amount = Amount::<USD>::from_minor(12345); // $123.45
    println!("Original: {}", usd_amount);
    println!("Half Up: {}", usd_amount.round(RoundingMode::HalfUp));
    println!("Half Down: {}", usd_amount.round(RoundingMode::HalfDown));
    println!("Half Even: {}", usd_amount.round(RoundingMode::HalfEven));
    println!("Floor: {}", usd_amount.round(RoundingMode::Floor));
    println!("Ceiling: {}", usd_amount.round(RoundingMode::Ceiling));
    println!();

    // 9. CURRENCY METADATA
    println!("9. CURRENCY METADATA");
    println!("--------------------");
    let currencies = [
        ("USD", USD::CODE, USD::SYMBOL, USD::DECIMALS),
        ("EUR", EUR::CODE, EUR::SYMBOL, EUR::DECIMALS),
        ("JPY", JPY::CODE, JPY::SYMBOL, JPY::DECIMALS),
        ("CNY", CNY::CODE, CNY::SYMBOL, CNY::DECIMALS),
        ("BRL", BRL::CODE, BRL::SYMBOL, BRL::DECIMALS),
        ("AED", AED::CODE, AED::SYMBOL, AED::DECIMALS),
    ];

    for (name, code, symbol, decimals) in currencies {
        println!("{}: {} {} ({} decimals)", name, symbol, code, decimals);
    }
    println!();

    // 10. TYPE SAFETY DEMONSTRATION
    println!("10. TYPE SAFETY DEMONSTRATION");
    println!("-----------------------------");
    println!("✓ USD + USD = Valid");
    println!("✓ EUR + EUR = Valid");
    println!("✓ CAD + CAD = Valid");
    println!("✗ USD + EUR = Compile Error!");
    println!("✗ CAD + JPY = Compile Error!");
    println!("✗ BRL + TRY = Compile Error!");
    println!();

    println!("=== Global Currencies Example Completed! ===");
    println!("Total currencies supported: 30+");
    println!("Regions covered: North America, Europe, Asia, South America, Africa, Middle East");
    println!("Type safety: 100% compile-time currency mixing prevention");
}

pub const fn with_source(self, source: &'static str) -> Self

Returns a new Rate with the given static source identifier set.

Existing metadata values not provided by this method are preserved.

Examples found in repository

examples/conversions.rs (line 111)

fn main() {
    println!("=== Currency Conversion Examples ===\n");

    // ========================================
    // Basic Conversion
    // ========================================
    println!("1. BASIC CONVERSION");
    println!("-------------------");

    let usd_amount = Amount::<USD>::from_major(100);
    println!("Starting amount: {}", usd_amount);

    // Create an exchange rate: 1 USD = 0.85 EUR
    let usd_to_eur = Rate::<USD, EUR>::new(0.85);
    println!("Exchange rate: 1 USD = 0.85 EUR");

    // Convert
    let eur_amount = usd_amount.convert(&usd_to_eur);
    println!("Converted amount: {}", eur_amount);
    println!("(${} × 0.85 = €{})\n", 100, eur_amount.to_major_floor());

    // ========================================
    // Inverse Rates
    // ========================================
    println!("2. INVERSE RATES");
    println!("----------------");

    let usd_to_eur = Rate::<USD, EUR>::new(0.85);
    println!("USD → EUR rate: {}", usd_to_eur.value());

    // Get the inverse rate automatically
    let eur_to_usd = usd_to_eur.inverse();
    println!("EUR → USD rate (inverse): {}", eur_to_usd.value());
    println!("(1 / 0.85 = ~1.176)\n");

    // Converting back
    let original_usd = Amount::<USD>::from_major(100);
    let eur = original_usd.convert(&usd_to_eur);
    let back_to_usd = eur.convert(&eur_to_usd);

    println!("Original: {}", original_usd);
    println!("To EUR:   {}", eur);
    println!("Back to USD: {}", back_to_usd);
    println!("(Should be approximately the same)\n");

    // ========================================
    // Multiple Conversions
    // ========================================
    println!("3. MULTIPLE CONVERSIONS");
    println!("-----------------------");

    let usd = Amount::<USD>::from_major(1000);
    println!("Starting with: {}", usd);

    // Define multiple rates
    let usd_to_eur = Rate::<USD, EUR>::new(0.85);
    let usd_to_gbp = Rate::<USD, GBP>::new(0.73);
    let usd_to_jpy = Rate::<USD, JPY>::new(110.0);

    println!("\nExchange rates:");
    println!("  1 USD = {} EUR", usd_to_eur.value());
    println!("  1 USD = {} GBP", usd_to_gbp.value());
    println!("  1 USD = {} JPY", usd_to_jpy.value());

    println!("\nConversions:");
    let eur = usd.convert(&usd_to_eur);
    let gbp = usd.convert(&usd_to_gbp);
    let jpy = usd.convert(&usd_to_jpy);

    println!("  {} → {}", usd, eur);
    println!("  {} → {}", usd, gbp);
    println!("  {} → {}", usd, jpy);

    // ========================================
    // Chained Conversions
    // ========================================
    println!("\n4. CHAINED CONVERSIONS");
    println!("----------------------");

    println!("Converting USD → EUR → GBP");

    let usd = Amount::<USD>::from_major(100);
    let usd_to_eur = Rate::<USD, EUR>::new(0.85);
    let eur_to_gbp = Rate::<EUR, GBP>::new(0.86);

    println!("Starting: {}", usd);
    let eur = usd.convert(&usd_to_eur);
    println!("After USD→EUR: {}", eur);
    let gbp = eur.convert(&eur_to_gbp);
    println!("After EUR→GBP: {}", gbp);
    println!("(${} × 0.85 × 0.86 = £{})\n", 100, gbp.to_major_floor());

    // ========================================
    // Rate Metadata for Auditability
    // ========================================
    println!("5. RATE METADATA FOR AUDITABILITY");
    println!("----------------------------------");

    // Create a rate with metadata
    let rate = Rate::<USD, EUR>::new(0.85)
        .with_timestamp_unix_secs(1700000000)
        .with_source("ECB"); // European Central Bank

    println!("Rate: {}", rate.value());
    println!("Timestamp: {:?}", rate.timestamp_unix_secs());
    println!("Source: {:?}", rate.source());

    let amount = Amount::<USD>::from_major(1000);
    let converted = amount.convert(&rate);
    println!(
        "\nConverted {} to {} using rate from {:?}",
        amount,
        converted,
        rate.source().unwrap_or("unknown")
    );

    // ========================================
    // Real-World Example: International Payment
    // ========================================
    println!("\n6. REAL-WORLD EXAMPLE: INTERNATIONAL PAYMENT");
    println!("---------------------------------------------");

    // Customer pays in USD
    let payment_usd = Amount::<USD>::from_major(250);
    println!("Customer payment: {}", payment_usd);

    // Current exchange rate (would come from an API in production)
    let current_rate = Rate::<USD, EUR>::new(0.92)
        .with_timestamp_unix_secs(1700000000)
        .with_source("API");

    // Convert to EUR
    let payment_eur = payment_usd.convert(&current_rate);
    println!("Converted to EUR: {}", payment_eur);

    // Calculate fees
    let fee_percentage = 3; // 3% transaction fee
    let fee = (payment_eur * fee_percentage) / 100;
    println!("Transaction fee ({}%): {}", fee_percentage, fee);

    let final_amount = payment_eur - fee;
    println!("Final amount to recipient: {}", final_amount);

    println!("\nTransaction summary:");
    println!("  Original: {}", payment_usd);
    println!(
        "  Rate: {} (from {:?})",
        current_rate.value(),
        current_rate.source().unwrap_or("N/A")
    );
    println!("  Converted: {}", payment_eur);
    println!("  Fee: -{}", fee);
    println!("  Final: {}", final_amount);

    // ========================================
    // Type Safety with Conversions
    // ========================================
    println!("\n7. TYPE SAFETY");
    println!("--------------");

    println!("✓ Can only convert with matching rate types");
    println!("✓ USD amount requires Rate<USD, X>");
    println!("✗ Cannot use Rate<EUR, GBP> on USD amount (compile error!)");
    println!("\nThe type system ensures you always use the correct exchange rate!");

    // This would NOT compile:
    // let usd = Amount::<USD>::from_major(100);
    // let wrong_rate = Rate::<EUR, GBP>::new(0.86);
    // let invalid = usd.convert(&wrong_rate);  // Compile error!

    println!("\n=== All conversion examples completed! ===");
}

examples/global_currencies.rs (line 159)

fn main() {
    println!("=== Typed Money - Global Currencies Example ===\n");

    // 1. MAJOR FIAT CURRENCIES
    println!("1. MAJOR FIAT CURRENCIES");
    println!("------------------------");
    let usd = Amount::<USD>::from_major(100);
    let cad = Amount::<CAD>::from_major(135);
    let chf = Amount::<CHF>::from_major(90);
    let aud = Amount::<AUD>::from_major(150);
    let nzd = Amount::<NZD>::from_major(160);

    println!("USD: {} ({} decimals)", usd, USD::DECIMALS);
    println!("CAD: {} ({} decimals)", cad, CAD::DECIMALS);
    println!("CHF: {} ({} decimals)", chf, CHF::DECIMALS);
    println!("AUD: {} ({} decimals)", aud, AUD::DECIMALS);
    println!("NZD: {} ({} decimals)", nzd, NZD::DECIMALS);
    println!();

    // 2. ASIAN CURRENCIES
    println!("2. ASIAN CURRENCIES");
    println!("-------------------");
    let cny = Amount::<CNY>::from_major(720);
    let krw = Amount::<KRW>::from_major(130_000);
    let sgd = Amount::<SGD>::from_major(135);
    let hkd = Amount::<HKD>::from_major(780);
    let twd = Amount::<TWD>::from_major(3100);
    let inr = Amount::<INR>::from_major(8300);

    println!("CNY: {} ({} decimals)", cny, CNY::DECIMALS);
    println!("KRW: {} ({} decimals)", krw, KRW::DECIMALS);
    println!("SGD: {} ({} decimals)", sgd, SGD::DECIMALS);
    println!("HKD: {} ({} decimals)", hkd, HKD::DECIMALS);
    println!("TWD: {} ({} decimals)", twd, TWD::DECIMALS);
    println!("INR: {} ({} decimals)", inr, INR::DECIMALS);
    println!();

    // 3. EUROPEAN CURRENCIES
    println!("3. EUROPEAN CURRENCIES");
    println!("----------------------");
    let eur = Amount::<EUR>::from_major(85);
    let gbp = Amount::<GBP>::from_major(75);
    let sek = Amount::<SEK>::from_major(1050);
    let nok = Amount::<NOK>::from_major(1100);
    let dkk = Amount::<DKK>::from_major(650);
    let pln = Amount::<PLN>::from_major(400);
    let czk = Amount::<CZK>::from_major(2300);
    let huf = Amount::<HUF>::from_major(36_000);

    println!("EUR: {} ({} decimals)", eur, EUR::DECIMALS);
    println!("GBP: {} ({} decimals)", gbp, GBP::DECIMALS);
    println!("SEK: {} ({} decimals)", sek, SEK::DECIMALS);
    println!("NOK: {} ({} decimals)", nok, NOK::DECIMALS);
    println!("DKK: {} ({} decimals)", dkk, DKK::DECIMALS);
    println!("PLN: {} ({} decimals)", pln, PLN::DECIMALS);
    println!("CZK: {} ({} decimals)", czk, CZK::DECIMALS);
    println!("HUF: {} ({} decimals)", huf, HUF::DECIMALS);
    println!();

    // 4. AMERICAN CURRENCIES
    println!("4. AMERICAN CURRENCIES");
    println!("----------------------");
    let brl = Amount::<BRL>::from_major(500);
    let mxn = Amount::<MXN>::from_major(1700);
    let ars = Amount::<ARS>::from_major(85_000);
    let clp = Amount::<CLP>::from_major(90_000);

    println!("BRL: {} ({} decimals)", brl, BRL::DECIMALS);
    println!("MXN: {} ({} decimals)", mxn, MXN::DECIMALS);
    println!("ARS: {} ({} decimals)", ars, ARS::DECIMALS);
    println!("CLP: {} ({} decimals)", clp, CLP::DECIMALS);
    println!();

    // 5. AFRICAN/MIDDLE EASTERN CURRENCIES
    println!("5. AFRICAN/MIDDLE EASTERN CURRENCIES");
    println!("------------------------------------");
    let zar = Amount::<ZAR>::from_major(1800);
    let egp = Amount::<EGP>::from_major(3100);
    let aed = Amount::<AED>::from_major(370);
    let sar = Amount::<SAR>::from_major(375);
    let ils = Amount::<ILS>::from_major(360);
    let try_currency = Amount::<TRY>::from_major(3000);

    println!("ZAR: {} ({} decimals)", zar, ZAR::DECIMALS);
    println!("EGP: {} ({} decimals)", egp, EGP::DECIMALS);
    println!("AED: {} ({} decimals)", aed, AED::DECIMALS);
    println!("SAR: {} ({} decimals)", sar, SAR::DECIMALS);
    println!("ILS: {} ({} decimals)", ils, ILS::DECIMALS);
    println!("TRY: {} ({} decimals)", try_currency, TRY::DECIMALS);
    println!();

    // 6. CRYPTOCURRENCIES
    println!("6. CRYPTOCURRENCIES");
    println!("-------------------");
    let btc = Amount::<BTC>::from_minor(100_000_000); // 1.00000000 BTC
    let eth = Amount::<ETH>::from_minor(1_000_000_000_000_000_000); // 1.000000000000000000 ETH

    println!("BTC: {} ({} decimals)", btc, BTC::DECIMALS);
    println!("ETH: {} ({} decimals)", eth, ETH::DECIMALS);
    println!();

    // 7. CURRENCY CONVERSION EXAMPLES
    println!("7. CURRENCY CONVERSION EXAMPLES");
    println!("-------------------------------");

    // USD to EUR
    let usd_to_eur = Rate::<USD, EUR>::new(0.85)
        .with_timestamp_unix_secs(1_700_000_000)
        .with_source("ECB");
    let eur_converted = usd.convert(&usd_to_eur);
    println!(
        "USD to EUR: {} → {} (rate: {})",
        usd,
        eur_converted,
        usd_to_eur.value()
    );

    // EUR to GBP
    let eur_to_gbp = Rate::<EUR, GBP>::new(0.87);
    let gbp_converted = eur_converted.convert(&eur_to_gbp);
    println!(
        "EUR to GBP: {} → {} (rate: {})",
        eur_converted,
        gbp_converted,
        eur_to_gbp.value()
    );

    // USD to JPY
    let usd_to_jpy = Rate::<USD, JPY>::new(150.0);
    let jpy_converted = usd.convert(&usd_to_jpy);
    println!(
        "USD to JPY: {} → {} (rate: {})",
        usd,
        jpy_converted,
        usd_to_jpy.value()
    );
    println!();

    // 8. ROUNDING EXAMPLES
    println!("8. ROUNDING EXAMPLES");
    println!("--------------------");
    let usd_amount = Amount::<USD>::from_minor(12345); // $123.45
    println!("Original: {}", usd_amount);
    println!("Half Up: {}", usd_amount.round(RoundingMode::HalfUp));
    println!("Half Down: {}", usd_amount.round(RoundingMode::HalfDown));
    println!("Half Even: {}", usd_amount.round(RoundingMode::HalfEven));
    println!("Floor: {}", usd_amount.round(RoundingMode::Floor));
    println!("Ceiling: {}", usd_amount.round(RoundingMode::Ceiling));
    println!();

    // 9. CURRENCY METADATA
    println!("9. CURRENCY METADATA");
    println!("--------------------");
    let currencies = [
        ("USD", USD::CODE, USD::SYMBOL, USD::DECIMALS),
        ("EUR", EUR::CODE, EUR::SYMBOL, EUR::DECIMALS),
        ("JPY", JPY::CODE, JPY::SYMBOL, JPY::DECIMALS),
        ("CNY", CNY::CODE, CNY::SYMBOL, CNY::DECIMALS),
        ("BRL", BRL::CODE, BRL::SYMBOL, BRL::DECIMALS),
        ("AED", AED::CODE, AED::SYMBOL, AED::DECIMALS),
    ];

    for (name, code, symbol, decimals) in currencies {
        println!("{}: {} {} ({} decimals)", name, symbol, code, decimals);
    }
    println!();

    // 10. TYPE SAFETY DEMONSTRATION
    println!("10. TYPE SAFETY DEMONSTRATION");
    println!("-----------------------------");
    println!("✓ USD + USD = Valid");
    println!("✓ EUR + EUR = Valid");
    println!("✓ CAD + CAD = Valid");
    println!("✗ USD + EUR = Compile Error!");
    println!("✗ CAD + JPY = Compile Error!");
    println!("✗ BRL + TRY = Compile Error!");
    println!();

    println!("=== Global Currencies Example Completed! ===");
    println!("Total currencies supported: 30+");
    println!("Regions covered: North America, Europe, Asia, South America, Africa, Middle East");
    println!("Type safety: 100% compile-time currency mixing prevention");
}

pub const fn with_metadata( self, timestamp_unix_secs: u64, source: &'static str, ) -> Self

Convenience method to set both timestamp and source metadata at once.

pub fn inverse(&self) -> Rate<To, From>

Returns the inverse rate (To -> From).

Examples

use typed_money::{Rate, USD, EUR};

let usd_to_eur = Rate::<USD, EUR>::new(0.85);
let eur_to_usd = usd_to_eur.inverse();

// Inverse of 0.85 is approximately 1.176

Examples found in repository

examples/conversions.rs (line 41)

fn main() {
    println!("=== Currency Conversion Examples ===\n");

    // ========================================
    // Basic Conversion
    // ========================================
    println!("1. BASIC CONVERSION");
    println!("-------------------");

    let usd_amount = Amount::<USD>::from_major(100);
    println!("Starting amount: {}", usd_amount);

    // Create an exchange rate: 1 USD = 0.85 EUR
    let usd_to_eur = Rate::<USD, EUR>::new(0.85);
    println!("Exchange rate: 1 USD = 0.85 EUR");

    // Convert
    let eur_amount = usd_amount.convert(&usd_to_eur);
    println!("Converted amount: {}", eur_amount);
    println!("(${} × 0.85 = €{})\n", 100, eur_amount.to_major_floor());

    // ========================================
    // Inverse Rates
    // ========================================
    println!("2. INVERSE RATES");
    println!("----------------");

    let usd_to_eur = Rate::<USD, EUR>::new(0.85);
    println!("USD → EUR rate: {}", usd_to_eur.value());

    // Get the inverse rate automatically
    let eur_to_usd = usd_to_eur.inverse();
    println!("EUR → USD rate (inverse): {}", eur_to_usd.value());
    println!("(1 / 0.85 = ~1.176)\n");

    // Converting back
    let original_usd = Amount::<USD>::from_major(100);
    let eur = original_usd.convert(&usd_to_eur);
    let back_to_usd = eur.convert(&eur_to_usd);

    println!("Original: {}", original_usd);
    println!("To EUR:   {}", eur);
    println!("Back to USD: {}", back_to_usd);
    println!("(Should be approximately the same)\n");

    // ========================================
    // Multiple Conversions
    // ========================================
    println!("3. MULTIPLE CONVERSIONS");
    println!("-----------------------");

    let usd = Amount::<USD>::from_major(1000);
    println!("Starting with: {}", usd);

    // Define multiple rates
    let usd_to_eur = Rate::<USD, EUR>::new(0.85);
    let usd_to_gbp = Rate::<USD, GBP>::new(0.73);
    let usd_to_jpy = Rate::<USD, JPY>::new(110.0);

    println!("\nExchange rates:");
    println!("  1 USD = {} EUR", usd_to_eur.value());
    println!("  1 USD = {} GBP", usd_to_gbp.value());
    println!("  1 USD = {} JPY", usd_to_jpy.value());

    println!("\nConversions:");
    let eur = usd.convert(&usd_to_eur);
    let gbp = usd.convert(&usd_to_gbp);
    let jpy = usd.convert(&usd_to_jpy);

    println!("  {} → {}", usd, eur);
    println!("  {} → {}", usd, gbp);
    println!("  {} → {}", usd, jpy);

    // ========================================
    // Chained Conversions
    // ========================================
    println!("\n4. CHAINED CONVERSIONS");
    println!("----------------------");

    println!("Converting USD → EUR → GBP");

    let usd = Amount::<USD>::from_major(100);
    let usd_to_eur = Rate::<USD, EUR>::new(0.85);
    let eur_to_gbp = Rate::<EUR, GBP>::new(0.86);

    println!("Starting: {}", usd);
    let eur = usd.convert(&usd_to_eur);
    println!("After USD→EUR: {}", eur);
    let gbp = eur.convert(&eur_to_gbp);
    println!("After EUR→GBP: {}", gbp);
    println!("(${} × 0.85 × 0.86 = £{})\n", 100, gbp.to_major_floor());

    // ========================================
    // Rate Metadata for Auditability
    // ========================================
    println!("5. RATE METADATA FOR AUDITABILITY");
    println!("----------------------------------");

    // Create a rate with metadata
    let rate = Rate::<USD, EUR>::new(0.85)
        .with_timestamp_unix_secs(1700000000)
        .with_source("ECB"); // European Central Bank

    println!("Rate: {}", rate.value());
    println!("Timestamp: {:?}", rate.timestamp_unix_secs());
    println!("Source: {:?}", rate.source());

    let amount = Amount::<USD>::from_major(1000);
    let converted = amount.convert(&rate);
    println!(
        "\nConverted {} to {} using rate from {:?}",
        amount,
        converted,
        rate.source().unwrap_or("unknown")
    );

    // ========================================
    // Real-World Example: International Payment
    // ========================================
    println!("\n6. REAL-WORLD EXAMPLE: INTERNATIONAL PAYMENT");
    println!("---------------------------------------------");

    // Customer pays in USD
    let payment_usd = Amount::<USD>::from_major(250);
    println!("Customer payment: {}", payment_usd);

    // Current exchange rate (would come from an API in production)
    let current_rate = Rate::<USD, EUR>::new(0.92)
        .with_timestamp_unix_secs(1700000000)
        .with_source("API");

    // Convert to EUR
    let payment_eur = payment_usd.convert(&current_rate);
    println!("Converted to EUR: {}", payment_eur);

    // Calculate fees
    let fee_percentage = 3; // 3% transaction fee
    let fee = (payment_eur * fee_percentage) / 100;
    println!("Transaction fee ({}%): {}", fee_percentage, fee);

    let final_amount = payment_eur - fee;
    println!("Final amount to recipient: {}", final_amount);

    println!("\nTransaction summary:");
    println!("  Original: {}", payment_usd);
    println!(
        "  Rate: {} (from {:?})",
        current_rate.value(),
        current_rate.source().unwrap_or("N/A")
    );
    println!("  Converted: {}", payment_eur);
    println!("  Fee: -{}", fee);
    println!("  Final: {}", final_amount);

    // ========================================
    // Type Safety with Conversions
    // ========================================
    println!("\n7. TYPE SAFETY");
    println!("--------------");

    println!("✓ Can only convert with matching rate types");
    println!("✓ USD amount requires Rate<USD, X>");
    println!("✗ Cannot use Rate<EUR, GBP> on USD amount (compile error!)");
    println!("\nThe type system ensures you always use the correct exchange rate!");

    // This would NOT compile:
    // let usd = Amount::<USD>::from_major(100);
    // let wrong_rate = Rate::<EUR, GBP>::new(0.86);
    // let invalid = usd.convert(&wrong_rate);  // Compile error!

    println!("\n=== All conversion examples completed! ===");
}

Trait Implementations

impl<From: Clone + Currency, To: Clone + Currency> Clone for Rate<From, To>

fn clone(&self) -> Rate<From, To>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<From: Debug + Currency, To: Debug + Currency> Debug for Rate<From, To>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<From: PartialEq + Currency, To: PartialEq + Currency> PartialEq for Rate<From, To>

fn eq(&self, other: &Rate<From, To>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<From: Copy + Currency, To: Copy + Currency> Copy for Rate<From, To>

impl<From: Currency, To: Currency> StructuralPartialEq for Rate<From, To>