library/core/src/macros/panic.md

   1 Panics the current thread.
   2
   3 This allows a program to terminate immediately and provide feedback
   4 to the caller of the program.
   5
   6 This macro is the perfect way to assert conditions in example code and in
   7 tests. `panic!` is closely tied with the `unwrap` method of both
   8 [`Option`][ounwrap] and [`Result`][runwrap] enums. Both implementations call
   9 `panic!` when they are set to [`None`] or [`Err`] variants.
  10
  11 When using `panic!()` you can specify a string payload, that is built using
  12 the [`format!`] syntax. That payload is used when injecting the panic into
  13 the calling Rust thread, causing the thread to panic entirely.
  14
  15 The behavior of the default `std` hook, i.e. the code that runs directly
  16 after the panic is invoked, is to print the message payload to
  17 `stderr` along with the file/line/column information of the `panic!()`
  18 call. You can override the panic hook using [`std::panic::set_hook()`].
  19 Inside the hook a panic can be accessed as a `&dyn Any + Send`,
  20 which contains either a `&str` or `String` for regular `panic!()` invocations.
  21 To panic with a value of another other type, [`panic_any`] can be used.
  22
  23 See also the macro [`compile_error!`], for raising errors during compilation.
  24
  25 # When to use `panic!` vs `Result`
  26
  27 The Rust model of error handling groups errors into two major categories:
  28 recoverable and unrecoverable errors. For a recoverable error, such as a file
  29 not found error, it’s reasonable to report the problem to the user and retry
  30 the operation. Unrecoverable errors are always symptoms of bugs, like trying to
  31 access a location beyond the end of an array.
  32
  33 The Rust language and standard library provides `Result` and `panic!` as parts
  34 of two complementary systems for representing, reporting, propagating, reacting
  35 to, and discarding errors for in these two categories.
  36
  37 The `panic!` macro is provided to represent unrecoverable errors, whereas the
  38 `Result` enum is provided to represent recoverable errors. For more detailed
  39 information about error handling check out the [book] or the [`std::result`]
  40 module docs.
  41
  42 [ounwrap]: Option::unwrap
  43 [runwrap]: Result::unwrap
  44 [`std::panic::set_hook()`]: ../std/panic/fn.set_hook.html
  45 [`panic_any`]: ../std/panic/fn.panic_any.html
  46 [`Box`]: ../std/boxed/struct.Box.html
  47 [`Any`]: crate::any::Any
  48 [`format!`]: ../std/macro.format.html
  49 [book]: ../book/ch09-00-error-handling.html
  50 [`std::result`]: ../std/result/index.html
  51
  52 # Current implementation
  53
  54 If the main thread panics it will terminate all your threads and end your
  55 program with code `101`.
  56
  57 # Examples
  58
  59 ```should_panic
  60 # #![allow(unreachable_code)]
  61 panic!();
  62 panic!("this is a terrible mistake!");
  63 panic!("this is a {} {message}", "fancy", message = "message");
  64 std::panic::panic_any(4); // panic with the value of 4 to be collected elsewhere
  65 ```