487 lines
39 KiB
HTML
487 lines
39 KiB
HTML
|
<!DOCTYPE HTML>
|
|||
|
<html lang="en" class="sidebar-visible no-js light">
|
|||
|
<head>
|
|||
|
<!-- Book generated using mdBook -->
|
|||
|
<meta charset="UTF-8">
|
|||
|
<title>The match Control Flow Operator - 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" class="active"><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-modu
|
|||
|
</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="#the-match-control-flow-operator" id="the-match-control-flow-operator">The <code>match</code> Control Flow Operator</a></h2>
|
|||
|
<p>Rust has an extremely powerful control flow operator called <code>match</code> that allows
|
|||
|
you to compare a value against a series of patterns and then execute code based
|
|||
|
on which pattern matches. Patterns can be made up of literal values, variable
|
|||
|
names, wildcards, and many other things; Chapter 18 covers all the different
|
|||
|
kinds of patterns and what they do. The power of <code>match</code> comes from the
|
|||
|
expressiveness of the patterns and the fact that the compiler confirms that all
|
|||
|
possible cases are handled.</p>
|
|||
|
<p>Think of a <code>match</code> expression as being like a coin-sorting machine: coins slide
|
|||
|
down a track with variously sized holes along it, and each coin falls through
|
|||
|
the first hole it encounters that it fits into. In the same way, values go
|
|||
|
through each pattern in a <code>match</code>, and at the first pattern the value “fits,”
|
|||
|
the value falls into the associated code block to be used during execution.</p>
|
|||
|
<p>Because we just mentioned coins, let’s use them as an example using <code>match</code>! We
|
|||
|
can write a function that can take an unknown United States coin and, in a
|
|||
|
similar way as the counting machine, determine which coin it is and return its
|
|||
|
value in cents, as shown here in Listing 6-3.</p>
|
|||
|
<pre><pre class="playpen"><code class="language-rust">
|
|||
|
<span class="boring">#![allow(unused_variables)]
|
|||
|
</span><span class="boring">fn main() {
|
|||
|
</span>enum Coin {
|
|||
|
Penny,
|
|||
|
Nickel,
|
|||
|
Dime,
|
|||
|
Quarter,
|
|||
|
}
|
|||
|
|
|||
|
fn value_in_cents(coin: Coin) -> u8 {
|
|||
|
match coin {
|
|||
|
Coin::Penny => 1,
|
|||
|
Coin::Nickel => 5,
|
|||
|
Coin::Dime => 10,
|
|||
|
Coin::Quarter => 25,
|
|||
|
}
|
|||
|
}
|
|||
|
<span class="boring">}
|
|||
|
</span></code></pre></pre>
|
|||
|
<p><span class="caption">Listing 6-3: An enum and a <code>match</code> expression that has
|
|||
|
the variants of the enum as its patterns</span></p>
|
|||
|
<p>Let’s break down the <code>match</code> in the <code>value_in_cents</code> function. First, we list
|
|||
|
the <code>match</code> keyword followed by an expression, which in this case is the value
|
|||
|
<code>coin</code>. This seems very similar to an expression used with <code>if</code>, but there’s a
|
|||
|
big difference: with <code>if</code>, the expression needs to return a Boolean value, but
|
|||
|
here, it can be any type. The type of <code>coin</code> in this example is the <code>Coin</code> enum
|
|||
|
that we defined on line 1.</p>
|
|||
|
<p>Next are the <code>match</code> arms. An arm has two parts: a pattern and some code. The
|
|||
|
first arm here has a pattern that is the value <code>Coin::Penny</code> and then the <code>=></code>
|
|||
|
operator that separates the pattern and the code to run. The code in this case
|
|||
|
is just the value <code>1</code>. Each arm is separated from the next with a comma.</p>
|
|||
|
<p>When the <code>match</code> expression executes, it compares the resulting value against
|
|||
|
the pattern of each arm, in order. If a pattern matches the value, the code
|
|||
|
associated with that pattern is executed. If that pattern doesn’t match the
|
|||
|
value, execution continues to the next arm, much as in a coin-sorting machine.
|
|||
|
We can have as many arms as we need: in Listing 6-3, our <code>match</code> has four arms.</p>
|
|||
|
<p>The code associated with each arm is an expression, and the resulting value of
|
|||
|
the expression in the matching arm is the value that gets returned for the
|
|||
|
entire <code>match</code> expression.</p>
|
|||
|
<p>Curly brackets typically aren’t used if the match arm code is short, as it is
|
|||
|
in Listing 6-3 where each arm just returns a value. If you want to run multiple
|
|||
|
lines of code in a match arm, you can use curly brackets. For example, the
|
|||
|
following code would print “Lucky penny!” every time the method was called with
|
|||
|
a <code>Coin::Penny</code> but would still return the last value of the block, <code>1</code>:</p>
|
|||
|
<pre><pre class="playpen"><code class="language-rust">
|
|||
|
<span class="boring">#![allow(unused_variables)]
|
|||
|
</span><span class="boring">fn main() {
|
|||
|
</span><span class="boring">enum Coin {
|
|||
|
</span><span class="boring"> Penny,
|
|||
|
</span><span class="boring"> Nickel,
|
|||
|
</span><span class="boring"> Dime,
|
|||
|
</span><span class="boring"> Quarter,
|
|||
|
</span><span class="boring">}
|
|||
|
</span><span class="boring">
|
|||
|
</span>fn value_in_cents(coin: Coin) -> u8 {
|
|||
|
match coin {
|
|||
|
Coin::Penny => {
|
|||
|
println!("Lucky penny!");
|
|||
|
1
|
|||
|
},
|
|||
|
Coin::Nickel => 5,
|
|||
|
Coin::Dime => 10,
|
|||
|
Coin::Quarter => 25,
|
|||
|
}
|
|||
|
}
|
|||
|
<span class="boring">}
|
|||
|
</span></code></pre></pre>
|
|||
|
<h3><a class="header" href="#patterns-that-bind-to-values" id="patterns-that-bind-to-values">Patterns that Bind to Values</a></h3>
|
|||
|
<p>Another useful feature of match arms is that they can bind to the parts of the
|
|||
|
values that match the pattern. This is how we can extract values out of enum
|
|||
|
variants.</p>
|
|||
|
<p>As an example, let’s change one of our enum variants to hold data inside it.
|
|||
|
From 1999 through 2008, the United States minted quarters with different
|
|||
|
designs for each of the 50 states on one side. No other coins got state
|
|||
|
designs, so only quarters have this extra value. We can add this information to
|
|||
|
our <code>enum</code> by changing the <code>Quarter</code> variant to include a <code>UsState</code> value stored
|
|||
|
inside it, which we’ve done here in Listing 6-4.</p>
|
|||
|
<pre><pre class="playpen"><code class="language-rust">
|
|||
|
<span class="boring">#![allow(unused_variables)]
|
|||
|
</span><span class="boring">fn main() {
|
|||
|
</span>#[derive(Debug)] // so we can inspect the state in a minute
|
|||
|
enum UsState {
|
|||
|
Alabama,
|
|||
|
Alaska,
|
|||
|
// --snip--
|
|||
|
}
|
|||
|
|
|||
|
enum Coin {
|
|||
|
Penny,
|
|||
|
Nickel,
|
|||
|
Dime,
|
|||
|
Quarter(UsState),
|
|||
|
}
|
|||
|
<span class="boring">}
|
|||
|
</span></code></pre></pre>
|
|||
|
<p><span class="caption">Listing 6-4: A <code>Coin</code> enum in which the <code>Quarter</code> variant
|
|||
|
also holds a <code>UsState</code> value</span></p>
|
|||
|
<p>Let’s imagine that a friend of ours is trying to collect all 50 state quarters.
|
|||
|
While we sort our loose change by coin type, we’ll also call out the name of
|
|||
|
the state associated with each quarter so if it’s one our friend doesn’t have,
|
|||
|
they can add it to their collection.</p>
|
|||
|
<p>In the match expression for this code, we add a variable called <code>state</code> to the
|
|||
|
pattern that matches values of the variant <code>Coin::Quarter</code>. When a
|
|||
|
<code>Coin::Quarter</code> matches, the <code>state</code> variable will bind to the value of that
|
|||
|
quarter’s state. Then we can use <code>state</code> in the code for that arm, like so:</p>
|
|||
|
<pre><pre class="playpen"><code class="language-rust">
|
|||
|
<span class="boring">#![allow(unused_variables)]
|
|||
|
</span><span class="boring">fn main() {
|
|||
|
</span><span class="boring">#[derive(Debug)]
|
|||
|
</span><span class="boring">enum UsState {
|
|||
|
</span><span class="boring"> Alabama,
|
|||
|
</span><span class="boring"> Alaska,
|
|||
|
</span><span class="boring">}
|
|||
|
</span><span class="boring">
|
|||
|
</span><span class="boring">enum Coin {
|
|||
|
</span><span class="boring"> Penny,
|
|||
|
</span><span class="boring"> Nickel,
|
|||
|
</span><span class="boring"> Dime,
|
|||
|
</span><span class="boring"> Quarter(UsState),
|
|||
|
</span><span class="boring">}
|
|||
|
</span><span class="boring">
|
|||
|
</span>fn value_in_cents(coin: Coin) -> u8 {
|
|||
|
match coin {
|
|||
|
Coin::Penny => 1,
|
|||
|
Coin::Nickel => 5,
|
|||
|
Coin::Dime => 10,
|
|||
|
Coin::Quarter(state) => {
|
|||
|
println!("State quarter from {:?}!", state);
|
|||
|
25
|
|||
|
},
|
|||
|
}
|
|||
|
}
|
|||
|
<span class="boring">}
|
|||
|
</span></code></pre></pre>
|
|||
|
<p>If we were to call <code>value_in_cents(Coin::Quarter(UsState::Alaska))</code>, <code>coin</code>
|
|||
|
would be <code>Coin::Quarter(UsState::Alaska)</code>. When we compare that value with each
|
|||
|
of the match arms, none of them match until we reach <code>Coin::Quarter(state)</code>. At
|
|||
|
that point, the binding for <code>state</code> will be the value <code>UsState::Alaska</code>. We can
|
|||
|
then use that binding in the <code>println!</code> expression, thus getting the inner
|
|||
|
state value out of the <code>Coin</code> enum variant for <code>Quarter</code>.</p>
|
|||
|
<h3><a class="header" href="#matching-with-optiont" id="matching-with-optiont">Matching with <code>Option<T></code></a></h3>
|
|||
|
<p>In the previous section, we wanted to get the inner <code>T</code> value out of the <code>Some</code>
|
|||
|
case when using <code>Option<T></code>; we can also handle <code>Option<T></code> using <code>match</code> as we
|
|||
|
did with the <code>Coin</code> enum! Instead of comparing coins, we’ll compare the
|
|||
|
variants of <code>Option<T></code>, but the way that the <code>match</code> expression works remains
|
|||
|
the same.</p>
|
|||
|
<p>Let’s say we want to write a function that takes an <code>Option<i32></code> and, if
|
|||
|
there’s a value inside, adds 1 to that value. If there isn’t a value inside,
|
|||
|
the function should return the <code>None</code> value and not attempt to perform any
|
|||
|
operations.</p>
|
|||
|
<p>This function is very easy to write, thanks to <code>match</code>, and will look like
|
|||
|
Listing 6-5.</p>
|
|||
|
<pre><pre class="playpen"><code class="language-rust">
|
|||
|
<span class="boring">#![allow(unused_variables)]
|
|||
|
</span><span class="boring">fn main() {
|
|||
|
</span>fn plus_one(x: Option<i32>) -> Option<i32> {
|
|||
|
match x {
|
|||
|
None => None,
|
|||
|
Some(i) => Some(i + 1),
|
|||
|
}
|
|||
|
}
|
|||
|
|
|||
|
let five = Some(5);
|
|||
|
let six = plus_one(five);
|
|||
|
let none = plus_one(None);
|
|||
|
<span class="boring">}
|
|||
|
</span></code></pre></pre>
|
|||
|
<p><span class="caption">Listing 6-5: A function that uses a <code>match</code> expression on
|
|||
|
an <code>Option<i32></code></span></p>
|
|||
|
<p>Let’s examine the first execution of <code>plus_one</code> in more detail. When we call
|
|||
|
<code>plus_one(five)</code>, the variable <code>x</code> in the body of <code>plus_one</code> will have the
|
|||
|
value <code>Some(5)</code>. We then compare that against each match arm.</p>
|
|||
|
<pre><code class="language-rust ignore">None => None,
|
|||
|
</code></pre>
|
|||
|
<p>The <code>Some(5)</code> value doesn’t match the pattern <code>None</code>, so we continue to the
|
|||
|
next arm.</p>
|
|||
|
<pre><code class="language-rust ignore">Some(i) => Some(i + 1),
|
|||
|
</code></pre>
|
|||
|
<p>Does <code>Some(5)</code> match <code>Some(i)</code>? Why yes it does! We have the same variant. The
|
|||
|
<code>i</code> binds to the value contained in <code>Some</code>, so <code>i</code> takes the value <code>5</code>. The
|
|||
|
code in the match arm is then executed, so we add 1 to the value of <code>i</code> and
|
|||
|
create a new <code>Some</code> value with our total <code>6</code> inside.</p>
|
|||
|
<p>Now let’s consider the second call of <code>plus_one</code> in Listing 6-5, where <code>x</code> is
|
|||
|
<code>None</code>. We enter the <code>match</code> and compare to the first arm.</p>
|
|||
|
<pre><code class="language-rust ignore">None => None,
|
|||
|
</code></pre>
|
|||
|
<p>It matches! There’s no value to add to, so the program stops and returns the
|
|||
|
<code>None</code> value on the right side of <code>=></code>. Because the first arm matched, no other
|
|||
|
arms are compared.</p>
|
|||
|
<p>Combining <code>match</code> and enums is useful in many situations. You’ll see this
|
|||
|
pattern a lot in Rust code: <code>match</code> against an enum, bind a variable to the
|
|||
|
data inside, and then execute code based on it. It’s a bit tricky at first, but
|
|||
|
once you get used to it, you’ll wish you had it in all languages. It’s
|
|||
|
consistently a user favorite.</p>
|
|||
|
<h3><a class="header" href="#matches-are-exhaustive" id="matches-are-exhaustive">Matches Are Exhaustive</a></h3>
|
|||
|
<p>There’s one other aspect of <code>match</code> we need to discuss. Consider this version
|
|||
|
of our <code>plus_one</code> function that has a bug and won’t compile:</p>
|
|||
|
<pre><code class="language-rust ignore does_not_compile">fn plus_one(x: Option<i32>) -> Option<i32> {
|
|||
|
match x {
|
|||
|
Some(i) => Some(i + 1),
|
|||
|
}
|
|||
|
}
|
|||
|
</code></pre>
|
|||
|
<p>We didn’t handle the <code>None</code> case, so this code will cause a bug. Luckily, it’s
|
|||
|
a bug Rust knows how to catch. If we try to compile this code, we’ll get this
|
|||
|
error:</p>
|
|||
|
<pre><code class="language-text">error[E0004]: non-exhaustive patterns: `None` not covered
|
|||
|
-->
|
|||
|
|
|
|||
|
6 | match x {
|
|||
|
| ^ pattern `None` not covered
|
|||
|
</code></pre>
|
|||
|
<p>Rust knows that we didn’t cover every possible case and even knows which
|
|||
|
pattern we forgot! Matches in Rust are <em>exhaustive</em>: we must exhaust every last
|
|||
|
possibility in order for the code to be valid. Especially in the case of
|
|||
|
<code>Option<T></code>, when Rust prevents us from forgetting to explicitly handle the
|
|||
|
<code>None</code> case, it protects us from assuming that we have a value when we might
|
|||
|
have null, thus making the billion-dollar mistake discussed earlier.</p>
|
|||
|
<h3><a class="header" href="#the-_-placeholder" id="the-_-placeholder">The <code>_</code> Placeholder</a></h3>
|
|||
|
<p>Rust also has a pattern we can use when we don’t want to list all possible
|
|||
|
values. For example, a <code>u8</code> can have valid values of 0 through 255. If we only
|
|||
|
care about the values 1, 3, 5, and 7, we don’t want to have to list out 0, 2,
|
|||
|
4, 6, 8, 9 all the way up to 255. Fortunately, we don’t have to: we can use the
|
|||
|
special pattern <code>_</code> instead:</p>
|
|||
|
<pre><pre class="playpen"><code class="language-rust">
|
|||
|
<span class="boring">#![allow(unused_variables)]
|
|||
|
</span><span class="boring">fn main() {
|
|||
|
</span>let some_u8_value = 0u8;
|
|||
|
match some_u8_value {
|
|||
|
1 => println!("one"),
|
|||
|
3 => println!("three"),
|
|||
|
5 => println!("five"),
|
|||
|
7 => println!("seven"),
|
|||
|
_ => (),
|
|||
|
}
|
|||
|
<span class="boring">}
|
|||
|
</span></code></pre></pre>
|
|||
|
<p>The <code>_</code> pattern will match any value. By putting it after our other arms, the
|
|||
|
<code>_</code> will match all the possible cases that aren’t specified before it. The <code>()</code>
|
|||
|
is just the unit value, so nothing will happen in the <code>_</code> case. As a result, we
|
|||
|
can say that we want to do nothing for all the possible values that we don’t
|
|||
|
list before the <code>_</code> placeholder.</p>
|
|||
|
<p>However, the <code>match</code> expression can be a bit wordy in a situation in which we
|
|||
|
care about only <em>one</em> of the cases. For this situation, Rust provides <code>if let</code>.</p>
|
|||
|
|
|||
|
</main>
|
|||
|
|
|||
|
<nav class="nav-wrapper" aria-label="Page navigation">
|
|||
|
<!-- Mobile navigation buttons -->
|
|||
|
|
|||
|
<a rel="prev" href="ch06-01-defining-an-enum.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="ch06-03-if-let.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="ch06-01-defining-an-enum.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="ch06-03-if-let.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>
|