panic! and unrecoverable errors

Two kinds of errors

Things go wrong in every program. Rust splits errors into two kinds. Recoverable errors are expected problems the program can handle: a file is missing, the user typed letters instead of a number, the network is down. Unrecoverable errors are bugs: an index past the end of a list, a value that "can never be zero" being zero. For recoverable errors Rust uses the Result type (next topic). For bugs it uses panic.

What a panic does

fn main() {
    let marks = vec![70, 80, 90];
    println!("{}", marks[10]);
}

thread 'main' panicked at src/main.rs:3:20:
index out of bounds: the len is 3 but the index is 10
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

By default, a panic unwinds: Rust walks back up the call stack, dropping every value so memory and files are cleaned up, and then the thread stops. If the main thread panics, the program exits with an error code. A backtrace is the list of function calls that led to the panic; set RUST_BACKTRACE=1 to see it when you debug.

RUST_BACKTRACE=1 cargo run

Panicking on purpose

fn percent(part: u32, total: u32) -> u32 {
    if total == 0 {
        panic!("percent called with total = 0");
    }
    part * 100 / total
}

unwrap and expect

Option and Result have two shortcut methods. unwrap() gives the value inside, or panics if there is none. expect("message") does the same but with your own message, which makes the panic much easier to understand. Prefer expect over unwrap when you use either.

let n: u32 = "42".parse().unwrap();            // fine: "42" is valid
let port: u16 = std::env::var("PORT")
    .expect("PORT must be set")
    .parse()
    .expect("PORT must be a number");

When is panicking acceptable?

Common mistakes

• unwrap() on user input or file reads in a real program. One typo crashes everything. Use match or ? (next topic).
• unwrap() everywhere with no message. When it panics, you do not know which one failed. Use expect("...") with a clear reason.
• Thinking a panic is "exception handling" like try/catch in Java. Rust does not use panics for normal error flow.
• Ignoring the line number in the panic message. It points to the exact place; start debugging there.