<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Patterns - The Rust Reference</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" />
<base href="">
<link rel="stylesheet" href="book.css">
<link href="https://fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,600italic,700italic,800italic,400,300,600,700,800" rel="stylesheet" type="text/css">
<link href="https://fonts.googleapis.com/css?family=Source+Code+Pro:500" rel="stylesheet" type="text/css">
<link rel="shortcut icon" href="favicon.png">
<!-- Font Awesome -->
<link rel="stylesheet" href="_FontAwesome/css/font-awesome.css">
<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="src/theme/reference.css">
</head>
<body class="light">
<!-- 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 = 'light'; }
document.body.className = theme;
document.querySelector('html').className = theme + ' 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">
<ol class="chapter"><li class="affix"><a href="introduction.html">Introduction</a></li><li><a href="notation.html"><strong aria-hidden="true">1.</strong> Notation</a></li><li><a href="lexical-structure.html"><strong aria-hidden="true">2.</strong> Lexical structure</a></li><li><ol class="section"><li><a href="input-format.html"><strong aria-hidden="true">2.1.</strong> Input format</a></li><li><a href="keywords.html"><strong aria-hidden="true">2.2.</strong> Keywords</a></li><li><a href="identifiers.html"><strong aria-hidden="true">2.3.</strong> Identifiers</a></li><li><a href="comments.html"><strong aria-hidden="true">2.4.</strong> Comments</a></li><li><a href="whitespace.html"><strong aria-hidden="true">2.5.</strong> Whitespace</a></li><li><a href="tokens.html"><strong aria-hidden="true">2.6.</strong> Tokens</a></li><li><a href="paths.html"><strong aria-hidden="true">2.7.</strong> Paths</a></li></ol></li><li><a href="macros.html"><strong aria-hidden="true">3.</strong> Macros</a></li><li><ol class="section"><li><a href="macros-by-example.html"><strong aria-hidden="true">3.1.</strong> Macros By Example</a></li><li><a href="procedural-macros.html"><strong aria-hidden="true">3.2.</strong> Procedural Macros</a></li></ol></li><li><a href="crates-and-source-files.html"><strong aria-hidden="true">4.</strong> Crates and source files</a></li><li><a href="conditional-compilation.html"><strong aria-hidden="true">5.</strong> Conditional compilation</a></li><li><a href="items.html"><strong aria-hidden="true">6.</strong> Items</a></li><li><ol class="section"><li><a href="items/modules.html"><strong aria-hidden="true">6.1.</strong> Modules</a></li><li><a href="items/extern-crates.html"><strong aria-hidden="true">6.2.</strong> Extern crates</a></li><li><a href="items/use-declarations.html"><strong aria-hidden="true">6.3.</strong> Use declarations</a></li><li><a href="items/functions.html"><strong aria-hidden="true">6.4.</strong> Functions</a></li><li><a href="items/type-aliases.html"><strong aria-hidden="true">6.5.</strong> Type aliases</a></li><li><a href="items/structs.html"><strong aria-hidden="true">6.6.</strong> Structs</a></li><li><a href="items/enumerations.html"><strong aria-hidden="true">6.7.</strong> Enumerations</a></li><li><a href="items/unions.html"><strong aria-hidden="true">6.8.</strong> Unions</a></li><li><a href="items/constant-items.html"><strong aria-hidden="true">6.9.</strong> Constant items</a></li><li><a href="items/static-items.html"><strong aria-hidden="true">6.10.</strong> Static items</a></li><li><a href="items/traits.html"><strong aria-hidden="true">6.11.</strong> Traits</a></li><li><a href="items/implementations.html"><strong aria-hidden="true">6.12.</strong> Implementations</a></li><li><a href="items/external-blocks.html"><strong aria-hidden="true">6.13.</strong> External blocks</a></li><li><a href="items/generics.html"><strong aria-hidden="true">6.14.</strong> Type and lifetime parameters</a></li><li><a href="items/associated-items.html"><strong aria-hidden="true">6.15.</strong> Associated Items</a></li><li><a href="visibility-and-privacy.html"><strong aria-hidden="true">6.16.</strong> Visibility and Privacy</a></li></ol></li><li><a href="attributes.html"><strong aria-hidden="true">7.</strong> Attributes</a></li><li><ol class="section"><li><a href="attributes/testing.html"><strong aria-hidden="true">7.1.</strong> Testing</a></li><li><a href="attributes/derive.html"><strong aria-hidden="true">7.2.</strong> Derive</a></li><li><a href="attributes/diagnostics.html"><strong aria-hidden="true">7.3.</strong> Diagnostics</a></li><li><a href="attributes/codegen.html"><strong aria-hidden="true">7.4.</strong> Code generation</a></li><li><a href="attributes/limits.html"><strong aria-hidden="true">7.5.</strong> Limits</a></li></ol></li><li><a href="statements-and-expressions.html"><strong aria-hidden="true">8.</strong> Statements and expressions</a></li><li><ol class="section"><li><a href="statements.html"><strong aria-hidden="true">8.1.</strong> Statements</a></li><li><a href="expressions.html"><strong aria-hidden="true">8.2.</strong> Expressions</a></li><li><ol class="section"><li><a href="expressions/literal-expr.html"><strong aria-hidden="true">8.2.1.</strong> Literal expressions</a></li><li><a href="expressions/path-expr.html"><strong aria-hidden="true">8.2.2.</strong> Path expressions</a></li><li><a href="expressions/block-expr.html"><strong aria-hidden="true">8.2.3.</strong> Block expressions</a></li><li><a href="expressions/operator-expr.html"><strong aria-hidden="true">8.2.4.</strong> Operator expressions</a></li><li><a href="expressions/grouped-expr.html"><strong aria-hidden="true">8.2.5.</strong> Grouped expressions</a></li><li><a href="expressions/array-expr.html"><strong aria-hidden="true">8.2.6.</strong> Array and index expressions</a></li><li><a href="expressions/tuple-expr.html"><strong aria-hidden="true">8.2.7.</strong> Tuple and index expressions</a></li><li><a href="expressions/struct-expr.html"><strong aria-hidden="true">8.2.8.</strong> Struct expressions</a></li><li><a href="expressions/enum-variant-expr.html"><strong aria-hidden="true">8.2.9.</strong> Enum variant expressions</a></li><li><a href="expressions/call-expr.html"><strong aria-hidden="true">8.2.10.</strong> Call expressions</a></li><li><a href="expressions/method-call-expr.html"><strong aria-hidden="true">8.2.11.</strong> Method call expressions</a></li><li><a href="expressions/field-expr.html"><strong aria-hidden="true">8.2.12.</strong> Field access expressions</a></li><li><a href="expressions/closure-expr.html"><strong aria-hidden="true">8.2.13.</strong> Closure expressions</a></li><li><a href="expressions/loop-expr.html"><strong aria-hidden="true">8.2.14.</strong> Loop expressions</a></li><li><a href="expressions/range-expr.html"><strong aria-hidden="true">8.2.15.</strong> Range expressions</a></li><li><a href="expressions/if-expr.html"><strong aria-hidden="true">8.2.16.</strong> If and if let expressions</a></li><li><a href="expressions/match-expr.html"><strong aria-hidden="true">8.2.17.</strong> Match expressions</a></li><li><a href="expressions/return-expr.html"><strong aria-hidden="true">8.2.18.</strong> Return expressions</a></li></ol></li></ol></li><li><a href="patterns.html" class="active"><strong aria-hidden="true">9.</strong> Patterns</a></li><li><a href="type-system.html"><strong aria-hidden="true">10.</strong> Type system</a></li><li><ol class="section"><li><a href="types.html"><strong aria-hidden="true">10.1.</strong> Types</a></li><li><ol class="section"><li><a href="types/boolean.html"><strong aria-hidden="true">10.1.1.</strong> Boolean type</a></li><li><a href="types/numeric.html"><strong aria-hidden="true">10.1.2.</strong> Numeric types</a></li><li><a href="types/textual.html"><strong aria-hidden="true">10.1.3.</strong> Textual types</a></li><li><a href="types/never.html"><strong aria-hidden="true">10.1.4.</strong> Never type</a></li><li><a href="types/tuple.html"><strong aria-hidden="true">10.1.5.</strong> Tuple types</a></li><li><a href="types/array.html"><strong aria-hidden="true">10.1.6.</strong> Array types</a></li><li><a href="types/slice.html"><strong aria-hidden="true">10.1.7.</strong> Slice types</a></li><li><a href="types/struct.html"><strong aria-hidden="true">10.1.8.</strong> Struct types</a></li><li><a href="types/enum.html"><strong aria-hidden="true">10.1.9.</strong> Enumerated types</a></li><li><a href="types/union.html"><strong aria-hidden="true">10.1.10.</strong> Union types</a></li><li><a href="types/function-item.html"><strong aria-hidden="true">10.1.11.</strong> Function item types</a></li><li><a href="types/closure.html"><strong aria-hidden="true">10.1.12.</strong> Closure types</a></li><li><a href="types/pointer.html"><strong aria-hidden="true">10.1.13.</strong> Pointer types</a></li><li><a href="types/function-pointer.html"><strong aria-hidden="true">10.1.14.</strong> Function pointer types</a></li><li><a href="types/trait-object.html"><strong aria-hidden="true">10.1.15.</strong> Trait object types</a></li><li><a href="types/impl-trait.html"><strong aria-hidden="true">10.1.16.</strong> Impl trait type</a></li><li><a href="types/parameters.html"><strong aria-hidden="true">10.1.17.</strong> Type parameters</a></li><li><a href="types/inferred.html"><strong aria-hidden="true">10.1.18.</strong> Inferred type</a></li></ol></li><li><a href="dynamically-sized-types.html"><strong aria-hidden="true">10.2.</strong> Dynamically Sized Types</a></li><li><a href="type-layout.html"><strong aria-hidden="true">10.3.</strong> Type layout</a></li><li><a href="interior-mutability.html"><strong aria-hidden="true">10.4.</strong> Interior mutability</a></li><li><a href="subtyping.html"><strong aria-hidden="true">10.5.</strong> Subtyping and Variance</a></li><li><a href="trait-bounds.html"><strong aria-hidden="true">10.6.</strong> Trait and lifetime bounds</a></li><li><a href="type-coercions.html"><strong aria-hidden="true">10.7.</strong> Type coercions</a></li><li><a href="destructors.html"><strong aria-hidden="true">10.8.</strong> Destructors</a></li><li><a href="lifetime-elision.html"><strong aria-hidden="true">10.9.</strong> Lifetime elision</a></li></ol></li><li><a href="special-types-and-traits.html"><strong aria-hidden="true">11.</strong> Special types and traits</a></li><li><a href="memory-model.html"><strong aria-hidden="true">12.</strong> Memory model</a></li><li><ol class="section"><li><a href="memory-allocation-and-lifetime.html"><strong aria-hidden="true">12.1.</strong> Memory allocation and lifetime</a></li><li><a href="memory-ownership.html"><strong aria-hidden="true">12.2.</strong> Memory ownership</a></li><li><a href="variables.html"><strong aria-hidden="true">12.3.</strong> Variables</a></li></ol></li><li><a href="linkage.html"><strong aria-hidden="true">13.</strong> Linkage</a></li><li><a href="unsafety.html"><strong aria-hidden="true">14.</strong> Unsafety</a></li><li><ol class="section"><li><a href="unsafe-functions.html"><strong aria-hidden="true">14.1.</strong> Unsafe functions</a></li><li><a href="unsafe-blocks.html"><strong aria-hidden="true">14.2.</strong> Unsafe blocks</a></li><li><a href="behavior-considered-undefined.html"><strong aria-hidden="true">14.3.</strong> Behavior considered undefined</a></li><li><a href="behavior-not-considered-unsafe.html"><strong aria-hidden="true">14.4.</strong> Behavior not considered unsafe</a></li></ol></li><li><a href="const_eval.html"><strong aria-hidden="true">15.</strong> Constant Evaluation</a></li><li><a href="abi.html"><strong aria-hidden="true">16.</strong> Application Binary Interface</a></li><li><a href="runtime.html"><strong aria-hidden="true">17.</strong> The Rust runtime</a></li><li><a href="appendices.html"><strong aria-hidden="true">18.</strong> Appendices</a></li><li><ol class="section"><li><a href="macro-ambiguity.html"><strong aria-hidden="true">18.1.</strong> Macro Follow-Set Ambiguity Formal Specification</a></li><li><a href="influences.html"><strong aria-hidden="true">18.2.</strong> Influences</a></li><li><a href="glossary.html"><strong aria-hidden="true">18.3.</strong> Glossary</a></li></ol></li></ol>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<header><p class="warning">
For now, this reference is a best-effort document. We strive for validity
and completeness, but are not yet there. In the future, the docs and lang
teams will work together to figure out how best to do this. Until then, this
is a best-effort attempt. If you find something wrong or missing, file an
<a href="https://github.com/rust-lang-nursery/reference/issues">issue</a> or
send in a pull request.
</p></header>
<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 <span class="default">(default)</span></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 Reference</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>
<a class="header" href="patterns.html#patterns" id="patterns"><h1>Patterns</h1></a>
<blockquote>
<p><strong><sup>Syntax</sup></strong><br />
<em>Pattern</em> :<br />
<a href="patterns.html#literal-patterns"><em>LiteralPattern</em></a><br />
| <a href="patterns.html#identifier-patterns"><em>IdentifierPattern</em></a><br />
| <a href="patterns.html#wildcard-pattern"><em>WildcardPattern</em></a><br />
| <a href="patterns.html#range-patterns"><em>RangePattern</em></a><br />
| <a href="patterns.html#reference-patterns"><em>ReferencePattern</em></a><br />
| <a href="patterns.html#struct-patterns"><em>StructPattern</em></a><br />
| <a href="patterns.html#tuple-struct-patterns"><em>TupleStructPattern</em></a><br />
| <a href="patterns.html#tuple-patterns"><em>TuplePattern</em></a><br />
| <a href="patterns.html#grouped-patterns"><em>GroupedPattern</em></a><br />
| <a href="patterns.html#slice-patterns"><em>SlicePattern</em></a><br />
| <a href="patterns.html#path-patterns"><em>PathPattern</em></a><br />
| <a href="macros.html#macro-invocation"><em>MacroInvocation</em></a></p>
</blockquote>
<p>Patterns are used to match values against structures and to,
optionally, bind variables to values inside these structures. They are also
used in variable declarations and parameters for functions and closures.</p>
<p>The pattern in the following example does four things:</p>
<ul>
<li>Tests if <code>person</code> has the <code>car</code> field filled with something.</li>
<li>Tests if the person's <code>age</code> field is between 13 and 19, and binds its value to
the <code>person_age</code> variable.</li>
<li>Binds a reference to the <code>name</code> field to the variable <code>person_name</code>.</li>
<li>Ignores the rest of the fields of <code>person</code>. The remaining fields can have any value and
are not bound to any variables.</li>
</ul>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
# struct Car;
# struct Computer;
# struct Person {
# name: String,
# car: Option<Car>,
# computer: Option<Computer>,
# age: u8,
# }
# let person = Person {
# name: String::from("John"),
# car: Some(Car),
# computer: None,
# age: 15,
# };
if let
Person {
car: Some(_),
age: person_age @ 13..=19,
name: ref person_name,
..
} = person
{
println!("{} has a car and is {} years old.", person_name, person_age);
}
#}</code></pre></pre>
<p>Patterns are used in:</p>
<ul>
<li><a href="statements.html#let-statements"><code>let</code> declarations</a></li>
<li><a href="items/functions.html">Function</a> and <a href="expressions/closure-expr.html">closure</a>
parameters</li>
<li><a href="expressions/match-expr.html"><code>match</code> expressions</a></li>
<li><a href="expressions/if-expr.html"><code>if let</code> expressions</a></li>
<li><a href="expressions/loop-expr.html#predicate-pattern-loops"><code>while let</code> expressions</a></li>
<li><a href="expressions/loop-expr.html#iterator-loops"><code>for</code> expressions</a></li>
</ul>
<a class="header" href="patterns.html#destructuring" id="destructuring"><h2>Destructuring</h2></a>
<p>Patterns can be used to <em>destructure</em> <a href="items/structs.html">structs</a>, <a href="items/enumerations.html">enums</a>, and <a href="types/tuple.html">tuples</a>.
Destructuring breaks up a value into its component pieces. The syntax used is
almost the same as when creating such values. In a pattern whose <a href="glossary.html#scrutinee">scrutinee</a>
expression has a <code>struct</code>, <code>enum</code> or <code>tuple</code> type, a placeholder (<code>_</code>) stands
in for a <em>single</em> data field, whereas a wildcard <code>..</code> stands in for <em>all</em> the
remaining fields of a particular variant. When destructuring a data structure
with named (but not numbered) fields, it is allowed to write <code>fieldname</code> as a
shorthand for <code>fieldname: fieldname</code>.</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
# enum Message {
# Quit,
# WriteString(String),
# Move { x: i32, y: i32 },
# ChangeColor(u8, u8, u8),
# }
# let message = Message::Quit;
match message {
Message::Quit => println!("Quit"),
Message::WriteString(write) => println!("{}", &write),
Message::Move{ x, y: 0 } => println!("move {} horizontally", x),
Message::Move{ .. } => println!("other move"),
Message::ChangeColor { 0: red, 1: green, 2: _ } => {
println!("color change, red: {}, green: {}", red, green);
}
};
#}</code></pre></pre>
<a class="header" href="patterns.html#refutability" id="refutability"><h2>Refutability</h2></a>
<p>A pattern is said to be <em>refutable</em> when it has the possibility of not being matched
by the value it is being matched against. <em>Irrefutable</em> patterns, on the other hand,
always match the value they are being matched against. Examples:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
let (x, y) = (1, 2); // "(x, y)" is an irrefutable pattern
if let (a, 3) = (1, 2) { // "(a, 3)" is refutable, and will not match
panic!("Shouldn't reach here");
} else if let (a, 4) = (3, 4) { // "(a, 4)" is refutable, and will match
println!("Matched ({}, 4)", a);
}
#}</code></pre></pre>
<a class="header" href="patterns.html#literal-patterns" id="literal-patterns"><h2>Literal patterns</h2></a>
<blockquote>
<p><strong><sup>Syntax</sup></strong><br />
<em>LiteralPattern</em> :<br />
<a href="tokens.html#boolean-literals">BOOLEAN_LITERAL</a><br />
| <a href="tokens.html#character-literals">CHAR_LITERAL</a><br />
| <a href="tokens.html#byte-literals">BYTE_LITERAL</a><br />
| <a href="tokens.html#string-literals">STRING_LITERAL</a><br />
| <a href="tokens.html#raw-string-literals">RAW_STRING_LITERAL</a><br />
| <a href="tokens.html#byte-string-literals">BYTE_STRING_LITERAL</a><br />
| <a href="tokens.html#raw-byte-string-literals">RAW_BYTE_STRING_LITERAL</a><br />
| <code>-</code><sup>?</sup> <a href="tokens.html#integer-literals">INTEGER_LITERAL</a><br />
| <code>-</code><sup>?</sup> <a href="tokens.html#floating-point-literals">FLOAT_LITERAL</a></p>
</blockquote>
<p><em>Literal patterns</em> match exactly the same value as what is created by the
literal. Since negative numbers are not <a href="expressions/literal-expr.html">literals</a>, literal patterns also
accept an optional minus sign before the literal, which acts like the negation
operator.</p>
<div class="warning">
<p>Floating-point literals are currently accepted, but due to the complexity of comparing
them, they are going to be forbidden on literal patterns in a future version of Rust (see
<a href="https://github.com/rust-lang/rust/issues/41620">issue #41620</a>).</p>
</div>
<p>Literal patterns are always refutable.</p>
<p>Examples:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
for i in -2..5 {
match i {
-1 => println!("It's minus one"),
1 => println!("It's a one"),
2|4 => println!("It's either a two or a four"),
_ => println!("Matched none of the arms"),
}
}
#}</code></pre></pre>
<a class="header" href="patterns.html#identifier-patterns" id="identifier-patterns"><h2>Identifier patterns</h2></a>
<blockquote>
<p><strong><sup>Syntax</sup></strong><br />
<em>IdentifierPattern</em> :<br />
<code>ref</code><sup>?</sup> <code>mut</code><sup>?</sup> <a href="identifiers.html">IDENTIFIER</a> (<code>@</code> <a href="patterns.html#patterns"><em>Pattern</em></a> ) <sup>?</sup></p>
</blockquote>
<p>Identifier patterns bind the value they match to a variable. The identifier
must be unique within the pattern. The variable will shadow any variables of
the same name in scope. The scope of the new binding depends on the context of
where the pattern is used (such as a <code>let</code> binding or a <code>match</code> arm).</p>
<p>Patterns that consist of only an identifier, possibly with a <code>mut</code>, match any value and
bind it to that identifier. This is the most commonly used pattern in variable
declarations and parameters for functions and closures.</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
let mut variable = 10;
fn sum(x: i32, y: i32) -> i32 {
# x + y
# }
#}</code></pre></pre>
<p>To bind the matched value of a pattern to a variable, use the syntax <code>variable @ subpattern</code>. For example, the following binds the value 2 to <code>e</code> (not the
entire range: the range here is a range subpattern).</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
let x = 2;
match x {
e @ 1 ..= 5 => println!("got a range element {}", e),
_ => println!("anything"),
}
#}</code></pre></pre>
<p>By default, identifier patterns bind a variable to a copy of or move from the
matched value depending on whether the matched value implements <a href="special-types-and-traits.html#copy"><code>Copy</code></a>.
This can be changed to bind to a reference by using the <code>ref</code> keyword,
or to a mutable reference using <code>ref mut</code>. For example:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
# let a = Some(10);
match a {
None => (),
Some(value) => (),
}
match a {
None => (),
Some(ref value) => (),
}
#}</code></pre></pre>
<p>In the first match expression, the value is copied (or moved). In the second match,
a reference to the same memory location is bound to the variable value. This syntax is
needed because in destructuring subpatterns the <code>&</code> operator can't be applied to
the value's fields. For example, the following is not valid:</p>
<pre><pre class="playpen"><code class="language-rust compile_fail">
# #![allow(unused_variables)]
#fn main() {
# struct Person {
# name: String,
# age: u8,
# }
# let value = Person{ name: String::from("John"), age: 23 };
if let Person{name: &person_name, age: 18..=150} = value { }
#}</code></pre></pre>
<p>To make it valid, write the following:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
# struct Person {
# name: String,
# age: u8,
# }
# let value = Person{ name: String::from("John"), age: 23 };
if let Person{name: ref person_name, age: 18..=150} = value { }
#}</code></pre></pre>
<p>Thus, <code>ref</code> is not something that is being matched against. Its objective is
exclusively to make the matched binding a reference, instead of potentially
copying or moving what was matched.</p>
<p><a href="patterns.html#path-patterns">Path patterns</a> take precedence over identifier patterns. It is an error
if <code>ref</code> or <code>ref mut</code> is specified and the identifier shadows a constant.</p>
<a class="header" href="patterns.html#binding-modes" id="binding-modes"><h3>Binding modes</h3></a>
<p>To service better ergonomics, patterns operate in different <em>binding modes</em> in
order to make it easier to bind references to values. When a reference value is matched by
a non-reference pattern, it will be automatically treated as a <code>ref</code> or <code>ref mut</code> binding.
Example:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
let x: &Option<i32> = &Some(3);
if let Some(y) = x {
// y was converted to `ref y` and its type is &i32
}
#}</code></pre></pre>
<p><em>Non-reference patterns</em> include all patterns except bindings, <a href="patterns.html#wildcard-pattern">wildcard
patterns</a> (<code>_</code>), <a href="patterns.html#path-patterns"><code>const</code> patterns</a> of reference types,
and <a href="patterns.html#reference-patterns">reference patterns</a>.</p>
<p>If a binding pattern does not explicitly have <code>ref</code>, <code>ref mut</code>, or <code>mut</code>, then it uses the
<em>default binding mode</em> to determine how the variable is bound. The default binding
mode starts in "move" mode which uses move semantics. When matching a pattern, the
compiler starts from the outside of the pattern and works inwards. Each time a reference
is matched using a non-reference pattern, it will automatically dereference the value and
update the default binding mode. References will set the default binding mode to <code>ref</code>.
Mutable references will set the mode to <code>ref mut</code> unless the mode is already <code>ref</code> in
which case it remains <code>ref</code>. If the automatically dereferenced value is still a reference,
it is dereferenced and this process repeats.</p>
<a class="header" href="patterns.html#wildcard-pattern" id="wildcard-pattern"><h2>Wildcard pattern</h2></a>
<blockquote>
<p><strong><sup>Syntax</sup></strong><br />
<em>WildcardPattern</em> :<br />
<code>_</code></p>
</blockquote>
<p>The <em>wildcard pattern</em> matches any value. It is used to ignore values when they don't
matter. Inside other patterns it matches a single data field (as opposed to the <code>..</code>
which matches the remaining fields). Unlike identifier patterns, it does not copy, move
or borrow the value it matches.</p>
<p>Examples:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
# let x = 20;
let (a, _) = (10, x); // the x is always matched by _
# assert_eq!(a, 10);
// ignore a function/closure param
let real_part = |a: f64, _: f64| { a };
// ignore a field from a struct
# struct RGBA {
# r: f32,
# g: f32,
# b: f32,
# a: f32,
# }
# let color = RGBA{r: 0.4, g: 0.1, b: 0.9, a: 0.5};
let RGBA{r: red, g: green, b: blue, a: _} = color;
# assert_eq!(color.r, red);
# assert_eq!(color.g, green);
# assert_eq!(color.b, blue);
// accept any Some, with any value
# let x = Some(10);
if let Some(_) = x {}
#}</code></pre></pre>
<p>The wildcard pattern is always irrefutable.</p>
<a class="header" href="patterns.html#range-patterns" id="range-patterns"><h2>Range patterns</h2></a>
<blockquote>
<p><strong><sup>Syntax</sup></strong><br />
<em>RangePattern</em> :<br />
<em>RangePatternBound</em> <code>..=</code> <em>RangePatternBound</em><br />
| <em>RangePatternBound</em> <code>...</code> <em>RangePatternBound</em></p>
<p><em>RangePatternBound</em> :<br />
<a href="tokens.html#character-literals">CHAR_LITERAL</a><br />
| <a href="tokens.html#byte-literals">BYTE_LITERAL</a><br />
| <code>-</code><sup>?</sup> <a href="tokens.html#integer-literals">INTEGER_LITERAL</a><br />
| <code>-</code><sup>?</sup> <a href="tokens.html#floating-point-literals">FLOAT_LITERAL</a><br />
| <a href="paths.html#paths-in-expressions"><em>PathInExpression</em></a><br />
| <a href="paths.html#qualified-paths"><em>QualifiedPathInExpression</em></a></p>
</blockquote>
<p>Range patterns match values that are within the closed range defined by its lower and
upper bounds. For example, a pattern <code>'m'..='p'</code> will match only the values <code>'m'</code>, <code>'n'</code>,
<code>'o'</code>, and <code>'p'</code>. The bounds can be literals or paths that point to constant values.</p>
<p>A pattern a <code>..=</code> b must always have a ≤ b. It is an error to have a range pattern
<code>10..=0</code>, for example.</p>
<p>The <code>...</code> syntax is kept for backwards compatibility.</p>
<p>Range patterns only work on scalar types. The accepted types are:</p>
<ul>
<li>Integer types (u8, i8, u16, i16, usize, isize, etc.).</li>
<li>Character types (char).</li>
<li>Floating point types (f32 and f64). This is being deprecated and will not be available
in a future version of Rust (see
<a href="https://github.com/rust-lang/rust/issues/41620">issue #41620</a>).</li>
</ul>
<p>Examples:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
# let c = 'f';
let valid_variable = match c {
'a'..='z' => true,
'A'..='Z' => true,
'α'..='ω' => true,
_ => false,
};
# let ph = 10;
println!("{}", match ph {
0..=6 => "acid",
7 => "neutral",
8..=14 => "base",
_ => unreachable!(),
});
// using paths to constants:
# const TROPOSPHERE_MIN : u8 = 6;
# const TROPOSPHERE_MAX : u8 = 20;
#
# const STRATOSPHERE_MIN : u8 = TROPOSPHERE_MAX + 1;
# const STRATOSPHERE_MAX : u8 = 50;
#
# const MESOSPHERE_MIN : u8 = STRATOSPHERE_MAX + 1;
# const MESOSPHERE_MAX : u8 = 85;
#
# let altitude = 70;
#
println!("{}", match altitude {
TROPOSPHERE_MIN..=TROPOSPHERE_MAX => "troposphere",
STRATOSPHERE_MIN..=STRATOSPHERE_MAX => "stratosphere",
MESOSPHERE_MIN..=MESOSPHERE_MAX => "mesosphere",
_ => "outer space, maybe",
});
# pub mod binary {
# pub const MEGA : u64 = 1024*1024;
# pub const GIGA : u64 = 1024*1024*1024;
# }
# let n_items = 20_832_425;
# let bytes_per_item = 12;
if let size @ binary::MEGA..=binary::GIGA = n_items * bytes_per_item {
println!("It fits and occupies {} bytes", size);
}
# trait MaxValue {
# const MAX: u64;
# }
# impl MaxValue for u8 {
# const MAX: u64 = (1 << 8) - 1;
# }
# impl MaxValue for u16 {
# const MAX: u64 = (1 << 16) - 1;
# }
# impl MaxValue for u32 {
# const MAX: u64 = (1 << 32) - 1;
# }
// using qualified paths:
println!("{}", match 0xfacade {
0 ..= <u8 as MaxValue>::MAX => "fits in a u8",
0 ..= <u16 as MaxValue>::MAX => "fits in a u16",
0 ..= <u32 as MaxValue>::MAX => "fits in a u32",
_ => "too big",
});
#}</code></pre></pre>
<p>Range patterns for (non-<code>usize</code> and -<code>isize</code>) integer and <code>char</code> types are irrefutable
when they span the entire set of possible values of a type. For example, <code>0u8..=255u8</code>
is irrefutable. The range of values for an integer type is the closed range from its
minimum to maximum value. The range of values for a <code>char</code> type are precisely those
ranges containing all Unicode Scalar Values: <code>'\u{0000}'..='\u{D7FF}'</code> and
<code>'\u{E000}'..='\u{10FFFF}'</code>.</p>
<a class="header" href="patterns.html#reference-patterns" id="reference-patterns"><h2>Reference patterns</h2></a>
<blockquote>
<p><strong><sup>Syntax</sup></strong><br />
<em>ReferencePattern</em> :<br />
(<code>&</code>|<code>&&</code>) <code>mut</code><sup>?</sup> <em>Pattern</em></p>
</blockquote>
<p>Reference patterns dereference the pointers that are being matched
and, thus, borrow them.</p>
<p>For example, these two matches on <code>x: &i32</code> are equivalent:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
let int_reference = &3;
let a = match *int_reference { 0 => "zero", _ => "some" };
let b = match int_reference { &0 => "zero", _ => "some" };
assert_eq!(a, b);
#}</code></pre></pre>
<p>The grammar production for reference patterns has to match the token <code>&&</code> to match a
reference to a reference because it is a token by itself, not two <code>&</code> tokens.</p>
<p>Adding the <code>mut</code> keyword dereferences a mutable reference. The mutability must match the
mutability of the reference.</p>
<p>Reference patterns are always irrefutable.</p>
<a class="header" href="patterns.html#struct-patterns" id="struct-patterns"><h2>Struct patterns</h2></a>
<blockquote>
<p><strong><sup>Syntax</sup></strong><br />
<em>StructPattern</em> :<br />
<a href="paths.html#paths-in-expressions"><em>PathInExpression</em></a> <code>{</code><br />
<em>StructPatternElements</em> <sup>?</sup><br />
<code>}</code></p>
<p><em>StructPatternElements</em> :<br />
<em>StructPatternFields</em> (<code>,</code> | <code>,</code> <em>StructPatternEtCetera</em>)<sup>?</sup><br />
| <em>StructPatternEtCetera</em></p>
<p><em>StructPatternFields</em> :<br />
<em>StructPatternField</em> (<code>,</code> <em>StructPatternField</em>) <sup>*</sup></p>
<p><em>StructPatternField</em> :<br />
<a href="attributes.html"><em>OuterAttribute</em></a> <sup>*</sup><br />
(<br />
<a href="tokens.html#integer-literals">TUPLE_INDEX</a> <code>:</code> <a href="patterns.html#patterns"><em>Pattern</em></a><br />
| <a href="identifiers.html">IDENTIFIER</a> <code>:</code> <a href="patterns.html#patterns"><em>Pattern</em></a><br />
| <code>ref</code><sup>?</sup> <code>mut</code><sup>?</sup> <a href="identifiers.html">IDENTIFIER</a><br />
)</p>
<p><em>StructPatternEtCetera</em> :<br />
<a href="attributes.html"><em>OuterAttribute</em></a> <sup>*</sup><br />
<code>..</code></p>
</blockquote>
<p>Struct patterns match struct values that match all criteria defined by its subpatterns.
They are also used to <a href="patterns.html#destructuring">destructure</a> a struct.</p>
<p>On a struct pattern, the fields are referenced by name, index (in the case of tuple
structs) or ignored by use of <code>..</code>:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
# struct Point {
# x: u32,
# y: u32,
# }
# let s = Point {x: 1, y: 1};
#
match s {
Point {x: 10, y: 20} => (),
Point {y: 10, x: 20} => (), // order doesn't matter
Point {x: 10, ..} => (),
Point {..} => (),
}
# struct PointTuple (
# u32,
# u32,
# );
# let t = PointTuple(1, 2);
#
match t {
PointTuple {0: 10, 1: 20} => (),
PointTuple {1: 10, 0: 20} => (), // order doesn't matter
PointTuple {0: 10, ..} => (),
PointTuple {..} => (),
}
#}</code></pre></pre>
<p>If <code>..</code> is not used, it is required to match all fields:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
# struct Struct {
# a: i32,
# b: char,
# c: bool,
# }
# let mut struct_value = Struct{a: 10, b: 'X', c: false};
#
match struct_value {
Struct{a: 10, b: 'X', c: false} => (),
Struct{a: 10, b: 'X', ref c} => (),
Struct{a: 10, b: 'X', ref mut c} => (),
Struct{a: 10, b: 'X', c: _} => (),
Struct{a: _, b: _, c: _} => (),
}
#}</code></pre></pre>
<p>The <code>ref</code> and/or <code>mut</code> <em>IDENTIFIER</em> syntax matches any value and binds it to
a variable with the same name as the given field.</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
# struct Struct {
# a: i32,
# b: char,
# c: bool,
# }
# let struct_value = Struct{a: 10, b: 'X', c: false};
#
let Struct{a: x, b: y, c: z} = struct_value; // destructure all fields
#}</code></pre></pre>
<p>A struct pattern is refutable when one of its subpatterns is refutable.</p>
<a class="header" href="patterns.html#tuple-struct-patterns" id="tuple-struct-patterns"><h2>Tuple struct patterns</h2></a>
<blockquote>
<p><strong><sup>Syntax</sup></strong><br />
<em>TupleStructPattern</em> :<br />
<a href="paths.html#paths-in-expressions"><em>PathInExpression</em></a> <code>(</code> <em>TupleStructItems</em> <code>)</code></p>
<p><em>TupleStructItems</em> :<br />
<a href="patterns.html#patterns"><em>Pattern</em></a> ( <code>,</code> <a href="patterns.html#patterns"><em>Pattern</em></a> )<sup>*</sup> <code>,</code><sup>?</sup><br />
| (<a href="patterns.html#patterns"><em>Pattern</em></a> <code>,</code>)<sup>*</sup> <code>..</code> ( (<code>,</code> <a href="patterns.html#patterns"><em>Pattern</em></a>)<sup>+</sup> <code>,</code><sup>?</sup> )<sup>?</sup></p>
</blockquote>
<p>Tuple struct patterns match tuple struct and enum values that match all criteria defined
by its subpatterns. They are also used to <a href="patterns.html#destructuring">destructure</a> a tuple struct or
enum value.</p>
<p>A tuple struct pattern is refutable when one of its subpatterns is refutable.</p>
<a class="header" href="patterns.html#tuple-patterns" id="tuple-patterns"><h2>Tuple patterns</h2></a>
<blockquote>
<p><strong><sup>Syntax</sup></strong><br />
<em>TuplePattern</em> :<br />
<code>(</code> <em>TuplePatternItems</em><sup>?</sup> <code>)</code></p>
<p><em>TuplePatternItems</em> :<br />
<a href="patterns.html#patterns"><em>Pattern</em></a> <code>,</code><br />
| <a href="patterns.html#patterns"><em>Pattern</em></a> (<code>,</code> <a href="patterns.html#patterns"><em>Pattern</em></a>)<sup>+</sup> <code>,</code><sup>?</sup><br />
| (<a href="patterns.html#patterns"><em>Pattern</em></a> <code>,</code>)<sup>*</sup> <code>..</code> ( (<code>,</code> <a href="patterns.html#patterns"><em>Pattern</em></a>)<sup>+</sup> <code>,</code><sup>?</sup> )<sup>?</sup></p>
</blockquote>
<p>Tuple patterns match tuple values that match all criteria defined by its subpatterns.
They are also used to <a href="patterns.html#destructuring">destructure</a> a tuple.</p>
<p>This pattern is refutable when one of its subpatterns is refutable.</p>
<a class="header" href="patterns.html#grouped-patterns" id="grouped-patterns"><h2>Grouped patterns</h2></a>
<blockquote>
<p><strong><sup>Syntax</sup></strong><br />
<em>GroupedPattern</em> :<br />
<code>(</code> <a href="patterns.html#patterns"><em>Pattern</em></a> <code>)</code></p>
</blockquote>
<p>Enclosing a pattern in parentheses can be used to explicitly control the
precedence of compound patterns. For example, a reference pattern next to a
range pattern such as <code>&0..=5</code> is ambiguous and is not allowed, but can be
expressed with parentheses.</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
let int_reference = &3;
match int_reference {
&(0..=5) => (),
_ => (),
}
#}</code></pre></pre>
<a class="header" href="patterns.html#slice-patterns" id="slice-patterns"><h2>Slice patterns</h2></a>
<blockquote>
<p><strong><sup>Syntax</sup></strong><br />
<em>SlicePattern</em> :<br />
<code>[</code> <a href="patterns.html#patterns"><em>Pattern</em></a> (<code>,</code> <a href="patterns.html#patterns"><em>Pattern</em></a>)<sup>*</sup> <code>,</code><sup>?</sup> <code>]</code></p>
</blockquote>
<p>Slice patterns can match both arrays of fixed size and slices of dynamic size.</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
// Fixed size
let arr = [1, 2, 3];
match arr {
[1, _, _] => "starts with one",
[a, b, c] => "starts with something else",
};
#}</code></pre></pre>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
// Dynamic size
let v = vec![1, 2, 3];
match v[..] {
[a, b] => { /* this arm will not apply because the length doesn't match */ }
[a, b, c] => { /* this arm will apply */ }
_ => { /* this wildcard is required, since the length is not known statically */ }
};
#}</code></pre></pre>
<a class="header" href="patterns.html#path-patterns" id="path-patterns"><h2>Path patterns</h2></a>
<blockquote>
<p><strong><sup>Syntax</sup></strong><br />
<em>PathPattern</em> :<br />
<a href="paths.html#paths-in-expressions"><em>PathInExpression</em></a><br />
| <a href="paths.html#qualified-paths"><em>QualifiedPathInExpression</em></a></p>
</blockquote>
<p><em>Path patterns</em> are patterns that refer either to constant values or
to structs or enum variants that have no fields.</p>
<p>Unqualified path patterns can refer to:</p>
<ul>
<li>enum variants</li>
<li>structs</li>
<li>constants</li>
<li>associated constants</li>
</ul>
<p>Qualified path patterns can only refer to associated constants.</p>
<p>Constants cannot be a union type. Struct and enum constants must have
<code>#[derive(PartialEq, Eq)]</code> (not merely implemented).</p>
<p>Path patterns are irrefutable when they refer to structs or an enum variant when the enum
has only one variant or a constant whose type is irrefutable. They are refutable when they
refer to refutable constants or enum variants for enums with multiple variants.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="expressions/return-expr.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="type-system.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="expressions/return-expr.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="type-system.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 src="searchindex.js" type="text/javascript" charset="utf-8"></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 -->
</body>
</html>
distrib
>
Mageia
>
7
>
armv7hl
>
media
>
core-release
>
by-pkgid
>
0c2243f8a1696816431e7210e991fa52
>
files
>
13405
