> ## 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
The `match` expression is a control flow construct in Rust that compares a value against a series of patterns and executes the code associated with the first matching pattern. Because it is an expression rather than a statement, it evaluates to a value that can be assigned, returned, or passed to other functions.
```rust theme={"dark"}
match target_expression {
pattern_1 => expression_1,
pattern_2 | pattern_3 => expression_2,
pattern_4 if condition => expression_3,
_ => fallback_expression,
}
```
## Core Mechanics
**Exhaustiveness**
Rust enforces exhaustive pattern matching at compile time. Every possible valid value of the `target_expression`'s type must be explicitly handled by a pattern. If the type has a vast or infinite state space (such as `i32` or `String`), a catch-all pattern must be provided to satisfy the compiler.
**Type Uniformity**
Because `match` evaluates to a single value, the expressions in every match arm must resolve to the exact same type. If one arm evaluates to an `i32`, all other arms must also evaluate to an `i32`. If the `match` is used purely for side effects, all arms must evaluate to the unit type `()`.
**Sequential Evaluation**
Patterns are evaluated strictly from top to bottom. The compiler executes the expression of the *first* pattern that matches the target value. Once a match is found, the expression short-circuits, and subsequent arms are ignored.
## Pattern Syntax and Capabilities
The left side of a match arm (the pattern) supports several structural mechanics:
* **Literals:** Matching exact values (e.g., `1`, `"text"`).
* **Multiple Patterns:** The `|` operator allows a single arm to match multiple distinct patterns.
* **Ranges:** The `..=` syntax matches an inclusive range of scalar values (e.g., `1..=5`).
* **Destructuring:** Patterns can unpack compound data types—such as tuples, arrays, structs, and enums—binding their inner values to local variables.
* **Wildcards:** The `_` (underscore) pattern matches any value without binding it to a variable, effectively acting as a default or ignore mechanism.
* **Match Guards:** An `if` condition appended to a pattern. The arm is only executed if the pattern matches *and* the guard evaluates to `true`.
## Abstract Syntax Example
The following example demonstrates destructuring, ranges, match guards, and exhaustiveness without relying on a specific implementation scenario:
```rust theme={"dark"}
let target = Some((4, 10));
let result: i32 = match target {
// Destructures the tuple; executes only if the guard condition is met
Some((x, y)) if x == y => x + y,
// Matches if the first tuple element is within the inclusive range 1 to 5
Some((1..=5, y)) => y,
// Uses a wildcard to ignore the first element, binding only the second
Some((_, y)) => y * 2,
// Exhausts the remaining Option variant
None => 0,
};
```
## Variable Binding and Shadowing
When a variable name is used as a pattern, it acts as an irrefutable catch-all that binds the matched value to that variable name. This introduces a new lexical scope for the right side of the match arm. If the variable name matches a variable in the outer scope, it will shadow the outer variable.
```rust theme={"dark"}
let x = 5;
let y = 10;
match x {
// 'y' here is a new binding, not a comparison to the outer 'y'.
// It matches any value and shadows the outer 'y' of 10.
y => println!("Matched: {}", y),
}
```
To compare against an existing variable rather than shadowing it, match guards must be used:
```rust theme={"dark"}
let x = 5;
let y = 10;
match x {
// 'val' binds the target, and the guard compares it to the outer 'y'
val if val == y => println!("Matches outer y"),
_ => println!("Does not match"),
}
```
Tired of Poor Rust Skills? Fix That With Deep Grasping!
Learn More
