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.

// 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:

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.

Master Rust with Deep Grasping Methodology!

Learn More