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 language provides two complementary systems for constructing /
  28 representing, reporting, propagating, reacting to, and discarding errors. These
  29 responsibilities are collectively known as "error handling." `panic!` and
  30 `Result` are similar in that they are each the primary interface of their
  31 respective error handling systems; however, the meaning these interfaces attach
  32 to their errors and the responsibilities they fulfill within their respective
  33 error handling systems differ.
  34
  35 The `panic!` macro is used to construct errors that represent a bug that has
  36 been detected in your program. With `panic!` you provide a message that
  37 describes the bug and the language then constructs an error with that message,
  38 reports it, and propagates it for you.
  39
  40 `Result` on the other hand is used to wrap other types that represent either
  41 the successful result of some computation, `Ok(T)`, or error types that
  42 represent an anticipated runtime failure mode of that computation, `Err(E)`.
  43 `Result` is used alongside user defined types which represent the various
  44 anticipated runtime failure modes that the associated computation could
  45 encounter. `Result` must be propagated manually, often with the the help of the
  46 `?` operator and `Try` trait, and they must be reported manually, often with
  47 the help of the `Error` trait.
  48
  49 For more detailed information about error handling check out the [book] or the
  50 [`std::result`] module docs.
  51
  52 [ounwrap]: Option::unwrap
  53 [runwrap]: Result::unwrap
  54 [`std::panic::set_hook()`]: ../std/panic/fn.set_hook.html
  55 [`panic_any`]: ../std/panic/fn.panic_any.html
  56 [`Box`]: ../std/boxed/struct.Box.html
  57 [`Any`]: crate::any::Any
  58 [`format!`]: ../std/macro.format.html
  59 [book]: ../book/ch09-00-error-handling.html
  60 [`std::result`]: ../std/result/index.html
  61
  62 # Current implementation
  63
  64 If the main thread panics it will terminate all your threads and end your
  65 program with code `101`.
  66
  67 # Examples
  68
  69 ```should_panic
  70 # #![allow(unreachable_code)]
  71 panic!();
  72 panic!("this is a terrible mistake!");
  73 panic!("this is a {} {message}", "fancy", message = "message");
  74 std::panic::panic_any(4); // panic with the value of 4 to be collected elsewhere
  75 ```