<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>library/core/src/error.md - fork/rust @ master</title>
<meta name="description" content="library/core/src/error.md in fork/rust at master.">
<meta property="og:title" content="library/core/src/error.md - fork/rust @ master">
<meta property="og:description" content="library/core/src/error.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> / <span class="cur">error.md</span></nav>
<span class="view-stats"><span>5.7 KiB</span><span>139 lines</span></span><span class="actions"><a class="raw" href="/fork/rust/raw/a5deb71e6b80a33b75e8ee074cf1aea1fb71a721/library/core/src/error.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>Interfaces for working with Errors.</p>
<h1>Error Handling In Rust</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." The
components of the first system, the panic runtime and interfaces, are most
commonly used to represent bugs that have been detected in your program. The
components of the second system, <code>Result</code>, the error traits, and user
defined types, are used to represent anticipated runtime failure modes of
your program.</p>
<h2>The Panic Interfaces</h2>
<p>The following are the primary interfaces of the panic system and the
responsibilities they cover:</p>
<ul>
<li>[<code>panic!</code>] and <a href="../../std/panic/fn.panic_any.html"><code>panic_any</code></a> (Constructing, Propagated automatically)</li>
<li><a href="crate::panic::PanicInfo"><code>PanicInfo</code></a> (Reporting)</li>
<li><a href="../../std/panic/fn.set_hook.html"><code>set_hook</code></a>, <a href="../../std/panic/fn.take_hook.html"><code>take_hook</code></a>, and <a href="https://doc.rust-lang.org/nomicon/panic-handler.html"><code>#[panic_handler]</code></a> (Reporting)</li>
<li><a href="../../std/panic/fn.catch_unwind.html"><code>catch_unwind</code></a> and <a href="../../std/panic/fn.resume_unwind.html"><code>resume_unwind</code></a> (Discarding, Propagating)</li>
</ul>
<p>The following are the primary interfaces of the error system and the
responsibilities they cover:</p>
<ul>
<li>[<code>Result</code>] (Propagating, Reacting)</li>
<li>The [<code>Error</code>] trait (Reporting)</li>
<li>User defined types (Constructing / Representing)</li>
<li><a href="../../std/keyword.match.html"><code>match</code></a> and <a href="crate::error::Error"><code>downcast</code></a> (Reacting)</li>
<li>The question mark operator (<a href="../../std/result/index.html#the-question-mark-operator-"><code>?</code></a>) (Propagating)</li>
<li>The partially stable <a href="crate::ops::Try"><code>Try</code></a> traits (Propagating, Constructing)</li>
<li><a href="../../std/process/trait.Termination.html"><code>Termination</code></a> (Reporting)</li>
</ul>
<h2>Converting Errors into Panics</h2>
<p>The panic and error systems are not entirely distinct. Often times errors
that are anticipated runtime failures in an API might instead represent bugs
to a caller. For these situations the standard library provides APIs for
constructing panics with an <code>Error</code> as its source.</p>
<ul>
<li>[<code>Result::unwrap</code>]</li>
<li>[<code>Result::expect</code>]</li>
</ul>
<p>These functions are equivalent, they either return the inner value if the
<code>Result</code> is <code>Ok</code> or panic if the <code>Result</code> is <code>Err</code> printing the inner error
as the source. The only difference between them is that with <code>expect</code> you
provide a panic error message to be printed alongside the source, whereas
<code>unwrap</code> has a default message indicating only that you unwrapped an <code>Err</code>.</p>
<p>Of the two, <code>expect</code> is generally preferred since its <code>msg</code> field allows you
to convey your intent and assumptions which makes tracking down the source
of a panic easier. <code>unwrap</code> on the other hand can still be a good fit in
situations where you can trivially show that a piece of code will never
panic, such as <code>"127.0.0.1".parse::&lt;std::net::IpAddr&gt;().unwrap()</code> or early
prototyping.</p>
<h1>Common Message Styles</h1>
<p>There are two common styles for how people word <code>expect</code> messages. Using
the message to present information to users encountering a panic
("expect as error message") or using the message to present information
to developers debugging the panic ("expect as precondition").</p>
<p>In the former case the expect message is used to describe the error that
has occurred which is considered a bug. Consider the following example:</p>
<pre>// Read environment variable, panic if it is not present
let path = std::env::var(&quot;IMPORTANT_PATH&quot;).unwrap();
</pre>
<p>In the "expect as error message" style we would use expect to describe
that the environment variable was not set when it should have been:</p>
<pre>let path = std::env::var(&quot;IMPORTANT_PATH&quot;)
    .expect(&quot;env variable `IMPORTANT_PATH` is not set&quot;);
