Enum MoneyError 

pub enum MoneyError {
    CurrencyMismatch {
        expected: &'static str,
        found: &'static str,
        context: String,
    },
    ConversionRateMissing {
        from: &'static str,
        to: &'static str,
    },
    PrecisionError {
        currency: &'static str,
        expected: u8,
        actual: u32,
        suggestion: String,
    },
    InvalidAmount {
        reason: String,
        currency: Option<&'static str>,
    },
    ParseError {
        input: String,
        expected_currency: Option<&'static str>,
        reason: String,
    },
    RoundingError {
        currency: &'static str,
        reason: String,
    },
    InvalidRate {
        value: String,
        reason: String,
    },
    Overflow {
        operation: String,
        currency: &'static str,
    },
    Underflow {
        operation: String,
        currency: &'static str,
    },
}

Errors that can occur during monetary operations.

All error variants include context to help diagnose and fix issues.

Variants

CurrencyMismatch

Attempted to perform an operation between incompatible currencies.

This error is primarily for runtime checks. The type system usually prevents this at compile time.

Fields

expected: &'static str

The expected currency code

found: &'static str

The actual currency code found

context: String

Additional context about the operation

ConversionRateMissing

No conversion rate available for the requested currency pair.

Fields

from: &'static str

The source currency code

to: &'static str

The target currency code

PrecisionError

Precision would be lost in the operation.

This warning indicates that an amount has more decimal places than the currency supports.

Fields

currency: &'static str

The currency code

expected: u8

Expected precision (number of decimal places)

actual: u32

Actual precision found

suggestion: String

Suggestion for fixing the error

InvalidAmount

Invalid amount value (NaN, Infinity, or other invalid state).

Fields

reason: String

Description of what makes the amount invalid

currency: Option<&'static str>

The currency code if available

ParseError

Failed to parse a string into a monetary amount.

Fields

input: String

The input string that failed to parse

expected_currency: Option<&'static str>

The expected currency code

reason: String

Description of why parsing failed

RoundingError

Rounding operation failed.

Fields

currency: &'static str

The currency code

reason: String

Description of what went wrong

InvalidRate

Invalid exchange rate value.

Fields

value: String

The rate value that was invalid

reason: String

Description of why the rate is invalid

Overflow

Arithmetic overflow occurred.

Fields

operation: String

The operation that caused overflow

currency: &'static str

The currency code

Underflow

Arithmetic underflow occurred.

Fields

operation: String

The operation that caused underflow

currency: &'static str

The currency code

Implementations

impl MoneyError

pub fn suggestion(&self) -> &str

Returns a suggestion for how to fix this error.

Examples

use typed_money::MoneyError;

let error = MoneyError::InvalidRate {
    value: "0.0".to_string(),
    reason: "Rate must be positive".to_string(),
};

println!("{}", error.suggestion());

Examples found in repository

examples/error_handling.rs (line 136)

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 currency(&self) -> Option<&'static str>

Returns the currency code associated with this error, if any.

Examples found in repository

examples/error_handling.rs (line 137)

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! ===");
}

Trait Implementations

impl Clone for MoneyError

fn clone(&self) -> MoneyError

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for MoneyError

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

Formats the value using the given formatter.

impl Display for MoneyError

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

Formats the value using the given formatter.

impl Error for MoneyError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl PartialEq for MoneyError

fn eq(&self, other: &MoneyError) -> 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 StructuralPartialEq for MoneyError