pierre/RustBook
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
master
RustBook/ch09-03-to-panic-or-not-to-panic.html

440 lines
40 KiB
HTML
Raw Permalink Normal View History

Initial commit
2020-01-06 20:57:15 +00:00
<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js light">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>To panic! or Not To panic! - The Rust Programming Language</title>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff" />
<link rel="shortcut icon" href="favicon.png">
<link rel="stylesheet" href="css/variables.css">
<link rel="stylesheet" href="css/general.css">
<link rel="stylesheet" href="css/chrome.css">
<link rel="stylesheet" href="css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
<link href="googleFonts/css.css" rel="stylesheet" type="text/css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" href="highlight.css">
<link rel="stylesheet" href="tomorrow-night.css">
<link rel="stylesheet" href="ayu-highlight.css">
<!-- Custom theme stylesheets -->
<link rel="stylesheet" href="ferris.css">
<link rel="stylesheet" href="theme/2018-edition.css">
</head>
<body>
<!-- Provide site root to javascript -->
<script type="text/javascript">
var path_to_root = "";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "light" : "light";
</script>
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script type="text/javascript">
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script type="text/javascript">
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
var html = document.querySelector('html');
html.classList.remove('no-js')
html.classList.remove('light')
html.classList.add(theme);
html.classList.add('js');
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script type="text/javascript">
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div id="sidebar-scrollbox" class="sidebar-scrollbox">
<ol class="chapter"><li class="expanded affix "><a href="title-page.html">The Rust Programming Language</a></li><li class="expanded affix "><a href="foreword.html">Foreword</a></li><li class="expanded affix "><a href="ch00-00-introduction.html">Introduction</a></li><li class="expanded "><a href="ch01-00-getting-started.html"><strong aria-hidden="true">1.</strong> Getting Started</a></li><li><ol class="section"><li class="expanded "><a href="ch01-01-installation.html"><strong aria-hidden="true">1.1.</strong> Installation</a></li><li class="expanded "><a href="ch01-02-hello-world.html"><strong aria-hidden="true">1.2.</strong> Hello, World!</a></li><li class="expanded "><a href="ch01-03-hello-cargo.html"><strong aria-hidden="true">1.3.</strong> Hello, Cargo!</a></li></ol></li><li class="expanded "><a href="ch02-00-guessing-game-tutorial.html"><strong aria-hidden="true">2.</strong> Programming a Guessing Game</a></li><li class="expanded "><a href="ch03-00-common-programming-concepts.html"><strong aria-hidden="true">3.</strong> Common Programming Concepts</a></li><li><ol class="section"><li class="expanded "><a href="ch03-01-variables-and-mutability.html"><strong aria-hidden="true">3.1.</strong> Variables and Mutability</a></li><li class="expanded "><a href="ch03-02-data-types.html"><strong aria-hidden="true">3.2.</strong> Data Types</a></li><li class="expanded "><a href="ch03-03-how-functions-work.html"><strong aria-hidden="true">3.3.</strong> Functions</a></li><li class="expanded "><a href="ch03-04-comments.html"><strong aria-hidden="true">3.4.</strong> Comments</a></li><li class="expanded "><a href="ch03-05-control-flow.html"><strong aria-hidden="true">3.5.</strong> Control Flow</a></li></ol></li><li class="expanded "><a href="ch04-00-understanding-ownership.html"><strong aria-hidden="true">4.</strong> Understanding Ownership</a></li><li><ol class="section"><li class="expanded "><a href="ch04-01-what-is-ownership.html"><strong aria-hidden="true">4.1.</strong> What is Ownership?</a></li><li class="expanded "><a href="ch04-02-references-and-borrowing.html"><strong aria-hidden="true">4.2.</strong> References and Borrowing</a></li><li class="expanded "><a href="ch04-03-slices.html"><strong aria-hidden="true">4.3.</strong> The Slice Type</a></li></ol></li><li class="expanded "><a href="ch05-00-structs.html"><strong aria-hidden="true">5.</strong> Using Structs to Structure Related Data</a></li><li><ol class="section"><li class="expanded "><a href="ch05-01-defining-structs.html"><strong aria-hidden="true">5.1.</strong> Defining and Instantiating Structs</a></li><li class="expanded "><a href="ch05-02-example-structs.html"><strong aria-hidden="true">5.2.</strong> An Example Program Using Structs</a></li><li class="expanded "><a href="ch05-03-method-syntax.html"><strong aria-hidden="true">5.3.</strong> Method Syntax</a></li></ol></li><li class="expanded "><a href="ch06-00-enums.html"><strong aria-hidden="true">6.</strong> Enums and Pattern Matching</a></li><li><ol class="section"><li class="expanded "><a href="ch06-01-defining-an-enum.html"><strong aria-hidden="true">6.1.</strong> Defining an Enum</a></li><li class="expanded "><a href="ch06-02-match.html"><strong aria-hidden="true">6.2.</strong> The match Control Flow Operator</a></li><li class="expanded "><a href="ch06-03-if-let.html"><strong aria-hidden="true">6.3.</strong> Concise Control Flow with if let</a></li></ol></li><li class="expanded "><a href="ch07-00-managing-growing-projects-with-packages-crates-and-modules.html"><strong aria-hidden="true">7.</strong> Managing Growing Projects with Packages, Crates, and Modules</a></li><li><ol class="section"><li class="expanded "><a href="ch07-01-packages-and-crates.html"><strong aria-hidden="true">7.1.</strong> Packages and Crates</a></li><li class="expanded "><a href="ch07-02-defining-modules-to-control-scope-and-privacy.html"><strong aria-hidden="true">7.2.</strong> Defining Modules to Control Scope and Privacy</a></li><li class="expanded "><a href="ch07-03-paths-for-referring-to-an-item-in-the-module-tree.html"><
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar" class="menu-bar">
<div id="menu-bar-sticky-container">
<div class="left-buttons">
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</button>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">The Rust Programming Language</h1>
<div class="right-buttons">
<a href="print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
</div>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" name="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script type="text/javascript">
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<h2><a class="header" href="#to-panic-or-not-to-panic" id="to-panic-or-not-to-panic">To <code>panic!</code> or Not to <code>panic!</code></a></h2>
<p>So how do you decide when you should call <code>panic!</code> and when you should return
<code>Result</code>? When code panics, there’s no way to recover. You could call <code>panic!</code>
for any error situation, whether there’s a possible way to recover or not, but
then you’re making the decision on behalf of the code calling your code that a
situation is unrecoverable. When you choose to return a <code>Result</code> value, you
give the calling code options rather than making the decision for it. The
calling code could choose to attempt to recover in a way that’s appropriate for
its situation, or it could decide that an <code>Err</code> value in this case is
unrecoverable, so it can call <code>panic!</code> and turn your recoverable error into an
unrecoverable one. Therefore, returning <code>Result</code> is a good default choice when
you’re defining a function that might fail.</p>
<p>In rare situations, it’s more appropriate to write code that panics instead of
returning a <code>Result</code>. Let’s explore why it’s appropriate to panic in examples,
prototype code, and tests. Then we’ll discuss situations in which the compiler
can’t tell that failure is impossible, but you as a human can. The chapter will
conclude with some general guidelines on how to decide whether to panic in
library code.</p>
<h3><a class="header" href="#examples-prototype-code-and-tests" id="examples-prototype-code-and-tests">Examples, Prototype Code, and Tests</a></h3>
<p>When you’re writing an example to illustrate some concept, having robust
error-handling code in the example as well can make the example less clear. In
examples, it’s understood that a call to a method like <code>unwrap</code> that could
panic is meant as a placeholder for the way you’d want your application to
handle errors, which can differ based on what the rest of your code is doing.</p>
<p>Similarly, the <code>unwrap</code> and <code>expect</code> methods are very handy when prototyping,
before you’re ready to decide how to handle errors. They leave clear markers in
your code for when you’re ready to make your program more robust.</p>
<p>If a method call fails in a test, you’d want the whole test to fail, even if
that method isn’t the functionality under test. Because <code>panic!</code> is how a test
is marked as a failure, calling <code>unwrap</code> or <code>expect</code> is exactly what should
happen.</p>
<h3><a class="header" href="#cases-in-which-you-have-more-information-than-the-compiler" id="cases-in-which-you-have-more-information-than-the-compiler">Cases in Which You Have More Information Than the Compiler</a></h3>
<p>It would also be appropriate to call <code>unwrap</code> when you have some other logic
that ensures the <code>Result</code> will have an <code>Ok</code> value, but the logic isn’t
something the compiler understands. You’ll still have a <code>Result</code> value that you
need to handle: whatever operation you’re calling still has the possibility of
failing in general, even though it’s logically impossible in your particular
situation. If you can ensure by manually inspecting the code that you’ll never
have an <code>Err</code> variant, it’s perfectly acceptable to call <code>unwrap</code>. Here’s an
example:</p>
<pre><pre class="playpen"><code class="language-rust">
<span class="boring">#![allow(unused_variables)]
</span><span class="boring">fn main() {
</span>use std::net::IpAddr;
let home: IpAddr = &quot;127.0.0.1&quot;.parse().unwrap();
<span class="boring">}
</span></code></pre></pre>
<p>We’re creating an <code>IpAddr</code> instance by parsing a hardcoded string. We can see
that <code>127.0.0.1</code> is a valid IP address, so it’s acceptable to use <code>unwrap</code>
here. However, having a hardcoded, valid string doesn’t change the return type
of the <code>parse</code> method: we still get a <code>Result</code> value, and the compiler will
still make us handle the <code>Result</code> as if the <code>Err</code> variant is a possibility
because the compiler isn’t smart enough to see that this string is always a
valid IP address. If the IP address string came from a user rather than being
hardcoded into the program and therefore <em>did</em> have a possibility of failure,
we’d definitely want to handle the <code>Result</code> in a more robust way instead.</p>
<h3><a class="header" href="#guidelines-for-error-handling" id="guidelines-for-error-handling">Guidelines for Error Handling</a></h3>
<p>It’s advisable to have your code panic when it’s possible that your code
could end up in a bad state. In this context, a <em>bad state</em> is when some
assumption, guarantee, contract, or invariant has been broken, such as when
invalid values, contradictory values, or missing values are passed to your
code—plus one or more of the following:</p>
<ul>
<li>The bad state is not something that’s <em>expected</em> to happen occasionally.</li>
<li>Your code after this point needs to rely on not being in this bad state.</li>
<li>There’s not a good way to encode this information in the types you use.</li>
</ul>
<p>If someone calls your code and passes in values that don’t make sense, the best
choice might be to call <code>panic!</code> and alert the person using your library to the
bug in their code so they can fix it during development. Similarly, <code>panic!</code> is
often appropriate if you’re calling external code that is out of your control
and it returns an invalid state that you have no way of fixing.</p>
<p>However, when failure is expected, it’s more appropriate to return a <code>Result</code>
than to make a <code>panic!</code> call. Examples include a parser being given malformed
data or an HTTP request returning a status that indicates you have hit a rate
limit. In these cases, returning a <code>Result</code> indicates that failure is an
expected possibility that the calling code must decide how to handle.</p>
<p>When your code performs operations on values, your code should verify the
values are valid first and panic if the values aren’t valid. This is mostly for
safety reasons: attempting to operate on invalid data can expose your code to
vulnerabilities. This is the main reason the standard library will call
<code>panic!</code> if you attempt an out-of-bounds memory access: trying to access memory
that doesn’t belong to the current data structure is a common security problem.
Functions often have <em>contracts</em>: their behavior is only guaranteed if the
inputs meet particular requirements. Panicking when the contract is violated
makes sense because a contract violation always indicates a caller-side bug and
it’s not a kind of error you want the calling code to have to explicitly
handle. In fact, there’s no reasonable way for calling code to recover; the
calling <em>programmers</em> need to fix the code. Contracts for a function,
especially when a violation will cause a panic, should be explained in the API
documentation for the function.</p>
<p>However, having lots of error checks in all of your functions would be verbose
and annoying. Fortunately, you can use Rust’s type system (and thus the type
checking the compiler does) to do many of the checks for you. If your function
has a particular type as a parameter, you can proceed with your code’s logic
knowing that the compiler has already ensured you have a valid value. For
example, if you have a type rather than an <code>Option</code>, your program expects to
have <em>something</em> rather than <em>nothing</em>. Your code then doesn’t have to handle
two cases for the <code>Some</code> and <code>None</code> variants: it will only have one case for
definitely having a value. Code trying to pass nothing to your function won’t
even compile, so your function doesn’t have to check for that case at runtime.
Another example is using an unsigned integer type such as <code>u32</code>, which ensures
the parameter is never negative.</p>
<h3><a class="header" href="#creating-custom-types-for-validation" id="creating-custom-types-for-validation">Creating Custom Types for Validation</a></h3>
<p>Let’s take the idea of using Rust’s type system to ensure we have a valid value
one step further and look at creating a custom type for validation. Recall the
guessing game in Chapter 2 in which our code asked the user to guess a number
between 1 and 100. We never validated that the user’s guess was between those
numbers before checking it against our secret number; we only validated that
the guess was positive. In this case, the consequences were not very dire: our
output of “Too high” or “Too low” would still be correct. But it would be a
useful enhancement to guide the user toward valid guesses and have different
behavior when a user guesses a number that’s out of range versus when a user
types, for example, letters instead.</p>
<p>One way to do this would be to parse the guess as an <code>i32</code> instead of only a
<code>u32</code> to allow potentially negative numbers, and then add a check for the
number being in range, like so:</p>
<pre><code class="language-rust ignore">loop {
// --snip--
let guess: i32 = match guess.trim().parse() {
Ok(num) =&gt; num,
Err(_) =&gt; continue,
};
if guess &lt; 1 || guess &gt; 100 {
println!(&quot;The secret number will be between 1 and 100.&quot;);
continue;
}
match guess.cmp(&amp;secret_number) {
// --snip--
}
</code></pre>
<p>The <code>if</code> expression checks whether our value is out of range, tells the user
about the problem, and calls <code>continue</code> to start the next iteration of the loop
and ask for another guess. After the <code>if</code> expression, we can proceed with the
comparisons between <code>guess</code> and the secret number knowing that <code>guess</code> is
between 1 and 100.</p>
<p>However, this is not an ideal solution: if it was absolutely critical that the
program only operated on values between 1 and 100, and it had many functions
with this requirement, having a check like this in every function would be
tedious (and might impact performance).</p>
<p>Instead, we can make a new type and put the validations in a function to create
an instance of the type rather than repeating the validations everywhere. That
way, it’s safe for functions to use the new type in their signatures and
confidently use the values they receive. Listing 9-10 shows one way to define a
<code>Guess</code> type that will only create an instance of <code>Guess</code> if the <code>new</code> function
receives a value between 1 and 100.</p>
<pre><pre class="playpen"><code class="language-rust">
<span class="boring">#![allow(unused_variables)]
</span><span class="boring">fn main() {
</span>pub struct Guess {
value: i32,
}
impl Guess {
pub fn new(value: i32) -&gt; Guess {
if value &lt; 1 || value &gt; 100 {
panic!(&quot;Guess value must be between 1 and 100, got {}.&quot;, value);
}
Guess {
value
}
}
pub fn value(&amp;self) -&gt; i32 {
self.value
}
}
<span class="boring">}
</span></code></pre></pre>
<p><span class="caption">Listing 9-10: A <code>Guess</code> type that will only continue with
values between 1 and 100</span></p>
<p>First, we define a struct named <code>Guess</code> that has a field named <code>value</code> that
holds an <code>i32</code>. This is where the number will be stored.</p>
<p>Then we implement an associated function named <code>new</code> on <code>Guess</code> that creates
instances of <code>Guess</code> values. The <code>new</code> function is defined to have one
parameter named <code>value</code> of type <code>i32</code> and to return a <code>Guess</code>. The code in the
body of the <code>new</code> function tests <code>value</code> to make sure it’s between 1 and 100.
If <code>value</code> doesn’t pass this test, we make a <code>panic!</code> call, which will alert
the programmer who is writing the calling code that they have a bug they need
to fix, because creating a <code>Guess</code> with a <code>value</code> outside this range would
violate the contract that <code>Guess::new</code> is relying on. The conditions in which
<code>Guess::new</code> might panic should be discussed in its public-facing API
documentation; we’ll cover documentation conventions indicating the possibility
of a <code>panic!</code> in the API documentation that you create in Chapter 14. If
<code>value</code> does pass the test, we create a new <code>Guess</code> with its <code>value</code> field set
to the <code>value</code> parameter and return the <code>Guess</code>.</p>
<p>Next, we implement a method named <code>value</code> that borrows <code>self</code>, doesn’t have any
other parameters, and returns an <code>i32</code>. This kind of method is sometimes called
a <em>getter</em>, because its purpose is to get some data from its fields and return
it. This public method is necessary because the <code>value</code> field of the <code>Guess</code>
struct is private. It’s important that the <code>value</code> field be private so code
using the <code>Guess</code> struct is not allowed to set <code>value</code> directly: code outside
the module <em>must</em> use the <code>Guess::new</code> function to create an instance of
<code>Guess</code>, thereby ensuring there’s no way for a <code>Guess</code> to have a <code>value</code> that
hasn’t been checked by the conditions in the <code>Guess::new</code> function.</p>
<p>A function that has a parameter or returns only numbers between 1 and 100 could
then declare in its signature that it takes or returns a <code>Guess</code> rather than an
<code>i32</code> and wouldn’t need to do any additional checks in its body.</p>
<h2><a class="header" href="#summary" id="summary">Summary</a></h2>
<p>Rust’s error handling features are designed to help you write more robust code.
The <code>panic!</code> macro signals that your program is in a state it can’t handle and
lets you tell the process to stop instead of trying to proceed with invalid or
incorrect values. The <code>Result</code> enum uses Rust’s type system to indicate that
operations might fail in a way that your code could recover from. You can use
<code>Result</code> to tell code that calls your code that it needs to handle potential
success or failure as well. Using <code>panic!</code> and <code>Result</code> in the appropriate
situations will make your code more reliable in the face of inevitable problems.</p>
<p>Now that you’ve seen useful ways that the standard library uses generics with
the <code>Option</code> and <code>Result</code> enums, we’ll talk about how generics work and how you
can use them in your code.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="ch09-02-recoverable-errors-with-result.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next" href="ch10-00-generics.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
<a href="ch09-02-recoverable-errors-with-result.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a href="ch10-00-generics.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
</div>
<script type="text/javascript">
window.playpen_copyable = true;
</script>
<script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
<script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
<script src="searcher.js" type="text/javascript" charset="utf-8"></script>
<script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
<script src="highlight.js" type="text/javascript" charset="utf-8"></script>
<script src="book.js" type="text/javascript" charset="utf-8"></script>
<!-- Custom JS scripts -->
<script type="text/javascript" src="ferris.js"></script>
</body>
</html>
Reference in New Issue Copy Permalink