Errors and checked arithmetic

Agents will add a fourth kind, a supervised fault, which Concurrency describes.

Returning and handling errors

A function that can fail will return Result<T, E>. The error type E will usually be an enum of your own.

enum PriceError {
    Negative,
    TooMany,
}

fn line_total(price: i64, quantity: i64) -> Result<i64, PriceError> {
    if price < 0 {
        return Result::Err(PriceError::Negative);
    }
    if quantity > 1_000 {
        return Result::Err(PriceError::TooMany);
    }
    return Result::Ok(price * quantity);
}

fn total_or_zero(price: i64, quantity: i64) -> i64 {
    match line_total(price, quantity) {
        Result::Ok(total) => { return total; }
        Result::Err(_) => { return 0; }
    }
}

• An error will be a value. There will be no exceptions, nothing will be thrown, and nothing will be retried unless your code retries it.
• The caller will handle the error with match, or return its own Result.
• If price * quantity overflowed, that would be a panic, not an error: see below.

Built-in error types

A full collection will return an error and stay exactly as it was: nothing will be half-added. When a value cannot be added to a full list, the error will give the value back to you. Results and errors lists which library operations will return each type.

Checked arithmetic

The same rules will apply to every build, with no difference between a debug build and a release build.

• +, -, * and unary - will panic when the result does not fit the type.
• / will round toward zero: -7 / 2 will be -3.
• % will keep the sign of the number divided: -7 % 2 will be -1, and a == (a / b) * b + a % b will always hold.
• Dividing, or taking a remainder, by zero will panic.
• For a signed type, the smallest value divided by -1 will panic, and so will its remainder by -1.
• Unary - will be for signed types only; on an unsigned value it will fail the check.

Shifts and bitwise operators

• The shift count of << and >> will be an unsigned integer of the same width as the value: an i16 shifts by a u16.
• A count equal to or greater than the width will panic.
• << will panic when the result does not fit. >> on a signed value will round down; on an unsigned value it will fill with zeros.
• &, |, ^ and ~ will work on the exact bits of one integer type, and never on bool.

Explicit alternatives

When you want a different behaviour, you will ask for it by name, from the standard library (Numbers lists them):

• Wrapping operations that wrap around the type's range.
• Saturating operations that stop at the type's smallest or largest value.
• Checked conversions between integer types, which return a Result<T, CastError> that holds an error when the value does not fit. The preview has no conversion that silently cuts bits off.

Indexing

• An index into an array or a list will be checked against its length before the access, and an index out of range will panic.
• Text will have no index operator. Reading one byte of text will return a Result with an IndexError.
• A text literal longer than its type allows will fail when you check your code, before anything runs.

What a panic does

A panic will stop the program at once. On a desktop or server, the program will report what kind of defect stopped it and exit with a failure status. Microcontroller boards describes what a board will do after a panic.