</pre>
<p>In the "expect as precondition" style, we would instead describe the
reason we <em>expect</em> the <code>Result</code> should be <code>Ok</code>. With this style we would
prefer to write:</p>
<pre>let path = std::env::var(&quot;IMPORTANT_PATH&quot;)
    .expect(&quot;env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`&quot;);
</pre>
<p>The "expect as error message" style does not work as well with the
default output of the std panic hooks, and often ends up repeating
information that is already communicated by the source error being
unwrapped:</p>
<pre>thread 'main' panicked at src/main.rs:4:6:
env variable `IMPORTANT_PATH` is not set: NotPresent
</pre>
<p>In this example we end up mentioning that an env variable is not set,
followed by our source message that says the env is not present, the
only additional information we're communicating is the name of the
environment variable being checked.</p>
<p>The "expect as precondition" style instead focuses on source code
readability, making it easier to understand what must have gone wrong in
situations where panics are being used to represent bugs exclusively.
Also, by framing our expect in terms of what "SHOULD" have happened to
prevent the source error, we end up introducing new information that is
independent from our source error.</p>
<pre>thread 'main' panicked at src/main.rs:4:6:
env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`: NotPresent
</pre>
<p>In this example we are communicating not only the name of the
environment variable that should have been set, but also an explanation
for why it should have been set, and we let the source error display as
a clear contradiction to our expectation.</p>
<p><strong>Hint</strong>: If you're having trouble remembering how to phrase
expect-as-precondition style error messages remember to focus on the word
"should" as in "env variable should be set by blah" or "the given binary
should be available and executable by the current user".</p>
</section><div class="code-panel"><pre class="code src" data-hl="library/core/src/error.md"><span class="code-line"><a class="ln" id="L1" href="#L1">1</a><span class="code-text">Interfaces for working with Errors.</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"># Error Handling In Rust</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L4" href="#L4">4</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</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="L6" href="#L6">6</a><span class="code-text">representing, reporting, propagating, reacting to, and discarding errors.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L7" href="#L7">7</a><span class="code-text">These responsibilities are collectively known as &quot;error handling.&quot; The</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L8" href="#L8">8</a><span class="code-text">components of the first system, the panic runtime and interfaces, are most</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L9" href="#L9">9</a><span class="code-text">commonly used to represent bugs that have been detected in your program. The</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L10" href="#L10">10</a><span class="code-text">components of the second system, `Result`, the error traits, and user</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L11" href="#L11">11</a><span class="code-text">defined types, are used to represent anticipated runtime failure modes of</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L12" href="#L12">12</a><span class="code-text">your program.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L14" href="#L14">14</a><span class="code-text">## The Panic Interfaces</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L15" href="#L15">15</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L16" href="#L16">16</a><span class="code-text">The following are the primary interfaces of the panic system and the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L17" href="#L17">17</a><span class="code-text">responsibilities they cover:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L18" href="#L18">18</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L19" href="#L19">19</a><span class="code-text">* [`panic!`] and [`panic_any`] (Constructing, Propagated automatically)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L20" href="#L20">20</a><span class="code-text">* [`PanicInfo`] (Reporting)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L21" href="#L21">21</a><span class="code-text">* [`set_hook`], [`take_hook`], and [`#[panic_handler]`][panic-handler] (Reporting)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L22" href="#L22">22</a><span class="code-text">* [`catch_unwind`] and [`resume_unwind`] (Discarding, Propagating)</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">The following are the primary interfaces of the error system and the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L25" href="#L25">25</a><span class="code-text">responsibilities they cover:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L26" href="#L26">26</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L27" href="#L27">27</a><span class="code-text">* [`Result`] (Propagating, Reacting)</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 [`Error`] trait (Reporting)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L29" href="#L29">29</a><span class="code-text">* User defined types (Constructing / Representing)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L30" href="#L30">30</a><span class="code-text">* [`match`] and [`downcast`] (Reacting)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L31" href="#L31">31</a><span class="code-text">* The question mark operator ([`?`]) (Propagating)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L32" href="#L32">32</a><span class="code-text">* The partially stable [`Try`] traits (Propagating, Constructing)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L33" href="#L33">33</a><span class="code-text">* [`Termination`] (Reporting)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L34" href="#L34">34</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L35" href="#L35">35</a><span class="code-text">## Converting Errors into Panics</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L36" href="#L36">36</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L37" href="#L37">37</a><span class="code-text">The panic and error systems are not entirely distinct. Often times errors</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L38" href="#L38">38</a><span class="code-text">that are anticipated runtime failures in an API might instead represent bugs</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L39" href="#L39">39</a><span class="code-text">to a caller. For these situations the standard library provides APIs for</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L40" href="#L40">40</a><span class="code-text">constructing panics with an `Error` as its source.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L41" href="#L41">41</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L42" href="#L42">42</a><span class="code-text">* [`Result::unwrap`]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L43" href="#L43">43</a><span class="code-text">* [`Result::expect`]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L44" href="#L44">44</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L45" href="#L45">45</a><span class="code-text">These functions are equivalent, they either return the inner value if the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L46" href="#L46">46</a><span class="code-text">`Result` is `Ok` or panic if the `Result` is `Err` printing the inner error</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L47" href="#L47">47</a><span class="code-text">as the source. The only difference between them is that with `expect` you</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L48" href="#L48">48</a><span class="code-text">provide a panic error message to be printed alongside the source, whereas</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L49" href="#L49">49</a><span class="code-text">`unwrap` has a default message indicating only that you unwrapped an `Err`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L50" href="#L50">50</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L51" href="#L51">51</a><span class="code-text">Of the two, `expect` is generally preferred since its `msg` field allows you</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L52" href="#L52">52</a><span class="code-text">to convey your intent and assumptions which makes tracking down the source</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L53" href="#L53">53</a><span class="code-text">of a panic easier. `unwrap` on the other hand can still be a good fit in</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L54" href="#L54">54</a><span class="code-text">situations where you can trivially show that a piece of code will never</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L55" href="#L55">55</a><span class="code-text">panic, such as `&quot;127.0.0.1&quot;.parse::&lt;std::net::IpAddr&gt;().unwrap()` or early</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L56" href="#L56">56</a><span class="code-text">prototyping.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L57" href="#L57">57</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L58" href="#L58">58</a><span class="code-text"># Common Message Styles</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L59" href="#L59">59</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L60" href="#L60">60</a><span class="code-text">There are two common styles for how people word `expect` messages. Using</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L61" href="#L61">61</a><span class="code-text">the message to present information to users encountering a panic</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L62" href="#L62">62</a><span class="code-text">(&quot;expect as error message&quot;) or using the message to present information</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L63" href="#L63">63</a><span class="code-text">to developers debugging the panic (&quot;expect as precondition&quot;).</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">In the former case the expect message is used to describe the error that</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L66" href="#L66">66</a><span class="code-text">has occurred which is considered a bug. Consider the following example:</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">```should_panic</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L69" href="#L69">69</a><span class="code-text">// Read environment variable, panic if it is not present</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L70" href="#L70">70</a><span class="code-text">let path = std::env::var(&quot;IMPORTANT_PATH&quot;).unwrap();</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"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L73" href="#L73">73</a><span class="code-text">In the &quot;expect as error message&quot; style we would use expect to describe</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L74" href="#L74">74</a><span class="code-text">that the environment variable was not set when it should have been:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L75" href="#L75">75</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L76" href="#L76">76</a><span class="code-text">```should_panic</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L77" href="#L77">77</a><span class="code-text">let path = std::env::var(&quot;IMPORTANT_PATH&quot;)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L78" href="#L78">78</a><span class="code-text">    .expect(&quot;env variable `IMPORTANT_PATH` is not set&quot;);</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L79" href="#L79">79</a><span class="code-text">```</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 the &quot;expect as precondition&quot; style, we would instead describe the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L82" href="#L82">82</a><span class="code-text">reason we _expect_ the `Result` should be `Ok`. With this style we would</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L83" href="#L83">83</a><span class="code-text">prefer to write:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L84" href="#L84">84</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L85" href="#L85">85</a><span class="code-text">```should_panic</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L86" href="#L86">86</a><span class="code-text">let path = std::env::var(&quot;IMPORTANT_PATH&quot;)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L87" href="#L87">87</a><span class="code-text">    .expect(&quot;env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`&quot;);</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L88" href="#L88">88</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L89" href="#L89">89</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L90" href="#L90">90</a><span class="code-text">The &quot;expect as error message&quot; style does not work as well with the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L91" href="#L91">91</a><span class="code-text">default output of the std panic hooks, and often ends up repeating</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L92" href="#L92">92</a><span class="code-text">information that is already communicated by the source error being</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L93" href="#L93">93</a><span class="code-text">unwrapped:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L94" href="#L94">94</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L95" href="#L95">95</a><span class="code-text">```text</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L96" href="#L96">96</a><span class="code-text">thread 'main' panicked at src/main.rs:4:6:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L97" href="#L97">97</a><span class="code-text">env variable `IMPORTANT_PATH` is not set: NotPresent</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L98" href="#L98">98</a><span class="code-text">```</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 class="code-break">
</span></span><span class="code-line"><a class="ln" id="L100" href="#L100">100</a><span class="code-text">In this example we end up mentioning that an env variable is not set,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L101" href="#L101">101</a><span class="code-text">followed by our source message that says the env is not present, the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L102" href="#L102">102</a><span class="code-text">only additional information we're communicating is the name of the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L103" href="#L103">103</a><span class="code-text">environment variable being checked.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L104" href="#L104">104</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L105" href="#L105">105</a><span class="code-text">The &quot;expect as precondition&quot; style instead focuses on source code</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L106" href="#L106">106</a><span class="code-text">readability, making it easier to understand what must have gone wrong in</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L107" href="#L107">107</a><span class="code-text">situations where panics are being used to represent bugs exclusively.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L108" href="#L108">108</a><span class="code-text">Also, by framing our expect in terms of what &quot;SHOULD&quot; have happened to</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L109" href="#L109">109</a><span class="code-text">prevent the source error, we end up introducing new information that is</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L110" href="#L110">110</a><span class="code-text">independent from our source error.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L111" href="#L111">111</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L112" href="#L112">112</a><span class="code-text">```text</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L113" href="#L113">113</a><span class="code-text">thread 'main' panicked at src/main.rs:4:6:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L114" href="#L114">114</a><span class="code-text">env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`: NotPresent</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L115" href="#L115">115</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L116" href="#L116">116</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L117" href="#L117">117</a><span class="code-text">In this example we are communicating not only the name of the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L118" href="#L118">118</a><span class="code-text">environment variable that should have been set, but also an explanation</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L119" href="#L119">119</a><span class="code-text">for why it should have been set, and we let the source error display as</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L120" href="#L120">120</a><span class="code-text">a clear contradiction to our expectation.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L121" href="#L121">121</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L122" href="#L122">122</a><span class="code-text">**Hint**: If you're having trouble remembering how to phrase</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L123" href="#L123">123</a><span class="code-text">expect-as-precondition style error messages remember to focus on the word</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L124" href="#L124">124</a><span class="code-text">&quot;should&quot; as in &quot;env variable should be set by blah&quot; or &quot;the given binary</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L125" href="#L125">125</a><span class="code-text">should be available and executable by the current user&quot;.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L126" href="#L126">126</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L127" href="#L127">127</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="L128" href="#L128">128</a><span class="code-text">[`PanicInfo`]: crate::panic::PanicInfo</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L129" href="#L129">129</a><span class="code-text">[`catch_unwind`]: ../../std/panic/fn.catch_unwind.html</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L130" href="#L130">130</a><span class="code-text">[`resume_unwind`]: ../../std/panic/fn.resume_unwind.html</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L131" href="#L131">131</a><span class="code-text">[`downcast`]: crate::error::Error</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L132" href="#L132">132</a><span class="code-text">[`Termination`]: ../../std/process/trait.Termination.html</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L133" href="#L133">133</a><span class="code-text">[`Try`]: crate::ops::Try</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L134" href="#L134">134</a><span class="code-text">[panic hook]: ../../std/panic/fn.set_hook.html</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L135" href="#L135">135</a><span class="code-text">[`set_hook`]: ../../std/panic/fn.set_hook.html</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L136" href="#L136">136</a><span class="code-text">[`take_hook`]: ../../std/panic/fn.take_hook.html</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L137" href="#L137">137</a><span class="code-text">[panic-handler]: &lt;https://doc.rust-lang.org/nomicon/panic-handler.html&gt;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L138" href="#L138">138</a><span class="code-text">[`match`]: ../../std/keyword.match.html</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L139" href="#L139">139</a><span class="code-text">[`?`]: ../../std/result/index.html#the-question-mark-operator-</span></span></pre></div></div>
</main>
</body>
</html>
