Patterns are quite common in Rust. We use them in variable bindings, match expressions, and other places, too. Let’s go on a whirlwind tour of all of the things patterns can do!
A quick refresher: you can match against literals directly, and _ acts as an
‘any’ case:
let x = 1; match x { 1 => println!("one"), 2 => println!("two"), 3 => println!("three"), _ => println!("anything"), }
This prints one.
There’s one pitfall with patterns: like anything that introduces a new binding, they introduce shadowing. For example:
fn main() { let x = 1; let c = 'c'; match c { x => println!("x: {} c: {}", x, c), } println!("x: {}", x) }let x = 1; let c = 'c'; match c { x => println!("x: {} c: {}", x, c), } println!("x: {}", x)
This prints:
x: c c: c
x: 1
In other words, x => matches the pattern and introduces a new binding named
x. This new binding is in scope for the match arm and takes on the value of
c. Notice that the value of x outside the scope of the match has no bearing
on the value of x within it. Because we already have a binding named x, this
new x shadows it.
You can match multiple patterns with |:
let x = 1; match x { 1 | 2 => println!("one or two"), 3 => println!("three"), _ => println!("anything"), }
This prints one or two.
If you have a compound data type, like a struct, you can destructure it
inside of a pattern:
struct Point { x: i32, y: i32, } let origin = Point { x: 0, y: 0 }; match origin { Point { x, y } => println!("({},{})", x, y), }
We can use : to give a value a different name.
struct Point { x: i32, y: i32, } let origin = Point { x: 0, y: 0 }; match origin { Point { x: x1, y: y1 } => println!("({},{})", x1, y1), }
If we only care about some of the values, we don’t have to give them all names:
fn main() { struct Point { x: i32, y: i32, } let origin = Point { x: 0, y: 0 }; match origin { Point { x, .. } => println!("x is {}", x), } }struct Point { x: i32, y: i32, } let origin = Point { x: 0, y: 0 }; match origin { Point { x, .. } => println!("x is {}", x), }
This prints x is 0.
You can do this kind of match on any member, not only the first:
fn main() { struct Point { x: i32, y: i32, } let origin = Point { x: 0, y: 0 }; match origin { Point { y, .. } => println!("y is {}", y), } }struct Point { x: i32, y: i32, } let origin = Point { x: 0, y: 0 }; match origin { Point { y, .. } => println!("y is {}", y), }
This prints y is 0.
This ‘destructuring’ behavior works on any compound data type, like tuples or enums.
You can use _ in a pattern to disregard the type and value.
For example, here’s a match against a Result<T, E>:
match some_value { Ok(value) => println!("got a value: {}", value), Err(_) => println!("an error occurred"), }
In the first arm, we bind the value inside the Ok variant to value. But
in the Err arm, we use _ to disregard the specific error, and print
a general error message.
_ is valid in any pattern that creates a binding. This can be useful to
ignore parts of a larger structure:
fn coordinate() -> (i32, i32, i32) { // generate and return some sort of triple tuple } let (x, _, z) = coordinate();
Here, we bind the first and last element of the tuple to x and z, but
ignore the middle element.
It’s worth noting that using _ never binds the value in the first place,
which means a value may not move:
let tuple: (u32, String) = (5, String::from("five")); // Here, tuple is moved, because the String moved: let (x, _s) = tuple; // The next line would give "error: use of partially moved value: `tuple`" // println!("Tuple is: {:?}", tuple); // However, let tuple = (5, String::from("five")); // Here, tuple is _not_ moved, as the String was never moved, and u32 is Copy: let (x, _) = tuple; // That means this works: println!("Tuple is: {:?}", tuple);
This also means that any temporary variables will be dropped at the end of the statement:
fn main() { // Here, the String created will be dropped immediately, as it’s not bound: let _ = String::from(" hello ").trim(); }// Here, the String created will be dropped immediately, as it’s not bound: let _ = String::from(" hello ").trim();
You can also use .. in a pattern to disregard multiple values:
enum OptionalTuple { Value(i32, i32, i32), Missing, } let x = OptionalTuple::Value(5, -2, 3); match x { OptionalTuple::Value(..) => println!("Got a tuple!"), OptionalTuple::Missing => println!("No such luck."), }
This prints Got a tuple!.
If you want to get a reference, use the ref keyword:
let x = 5; match x { ref r => println!("Got a reference to {}", r), }
This prints Got a reference to 5.
Here, the r inside the match has the type &i32. In other words, the ref
keyword creates a reference, for use in the pattern. If you need a mutable
reference, ref mut will work in the same way:
let mut x = 5; match x { ref mut mr => println!("Got a mutable reference to {}", mr), }
You can match a range of values with ...:
let x = 1; match x { 1 ... 5 => println!("one through five"), _ => println!("anything"), }
This prints one through five.
Ranges are mostly used with integers and chars:
let x = '💅'; match x { 'a' ... 'j' => println!("early letter"), 'k' ... 'z' => println!("late letter"), _ => println!("something else"), }
This prints something else.
You can bind values to names with @:
let x = 1; match x { e @ 1 ... 5 => println!("got a range element {}", e), _ => println!("anything"), }
This prints got a range element 1. This is useful when you want to
do a complicated match of part of a data structure:
#[derive(Debug)] struct Person { name: Option<String>, } let name = "Steve".to_string(); let x: Option<Person> = Some(Person { name: Some(name) }); match x { Some(Person { name: ref a @ Some(_), .. }) => println!("{:?}", a), _ => {} }
This prints Some("Steve"): we’ve bound the inner name to a.
If you use @ with |, you need to make sure the name is bound in each part
of the pattern:
let x = 5; match x { e @ 1 ... 5 | e @ 8 ... 10 => println!("got a range element {}", e), _ => println!("anything"), }
You can introduce ‘match guards’ with if:
enum OptionalInt { Value(i32), Missing, } let x = OptionalInt::Value(5); match x { OptionalInt::Value(i) if i > 5 => println!("Got an int bigger than five!"), OptionalInt::Value(..) => println!("Got an int!"), OptionalInt::Missing => println!("No such luck."), }
This prints Got an int!.
If you’re using if with multiple patterns, the if applies to both sides:
let x = 4; let y = false; match x { 4 | 5 if y => println!("yes"), _ => println!("no"), }
This prints no, because the if applies to the whole of 4 | 5, and not to
only the 5. In other words, the precedence of if behaves like this:
(4 | 5) if y => ...
not this:
4 | (5 if y) => ...
Whew! That’s a lot of different ways to match things, and they can all be mixed and matched, depending on what you’re doing:
fn main() { match x { Foo { x: Some(ref name), y: None } => ... } }match x { Foo { x: Some(ref name), y: None } => ... }
Patterns are very powerful. Make good use of them.