The panic!() macro was given earlier as a common example of a macro in Rust, and this is indeed one of the most common across Rust's standard library.
This macro immediately and irrecoverably terminates the program in which it was called:
fn main() {
panic!("Error!")
}
It then prints the exact line and column numbers for where the panic occurred, and (optionally) prints a string, passed to it as a parameter, to error output explaining the reason, as well as a full backtrace of the runtime call stack (the record of processes executed during runtime):
thread 'main' panicked at src/main.rs:2:5:
Error!
stack backtrace:
0: rust_begin_unwind
at /rustc/.../library/std/src/panicking.rs:665:5
1: core::panicking::panic_fmt
at /rustc/.../library/core/src/panicking.rs:76:14
2: playground::main
at ./src/main.rs:2:5
3: core::ops::function::FnOnce::call_once
at ./.rustup/toolchains/stable-x86_64-unknown-linux-gnu/lib/rustlib/src/rust/library/core/src/ops/function.rs:250:5
While the above example involves manually invoking the panic!() macro as an intended result of execution, many other built-in functions and macros in the standard library are written to invoke it if something goes irreparably wrong.
For example, the method remove(), implemented for vectors, will call the
panic!() macro if an attempt is made to remove an element on an out-of-bounds index:
fn main() {
let mut v = vec![1,2,3,4,5];
v.remove(6);
}
thread 'main' panicked at src/main.rs:3:7:
removal index (is 6) should be < len (is 5)
In the implementation for the remove() method, the panic!() macro has been passed a string that provides contextual, useful information, saying exactly how the given index is out-of-bounds of the length of the given vector.
Since this macro allows for full string formatting, relevant variables and values can be passed into the error output string for maximum contextual clarity:
fn main() {
let big_num = i128::MAX;
panic!("Number {num} is too big!", num = big_num)
}
thread 'main' panicked at src/main.rs:3:5:
Number 170141183460469231731687303715884105727 is too big!
Exercise:
Cause the below code to panic with the following message:
removal index (is 100) should be < len (is 10)