Pattern Matching

Pattern matching is one of Rust's most powerful features. You got a taste of match in chapters 3 and 6 -- now we go deep. By the end of this chapter, you will use pattern matching fluently to destructure data, handle variants, and write expressive conditional logic.

match is exhaustive

The match expression must cover every possible value of the type being matched. The compiler enforces this:

enum TrafficLight {
    Red,
    Yellow,
    Green,
}

fn action(light: &TrafficLight) -> &str {
    match light {
        TrafficLight::Red => "stop",
        TrafficLight::Yellow => "caution",
        TrafficLight::Green => "go",
    }
}

fn main() {
    let light = TrafficLight::Green;
    println!("{}", action(&light));
}

If you remove one arm, the compiler rejects it:

error[E0004]: non-exhaustive patterns: `TrafficLight::Green` not covered

This is a safety feature -- you can never forget to handle a case. If you add a new variant to an enum, the compiler tells you every match that needs updating.

The wildcard pattern _

When you do not want to list every case, use _ as a catch-all:

fn describe_number(n: i32) -> &'static str {
    match n {
        0 => "zero",
        1 => "one",
        2 => "two",
        _ => "many",
    }
}

fn main() {
    println!("{}", describe_number(0));   // zero
    println!("{}", describe_number(42));  // many
}

_ matches anything and is used as the last arm. If you want to bind the value without using it, prefix with _:

fn main() {
    let pair = (1, 2);

    match pair {
        (0, _) => println!("First is zero"),
        (_, 0) => println!("Second is zero"),
        _ => println!("Neither is zero"),
    }
}

Destructuring

Patterns can pull apart (destructure) structs, enums, tuples, and references.

Destructuring tuples

fn main() {
    let point = (3, -7);

    match point {
        (0, 0) => println!("Origin"),
        (x, 0) => println!("On x-axis at {x}"),
        (0, y) => println!("On y-axis at {y}"),
        (x, y) => println!("Point at ({x}, {y})"),
    }
}

Destructuring structs

struct Point {
    x: i32,
    y: i32,
}

fn main() {
    let point = Point { x: 5, y: -3 };

    match point {
        Point { x: 0, y: 0 } => println!("Origin"),
        Point { x, y: 0 } => println!("On x-axis at {x}"),
        Point { x: 0, y } => println!("On y-axis at {y}"),
        Point { x, y } => println!("({x}, {y})"),
    }
}

You can also destructure with let:

struct Point {
    x: i32,
    y: i32,
}

fn main() {
    let point = Point { x: 10, y: 20 };
    let Point { x, y } = point;
    println!("x = {x}, y = {y}");
}

Destructuring enums

This is where pattern matching truly shines:

#[derive(Debug)]
enum Message {
    Quit,
    Echo(String),
    Move { x: i32, y: i32 },
    Color(u8, u8, u8),
}

fn process(msg: &Message) {
    match msg {
        Message::Quit => println!("Quitting"),
        Message::Echo(text) => println!("Echo: {text}"),
        Message::Move { x, y } => println!("Moving to ({x}, {y})"),
        Message::Color(r, g, b) => println!("Color: rgb({r}, {g}, {b})"),
    }
}

fn main() {
    let messages = [
        Message::Echo(String::from("hello")),
        Message::Move { x: 10, y: 20 },
        Message::Color(255, 128, 0),
        Message::Quit,
    ];

    for msg in &messages {
        process(msg);
    }
}

Nested destructuring

Patterns can be nested arbitrarily deep:

struct Point {
    x: i32,
    y: i32,
}

enum Shape {
    Circle { center: Point, radius: f64 },
    Rect { top_left: Point, bottom_right: Point },
}

fn describe(shape: &Shape) {
    match shape {
        Shape::Circle {
            center: Point { x, y },
            radius,
        } => println!("Circle at ({x}, {y}) with radius {radius}"),
        Shape::Rect {
            top_left: Point { x: x1, y: y1 },
            bottom_right: Point { x: x2, y: y2 },
        } => println!("Rectangle from ({x1}, {y1}) to ({x2}, {y2})"),
    }
}

fn main() {
    let shape = Shape::Circle {
        center: Point { x: 0, y: 0 },
        radius: 5.0,
    };
    describe(&shape);
}

Multiple patterns with |

Use | (or) to match any of several patterns:

fn main() {
    let number = 4;

    match number {
        1 | 2 => println!("one or two"),
        3 | 4 => println!("three or four"),
        _ => println!("something else"),
    }
}

Match guards

Add an if condition to a match arm for extra filtering:

fn main() {
    let number = 4;

    match number {
        n if n < 0 => println!("{n} is negative"),
        n if n == 0 => println!("zero"),
        n if n % 2 == 0 => println!("{n} is positive and even"),
        n => println!("{n} is positive and odd"),
    }
}

Guards are checked after the pattern matches. They do not count as exhaustive coverage, so you usually still need a catch-all arm.

Binding with @

The @ operator lets you bind a value to a name while also testing it against a pattern:

fn main() {
    let age = 25;

    match age {
        n @ 0..=12 => println!("{n} -- child"),
        n @ 13..=17 => println!("{n} -- teenager"),
        n @ 18..=64 => println!("{n} -- adult"),
        n @ 65.. => println!("{n} -- senior"),
        _ => unreachable!(),
    }
}

