Rust Match Guard

A match guard is an additional if condition appended to a match arm pattern that must evaluate to true for that specific arm to execute. It allows for arbitrary boolean expressions to refine pattern matching beyond standard structural destructuring.

match expression {
    pattern if boolean_expression => result_expression,
    _ => fallback_expression,
}

Evaluation Mechanics

When a match statement executes, the compiler evaluates arms sequentially. For an arm containing a match guard:

The compiler first checks if the value structurally matches the pattern.
If the structural match succeeds, any variables defined in the pattern are bound.
The boolean_expression (the guard) is then evaluated using those bound variables.
If the guard evaluates to true, the result_expression executes.
If the guard evaluates to false, the binding is discarded, and the compiler proceeds to evaluate the next match arm.

let target = Some(4);

match target {
    Some(x) if x % 2 == 0 => println!("Matched an even inner value: {}", x),
    Some(x) => println!("Matched an odd inner value: {}", x),
    None => println!("Matched None"),
}

Exhaustiveness Checking

The Rust compiler’s exhaustiveness checker ignores match guards. Because the compiler cannot statically determine if an arbitrary runtime boolean expression will evaluate to true, a pattern equipped with a match guard does not count toward making a match exhaustive. Even if a guard logically covers all possibilities, the compiler requires a fallback arm (an identical pattern without a guard, or a catch-all like _) to guarantee exhaustiveness.

let val = 10;

// This will NOT compile, even though x > 0 and x <= 0 covers all integers.
// The compiler considers the match non-exhaustive.
match val {
    x if x > 0 => println!("Positive"),
    x if x <= 0 => println!("Non-positive"),
}

// This WILL compile. The second arm acts as the exhaustive fallback.
match val {
    x if x > 0 => println!("Positive"),
    x => println!("Non-positive"),
}

Interaction with Compound Patterns

When a match guard is used alongside the pattern OR operator (|), the guard applies to the entire compound pattern, not just the pattern immediately preceding the if keyword. The syntax behaves as (Pattern1 | Pattern2) if condition, rather than Pattern1 | (Pattern2 if condition).

let x = 4;
let y = false;

match x {
    // The guard `if y` applies to 4, 5, AND 6.
    // Because y is false, this entire arm fails, even though x is 4.
    4 | 5 | 6 if y => println!("Matched"),
    _ => println!("Fell through to default"),
}

Variable Shadowing

Variables bound in the pattern of a match guard shadow variables of the same name in the outer scope. The match guard evaluates within the scope of the newly bound variables, not the outer variables.

let x = Some(5);
let y = 10;

match x {
    // 'y' here binds to the inner value of Some, shadowing the outer 'y' (10).
    // The guard evaluates `5 == 5`, which is true.
    Some(y) if y == 5 => println!("Inner value is 5"),
    _ => println!("Default"),
}

Tired of Poor Rust Skills? Fix That With Deep Grasping!Learn More

Functions

Traits

Closures

Generics

Enums

Pattern Matching

Structs

Macros

Lifetimes

Error Handling

Variables

Control Flow

Loops

Modules

Compound Types

Collection Types

Numeric Types

Text & Boolean Types

Attributes

Comments

Assignment Operators

Arithmetic Operators

Comparison Operators

Logical Operators

Unary Operators

Reference Operators

Access & Path Operators

Range Operators

Bitwise Operators

Type Cast Operators

Evaluation Mechanics

Exhaustiveness Checking

Interaction with Compound Patterns

Variable Shadowing

​Evaluation Mechanics

​Exhaustiveness Checking

​Interaction with Compound Patterns

​Variable Shadowing

Evaluation Mechanics

Exhaustiveness Checking

Interaction with Compound Patterns

Variable Shadowing