Pattern Matching with match

match compares a value against patterns, binding variables and running the first matching arm. Compiler enforces exhaustiveness.

Recipe

enum Color { Red, Green, Blue }
 
fn label(c: Color) -> &'static str {
    match c {
        Color::Red => "red",
        Color::Green => "green",
        Color::Blue => "blue",
    }
}

When to reach for this: Enums, Option/Result, parsing tokens, and multi-way branching with destructuring.

Working Example

#[derive(Debug)]
enum Token { Num(i64), Ident(String), Eof }
 
fn eval(tok: Token) -> String {
    match tok {
        Token::Num(n) if n < 0 => format!("negative {n}"),
        Token::Num(n) => n.to_string(),
        Token::Ident(name) => name,
        Token::Eof => "eof".into(),
    }
}
 
fn main() {
    println!("{}", eval(Token::Num(-3)));
}

What this demonstrates:

• Binding n, name from variant payloads
• Guard if n < 0 refines match arm
• Exhaustive arms for all variants
• match as expression returning String

Deep Dive

Pattern Forms

• Literals, ranges 1..=5
• Struct patterns Point { x, y }
• Tuple and slice patterns
• @ bindings n @ 1..=100
• | or-patterns Some(0) | Some(1)

match vs if let

match handles many patterns; if let one pattern ergonomically.

Gotchas

• Missing variant after enum change - Compile error across crate. Fix: Update all matches (benefit of exhaustiveness).
• Binding mode in Rust 2024 - mut binding modes affect move/copy. Fix: Read edition migration guide for ref/mut patterns.
• Non-exhaustive integers - match x: u8 needs _ arm. Fix: Add wildcard or ranges.
• Move in match arm - Binding moves unless ref pattern. Fix: Use ref/ref mut to borrow fields.
• Guard cannot borrow matched value oddly - Guard evaluated after pattern bind. Fix: Restructure guard or use if let chain.

Alternatives

FAQs

Related

• Enums - variants to match
• if let, let else & while let - partial match
• Destructuring - pattern forms
• Option & Result as Enums - core matches

Stack versions: This page was written for Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, and Polars 0.46+.