> ## 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 Literal Pattern
A literal pattern in Rust is a pattern that matches exactly a specific, hardcoded constant value. A match occurs if the scrutinee (the value being matched against) is structurally and strictly type-equal to the literal specified in the pattern.
Literal patterns are inherently **refutable**, meaning they can fail to match. Because of this, they cannot be used alone in contexts that require irrefutable patterns (like standard `let` bindings) and are primarily utilized in `match` expressions, `if let`, and `while let` constructs.
## Syntax and Supported Types
Rust supports literal patterns for most primitive types. The syntax is identical to the literal expression syntax used elsewhere in the language. Because Rust is strictly typed, the scrutinee's type must exactly match the literal pattern's type, requiring separate `match` blocks for different types.
```rust theme={"dark"}
// Integer literal patterns (including negative literals)
let int_val: i32 = -10;
match int_val {
42 => { /* ... */ }
-10 => { /* ... */ }
_ => { /* ... */ }
}
// Boolean literal patterns
let bool_val: bool = true;
match bool_val {
true => { /* ... */ }
false => { /* ... */ }
}
// Character literal patterns
let char_val: char = 'A';
match char_val {
'A' => { /* ... */ }
_ => { /* ... */ }
}
// String literal patterns (&str)
let str_val: &str = "literal";
match str_val {
"literal" => { /* ... */ }
_ => { /* ... */ }
}
// Byte literal patterns (u8)
let byte_val: u8 = b'x';
match byte_val {
b'x' => { /* ... */ }
_ => { /* ... */ }
}
// Byte string literal patterns (&[u8; N])
let byte_str_val: &[u8; 5] = b"bytes";
match byte_str_val {
b"bytes" => { /* ... */ }
_ => { /* ... */ }
}
```
## Technical Mechanics
**Exhaustiveness Checking**
The Rust compiler's exhaustiveness checker fully understands the domains of primitive types. While types with vast domains like `i32` or `&str` practically require a wildcard (`_`) or binding pattern to cover all unlisted values, finite domains can be matched exhaustively using only literal patterns. For example, providing both `true` and `false` for a `bool`, or explicitly listing all 256 possible values for a `u8`, fully satisfies the exhaustiveness checker and does not require a catch-all arm.
**Strict Type Equality and Strings**
Pattern matching requires strict type equality and does *not* perform implicit deref coercion. A string literal pattern (`"..."`) has the type `&str`. Attempting to match an owned `String` (or `&String`) directly against a string literal pattern will result in a `mismatched types` compiler error. The scrutinee must be explicitly converted to a string slice before matching:
```rust theme={"dark"}
let s = String::from("literal");
// s must be explicitly sliced to &str to match the literal pattern
match s.as_str() {
"literal" => { /* ... */ },
_ => { /* ... */ },
}
```
**Byte String Types**
Byte string literal patterns (like `b"bytes"`) have the strict underlying type of a reference to a fixed-size array: `&[u8; N]`. While slice pattern semantics allow them to match against dynamically sized `&[u8]` slices, their inherent type dictates that they match the exact length `N` defined by the literal.
**Floating-Point Restrictions**
Floating-point literals (`1.0`, `3.14`) are technically part of the literal pattern grammar, but their use is forbidden and will trigger compiler errors in modern Rust. This restriction exists because floating-point equality is inherently problematic due to `NaN` (Not-a-Number) representations, which do not equal themselves (`NaN != NaN`), violating the structural equality guarantees required by pattern matching.
**Negative Literals**
In the context of pattern matching, a minus sign `-` immediately preceding an integer literal is parsed as a single, unified literal pattern rather than a unary negation operator applied to an expression. This allows negative numbers to be matched directly without requiring guard clauses.
Tired of Poor Rust Skills? Fix That With Deep Grasping!
Learn More
