> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
```rust theme={"dark"}
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:
1. The compiler first checks if the value structurally matches the `pattern`.
2. If the structural match succeeds, any variables defined in the pattern are bound.
3. The `boolean_expression` (the guard) is then evaluated using those bound variables.
4. If the guard evaluates to `true`, the `result_expression` executes.
5. If the guard evaluates to `false`, the binding is discarded, and the compiler proceeds to evaluate the next `match` arm.
```rust theme={"dark"}
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.
```rust theme={"dark"}
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)`.
```rust theme={"dark"}
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.
```rust theme={"dark"}
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