Without @, you would have to use a guard: 18..=64 if true => ... and then you would not have the value bound.

if let -- matching a single pattern

When you only care about one variant and want to ignore the rest, if let is more concise than match:

fn main() {
    let maybe_number: Option<i32> = Some(42);

    // With match
    match maybe_number {
        Some(n) => println!("Got {n}"),
        None => {} // Do nothing
    }

    // Equivalent with if let
    if let Some(n) = maybe_number {
        println!("Got {n}");
    }
}

if let is syntactic sugar for a match with one arm and a wildcard for everything else. You can add an else:

fn main() {
    let config_value: Option<&str> = None;

    if let Some(val) = config_value {
        println!("Config: {val}");
    } else {
        println!("Using default config");
    }
}

Use if let when:

• You only care about one variant
• A full match would have an empty _ => {} arm
• The code is more readable without listing every case

Use match when:

• You need to handle multiple variants
• You want the compiler to enforce exhaustiveness

while let -- looping on a pattern

while let loops as long as a pattern matches:

fn main() {
    let mut stack = vec![1, 2, 3, 4, 5];

    while let Some(top) = stack.pop() {
        println!("{top}");
    }
    // Prints: 5, 4, 3, 2, 1
}

Vec::pop() returns Option<T> -- Some(value) when there are elements, None when empty. The while let keeps going until pop() returns None.

let else -- early exit on pattern failure

let else (stabilized in Rust 1.65) lets you bind a pattern or diverge:

fn process_name(name: Option<&str>) {
    let Some(name) = name else {
        println!("No name provided");
        return;
    };

    println!("Processing: {name}");
}

fn main() {
    process_name(Some("Alice"));
    process_name(None);
}

The else branch must diverge -- it must return, break, continue, or panic!. This is great for reducing nesting when you want to "unwrap or bail out early".

The matches! macro

The matches! macro returns true if a value matches a pattern:

#[derive(Debug)]
enum Status {
    Active,
    Inactive,
    Banned,
}

fn main() {
    let status = Status::Active;

    let is_active = matches!(status, Status::Active);
    let is_restricted = matches!(status, Status::Inactive | Status::Banned);

    println!("Active: {is_active}");
    println!("Restricted: {is_restricted}");
}

This is a concise alternative to writing a match that returns true or false.

Matching on Option and Result

Since Option and Result are enums, pattern matching works naturally:

Option patterns

fn describe_option(opt: Option<i32>) {
    match opt {
        Some(0) => println!("Zero"),
        Some(n) if n > 0 => println!("Positive: {n}"),
        Some(n) => println!("Negative: {n}"),
        None => println!("Nothing"),
    }
}

fn main() {
    describe_option(Some(42));
    describe_option(Some(-3));
    describe_option(Some(0));
    describe_option(None);
}

Result patterns

fn parse_and_double(input: &str) -> Result<i32, String> {
    match input.parse::<i32>() {
        Ok(n) => Ok(n * 2),
        Err(e) => Err(format!("Failed to parse '{input}': {e}")),
    }
}

fn main() {
    match parse_and_double("21") {
        Ok(n) => println!("Result: {n}"),
        Err(e) => println!("Error: {e}"),
    }

    match parse_and_double("abc") {
        Ok(n) => println!("Result: {n}"),
        Err(e) => println!("Error: {e}"),
    }
}

Patterns in function parameters

Function parameters can be patterns too:

fn print_coordinates(&(x, y): &(i32, i32)) {
    println!("({x}, {y})");
}

fn main() {
    let point = (3, 5);
    print_coordinates(&point);
}

A complete example

Here is a small command processor that demonstrates many pattern matching techniques:

#[derive(Debug)]
enum Command {
    Set { key: String, value: String },
    Get(String),
    Delete(String),
    List,
    Exit,
}

fn execute(cmd: &Command) {
    match cmd {
        Command::Set { key, value } => {
            println!("SET {key} = {value}");
        }
        Command::Get(key) | Command::Delete(key) => {
            let action = if matches!(cmd, Command::Get(_)) {
                "GET"
            } else {
                "DELETE"
            };
            println!("{action} {key}");
        }
        Command::List => println!("LIST all keys"),
        Command::Exit => println!("Goodbye!"),
    }
}

fn main() {
    let commands = [
        Command::Set {
            key: String::from("name"),
            value: String::from("Alice"),
        },
        Command::Get(String::from("name")),
        Command::List,
        Command::Delete(String::from("name")),
        Command::Exit,
    ];

    for cmd in &commands {
        execute(cmd);
    }
}

Summary

• match is exhaustive -- you must cover every possible value
• _ is the wildcard that matches anything
• Destructure tuples, structs, enums, and nested types in patterns
• | matches multiple patterns; match guards add if conditions
• @ binds a value while testing against a pattern
• if let is concise for single-pattern matching
• while let loops until a pattern no longer matches
• let else binds a pattern or diverges (early exit)
• matches! returns a boolean for quick pattern checks
• Patterns work in match, if let, while let, let, function parameters, and for loops

Next up: Collections -- Vec<T>, String, and HashMap<K, V> -- the standard library's most-used data structures.