Rust Reference ยท Patterns
Destructuring patterns
Reference for destructuring in Rust: taking apart tuples, structs, tuple structs, enums and nested values with patterns in let, match, parameters and for loops.
Destructuring means writing a pattern that mirrors the shape of a value, so Rust can pull the parts out into separate variables in one step. It works on tuples, arrays, structs, tuple structs and enum variants, and the patterns nest to any depth.
Destructuring is available wherever a pattern is: let, match, if let, while let, for and function or closure parameters. If the pattern can fail (for example, one enum variant), the place must accept a refutable pattern.
let (name, age) = ("Ada", 36); let Point { x, y } = point;
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Syntax
let (a, b) = tuple; let [x, y, z] = array; let Struct { field, other: renamed, .. } = value; let TupleStruct(a, b) = value; match e { Enum::Variant { f, .. } => {}, Enum::Pair(a, _) => {}, Enum::Unit => {} } fn f(&(a, b): &(i32, i32)) {} for (i, item) in list.iter().enumerate() {}
| Part | Description |
|---|---|
| Field shorthand | Point { x, y } binds variables named x and y. Write x: px to choose another name. |
.. |
Skips the remaining fields or elements (wildcard and rest). |
| Nested patterns | Any sub-pattern can itself be a pattern, including literals: Point { x: 0, y }. |
Errors and edge cases: a let with a refutable pattern, such as let Some(x) = opt;, fails with E0005 unless you add an else branch (let Some(x) = opt else { return };). Array patterns must match the array length exactly. Binding by value from a non-Copy field moves it, so the original value is partially moved.
Usage notes
- Match ergonomics. Matching on a reference (
&Shape) with a non-reference pattern makes every binding a reference. That is whyradiusabove is an&f64, and arithmetic likeradius * radiusstill works. - Partial moves. Destructuring a struct by value moves out fields that are not
Copy. The struct cannot be used as a whole afterwards, but untouched fields still can. - Types with
Dropcannot be destructured by moving fields out (E0509). Borrow instead. - Private fields. A pattern can only name fields visible at that location; use
..for the rest. - Parameters. Closures and functions can destructure arguments directly:
|&(a, b)| a + b,|(k, v)| ...over map entries. - Readability. Deeply nested destructuring is compact but hard to scan; bind the outer part first when a pattern gets longer than a line.
Related
match,let, Slice patterns, Reference patterns, Tuples- Lessons: Patterns, Enums and match, Structs