<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>library/core/src/macros/panic.md - fork/rust @ master</title>
<meta name="description" content="library/core/src/macros/panic.md in fork/rust at master.">
<meta property="og:title" content="library/core/src/macros/panic.md - fork/rust @ master">
<meta property="og:description" content="library/core/src/macros/panic.md in fork/rust at master.">
<meta property="og:type" content="website">
<meta property="og:site_name" content="git.julia.blue">
<link rel="stylesheet" href="/css/style.css?v=62">
<script type="module" src="/js/main.js?v=62"></script>
</head>
<body>
<main data-ref="master" data-tip="3bcad65fbf67b6edf87c949531fbc13435882e6b">
<noscript>
  <div class="callout">
    <p>
      hey! this is a static git repo viewer. commit diffs, file history,
      older commits and other revisions won't load without javascript.
    </p>
    <p>
      you are still able to view source files on branch/tag tips,
      but the experience is degraded.
    </p>
  </div>
</noscript>
<header class="repo"><div>
<h1>fork/rust</h1>
</div>
<pre class="clone">git clone https://git.julia.blue/fork/rust</pre>
</header>
<p class="snapshot-commit"><span class="commit-author">bors</span><span class="commit-message" data-commit="3bcad65fbf67b6edf87c949531fbc13435882e6b">Auto merge of #103046 - JanBeh:PR_clarify_cmp_terminology, r=workingjubilee</span><span class="snapshot-sha sha" data-commit="3bcad65fbf67b6edf87c949531fbc13435882e6b">3bcad65fbf6</span><time datetime="2023-10-05T15:24:54+00:00" title="2023-10-05 15:24:54 +0000">2023-10-05</time></p>
<header class="topbar"><details class="switcher"><summary>master</summary><div class="menu"><strong>branches</strong><a class="current" href="/fork/rust/ref/master/">master</a><strong>tags</strong><a href="/fork/rust/ref/1.39.0/">1.39.0</a><a href="/fork/rust/ref/1.40.0/">1.40.0</a><a href="/fork/rust/ref/1.41.0/">1.41.0</a><a href="/fork/rust/ref/1.41.1/">1.41.1</a><a href="/fork/rust/ref/1.42.0/">1.42.0</a><a href="/fork/rust/ref/1.43.0/">1.43.0</a><a href="/fork/rust/ref/1.43.1/">1.43.1</a><a href="/fork/rust/ref/1.44.0/">1.44.0</a><a class="all" href="/fork/rust/refs">all refs →</a></div></details><nav class="crumbs"><a href="/fork/rust/">rust</a> / <a href="/fork/rust/ref/master/tree/library/">library</a> / <a href="/fork/rust/ref/master/tree/library/core/">core</a> / <a href="/fork/rust/ref/master/tree/library/core/src/">src</a> / <a href="/fork/rust/ref/master/tree/library/core/src/macros/">macros</a> / <span class="cur">panic.md</span></nav>
<span class="view-stats"><span>4.2 KiB</span><span>99 lines</span></span><span class="actions"><a class="raw" href="/fork/rust/raw/60100c2655a6e47664e61f30bd02ef4965526979/library/core/src/macros/panic.md">raw</a></span></header>
<div class="markdown-view"><input type="radio" name="markdown-view" id="markdown-rendered" checked><label for="markdown-rendered">rendered</label><input type="radio" name="markdown-view" id="markdown-code"><label for="markdown-code">code</label><section class="readme rendered"><p>Panics the current thread.</p>
<p>This allows a program to terminate immediately and provide feedback
to the caller of the program.</p>
<p>This macro is the perfect way to assert conditions in example code and in
tests. <code>panic!</code> is closely tied with the <code>unwrap</code> method of both
<a href="Option::unwrap"><code>Option</code></a> and <a href="Result::unwrap"><code>Result</code></a> enums. Both implementations call
<code>panic!</code> when they are set to [<code>None</code>] or [<code>Err</code>] variants.</p>
<p>When using <code>panic!()</code> you can specify a string payload that is built using
[formatting syntax]. That payload is used when injecting the panic into
the calling Rust thread, causing the thread to panic entirely.</p>
<p>The behavior of the default <code>std</code> hook, i.e. the code that runs directly
after the panic is invoked, is to print the message payload to
<code>stderr</code> along with the file/line/column information of the <code>panic!()</code>
call. You can override the panic hook using <a href="../std/panic/fn.set_hook.html"><code>std::panic::set_hook()</code></a>.
Inside the hook a panic can be accessed as a <code>&amp;dyn Any + Send</code>,
which contains either a <code>&amp;str</code> or <code>String</code> for regular <code>panic!()</code> invocations.
(Whether a particular invocation contains the payload at type <code>&amp;str</code> or <code>String</code> is unspecified and can change.)
To panic with a value of another other type, <a href="../std/panic/fn.panic_any.html"><code>panic_any</code></a> can be used.</p>
<p>See also the macro [<code>compile_error!</code>], for raising errors during compilation.</p>
<h1>When to use <code>panic!</code> vs <code>Result</code></h1>
<p>The Rust language provides two complementary systems for constructing /
representing, reporting, propagating, reacting to, and discarding errors. These
responsibilities are collectively known as "error handling." <code>panic!</code> and
<code>Result</code> are similar in that they are each the primary interface of their
respective error handling systems; however, the meaning these interfaces attach
to their errors and the responsibilities they fulfill within their respective
error handling systems differ.</p>
<p>The <code>panic!</code> macro is used to construct errors that represent a bug that has
been detected in your program. With <code>panic!</code> you provide a message that
describes the bug and the language then constructs an error with that message,
reports it, and propagates it for you.</p>
<p><code>Result</code> on the other hand is used to wrap other types that represent either
the successful result of some computation, <code>Ok(T)</code>, or error types that
represent an anticipated runtime failure mode of that computation, <code>Err(E)</code>.
<code>Result</code> is used alongside user defined types which represent the various
anticipated runtime failure modes that the associated computation could
encounter. <code>Result</code> must be propagated manually, often with the help of the
<code>?</code> operator and <code>Try</code> trait, and they must be reported manually, often with
the help of the <code>Error</code> trait.</p>
<p>For more detailed information about error handling check out the <a href="../book/ch09-00-error-handling.html">book</a> or the
<a href="../std/result/index.html"><code>std::result</code></a> module docs.</p>
<h1>Current implementation</h1>
<p>If the main thread panics it will terminate all your threads and end your
program with code <code>101</code>.</p>
<h1>Editions</h1>
<p>Behavior of the panic macros changed over editions.</p>
<h2>2021 and later</h2>
<p>In Rust 2021 and later, <code>panic!</code> always requires a format string and
the applicable format arguments, and is the same in <code>core</code> and <code>std</code>.
Use <a href="../std/panic/fn.panic_any.html"><code>std::panic::panic_any(x)</code></a> to
panic with an arbitrary payload.</p>
<h2>2018 and 2015</h2>
<p>In Rust Editions prior to 2021, <code>std::panic!(x)</code> with a single
argument directly uses that argument as a payload.
This is true even if the argument is a string literal.
For example, <code>panic!("problem: {reason}")</code> panics with a
payload of literally <code>"problem: {reason}"</code> (a <code>&amp;'static str</code>).</p>
<p><code>core::panic!(x)</code> with a single argument requires that <code>x</code> be <code>&amp;str</code>,
but otherwise behaves like <code>std::panic!</code>. In particular, the string
need not be a literal, and is not interpreted as a format string.</p>
<h1>Examples</h1>
<pre># #![allow(unreachable_code)]
panic!();
panic!(&quot;this is a terrible mistake!&quot;);
panic!(&quot;this is a {} {message}&quot;, &quot;fancy&quot;, message = &quot;message&quot;);
std::panic::panic_any(4); // panic with the value of 4 to be collected elsewhere
</pre>
</section><div class="code-panel"><pre class="code src" data-hl="library/core/src/macros/panic.md"><span class="code-line"><a class="ln" id="L1" href="#L1">1</a><span class="code-text">Panics the current thread.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2" href="#L2">2</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L3" href="#L3">3</a><span class="code-text">This allows a program to terminate immediately and provide feedback</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L4" href="#L4">4</a><span class="code-text">to the caller of the program.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L6" href="#L6">6</a><span class="code-text">This macro is the perfect way to assert conditions in example code and in</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L7" href="#L7">7</a><span class="code-text">tests. `panic!` is closely tied with the `unwrap` method of both</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L8" href="#L8">8</a><span class="code-text">[`Option`][ounwrap] and [`Result`][runwrap] enums. Both implementations call</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L9" href="#L9">9</a><span class="code-text">`panic!` when they are set to [`None`] or [`Err`] variants.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L10" href="#L10">10</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L11" href="#L11">11</a><span class="code-text">When using `panic!()` you can specify a string payload that is built using</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L12" href="#L12">12</a><span class="code-text">[formatting syntax]. That payload is used when injecting the panic into</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text">the calling Rust thread, causing the thread to panic entirely.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L14" href="#L14">14</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L15" href="#L15">15</a><span class="code-text">The behavior of the default `std` hook, i.e. the code that runs directly</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L16" href="#L16">16</a><span class="code-text">after the panic is invoked, is to print the message payload to</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L17" href="#L17">17</a><span class="code-text">`stderr` along with the file/line/column information of the `panic!()`</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L18" href="#L18">18</a><span class="code-text">call. You can override the panic hook using [`std::panic::set_hook()`].</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L19" href="#L19">19</a><span class="code-text">Inside the hook a panic can be accessed as a `&amp;dyn Any + Send`,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L20" href="#L20">20</a><span class="code-text">which contains either a `&amp;str` or `String` for regular `panic!()` invocations.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L21" href="#L21">21</a><span class="code-text">(Whether a particular invocation contains the payload at type `&amp;str` or `String` is unspecified and can change.)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L22" href="#L22">22</a><span class="code-text">To panic with a value of another other type, [`panic_any`] can be used.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L23" href="#L23">23</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L24" href="#L24">24</a><span class="code-text">See also the macro [`compile_error!`], for raising errors during compilation.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L25" href="#L25">25</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L26" href="#L26">26</a><span class="code-text"># When to use `panic!` vs `Result`</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L27" href="#L27">27</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L28" href="#L28">28</a><span class="code-text">The Rust language provides two complementary systems for constructing /</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L29" href="#L29">29</a><span class="code-text">representing, reporting, propagating, reacting to, and discarding errors. These</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L30" href="#L30">30</a><span class="code-text">responsibilities are collectively known as &quot;error handling.&quot; `panic!` and</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L31" href="#L31">31</a><span class="code-text">`Result` are similar in that they are each the primary interface of their</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L32" href="#L32">32</a><span class="code-text">respective error handling systems; however, the meaning these interfaces attach</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L33" href="#L33">33</a><span class="code-text">to their errors and the responsibilities they fulfill within their respective</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L34" href="#L34">34</a><span class="code-text">error handling systems differ.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L35" href="#L35">35</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L36" href="#L36">36</a><span class="code-text">The `panic!` macro is used to construct errors that represent a bug that has</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L37" href="#L37">37</a><span class="code-text">been detected in your program. With `panic!` you provide a message that</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L38" href="#L38">38</a><span class="code-text">describes the bug and the language then constructs an error with that message,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L39" href="#L39">39</a><span class="code-text">reports it, and propagates it for you.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L40" href="#L40">40</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L41" href="#L41">41</a><span class="code-text">`Result` on the other hand is used to wrap other types that represent either</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L42" href="#L42">42</a><span class="code-text">the successful result of some computation, `Ok(T)`, or error types that</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L43" href="#L43">43</a><span class="code-text">represent an anticipated runtime failure mode of that computation, `Err(E)`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L44" href="#L44">44</a><span class="code-text">`Result` is used alongside user defined types which represent the various</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L45" href="#L45">45</a><span class="code-text">anticipated runtime failure modes that the associated computation could</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L46" href="#L46">46</a><span class="code-text">encounter. `Result` must be propagated manually, often with the help of the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L47" href="#L47">47</a><span class="code-text">`?` operator and `Try` trait, and they must be reported manually, often with</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L48" href="#L48">48</a><span class="code-text">the help of the `Error` trait.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L49" href="#L49">49</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L50" href="#L50">50</a><span class="code-text">For more detailed information about error handling check out the [book] or the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L51" href="#L51">51</a><span class="code-text">[`std::result`] module docs.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L52" href="#L52">52</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L53" href="#L53">53</a><span class="code-text">[ounwrap]: Option::unwrap</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L54" href="#L54">54</a><span class="code-text">[runwrap]: Result::unwrap</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L55" href="#L55">55</a><span class="code-text">[`std::panic::set_hook()`]: ../std/panic/fn.set_hook.html</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L56" href="#L56">56</a><span class="code-text">[`panic_any`]: ../std/panic/fn.panic_any.html</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L57" href="#L57">57</a><span class="code-text">[`Box`]: ../std/boxed/struct.Box.html</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L58" href="#L58">58</a><span class="code-text">[`Any`]: crate::any::Any</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L59" href="#L59">59</a><span class="code-text">[`format!` syntax]: ../std/fmt/index.html</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L60" href="#L60">60</a><span class="code-text">[book]: ../book/ch09-00-error-handling.html</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L61" href="#L61">61</a><span class="code-text">[`std::result`]: ../std/result/index.html</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L62" href="#L62">62</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L63" href="#L63">63</a><span class="code-text"># Current implementation</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L64" href="#L64">64</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L65" href="#L65">65</a><span class="code-text">If the main thread panics it will terminate all your threads and end your</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L66" href="#L66">66</a><span class="code-text">program with code `101`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L67" href="#L67">67</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L68" href="#L68">68</a><span class="code-text"># Editions</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L69" href="#L69">69</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L70" href="#L70">70</a><span class="code-text">Behavior of the panic macros changed over editions.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L71" href="#L71">71</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L72" href="#L72">72</a><span class="code-text">## 2021 and later</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L73" href="#L73">73</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L74" href="#L74">74</a><span class="code-text">In Rust 2021 and later, `panic!` always requires a format string and</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L75" href="#L75">75</a><span class="code-text">the applicable format arguments, and is the same in `core` and `std`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L76" href="#L76">76</a><span class="code-text">Use [`std::panic::panic_any(x)`](../std/panic/fn.panic_any.html) to</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L77" href="#L77">77</a><span class="code-text">panic with an arbitrary payload.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L78" href="#L78">78</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L79" href="#L79">79</a><span class="code-text">## 2018 and 2015</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L80" href="#L80">80</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L81" href="#L81">81</a><span class="code-text">In Rust Editions prior to 2021, `std::panic!(x)` with a single</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L82" href="#L82">82</a><span class="code-text">argument directly uses that argument as a payload.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L83" href="#L83">83</a><span class="code-text">This is true even if the argument is a string literal.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L84" href="#L84">84</a><span class="code-text">For example, `panic!(&quot;problem: {reason}&quot;)` panics with a</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L85" href="#L85">85</a><span class="code-text">payload of literally `&quot;problem: {reason}&quot;` (a `&amp;'static str`).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L86" href="#L86">86</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L87" href="#L87">87</a><span class="code-text">`core::panic!(x)` with a single argument requires that `x` be `&amp;str`,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L88" href="#L88">88</a><span class="code-text">but otherwise behaves like `std::panic!`. In particular, the string</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L89" href="#L89">89</a><span class="code-text">need not be a literal, and is not interpreted as a format string.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L90" href="#L90">90</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L91" href="#L91">91</a><span class="code-text"># Examples</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L92" href="#L92">92</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L93" href="#L93">93</a><span class="code-text">```should_panic</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L94" href="#L94">94</a><span class="code-text"># #![allow(unreachable_code)]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L95" href="#L95">95</a><span class="code-text">panic!();</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L96" href="#L96">96</a><span class="code-text">panic!(&quot;this is a terrible mistake!&quot;);</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L97" href="#L97">97</a><span class="code-text">panic!(&quot;this is a {} {message}&quot;, &quot;fancy&quot;, message = &quot;message&quot;);</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L98" href="#L98">98</a><span class="code-text">std::panic::panic_any(4); // panic with the value of 4 to be collected elsewhere</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L99" href="#L99">99</a><span class="code-text">```</span></span></pre></div></div>
</main>
</body>
</html>
