Path Pattern

A path pattern is a pattern that matches a value against a named constant, a unit struct, or a unit enum variant resolved through a module path. It evaluates to true if the matched value is structurally equal to the value represented by the path. Unlike identifier patterns, path patterns do not introduce new variable bindings into the local scope; they strictly perform structural equality checks against pre-existing items in the module tree.

Syntax

A path pattern follows standard Rust path resolution syntax. It supports relative paths, absolute paths from the crate root, generic arguments, and fully qualified paths for trait items.

PathPattern :
    PathExpression | QualifiedPathInExpression

PathExpression :
    ( :: | crate :: | self :: | super :: )? PathSegment ( :: PathSegment )*

PathSegment :
    Identifier ( :: GenericArgs )?

QualifiedPathInExpression :
    < Type ( as Trait )? > ( :: PathSegment )+

Resolution Mechanics

The Rust compiler distinguishes between path patterns and identifier patterns based on scope resolution:

1. Multi-segment paths: Any pattern containing a double-colon :: (e.g., Module::Item, Option::None, or <T as Trait>::CONSTANT) is unambiguously parsed as a path pattern.
2. Single-segment paths: If a pattern consists of a single identifier (e.g., Item), the compiler queries the current scope’s value namespace.
   • If the identifier resolves to a constant, unit struct, or unit enum variant, it is treated as a path pattern.
   • If the identifier resolves to another item in the value namespace (such as a tuple struct, tuple enum variant, or a struct with fields), the compiler emits a compilation error (e.g., E0532 or E0533), as these items require tuple or struct patterns.
   • If the identifier does not resolve to any item in the value namespace, it is treated as an identifier pattern and binds the matched value to a new variable.

Resolvable Items

A path pattern must resolve to one of the following item types:

• Constants: Items defined via the const keyword.
• Unit Enum Variants: Variants of an enum that hold no data.
• Unit Structs: Structs defined without fields.

const THRESHOLD: i32 = 10;

#[derive(PartialEq, Eq)]
enum State {
    Halted,
    Running,
    Paused,
}

struct Sentinel;

trait DefaultState {
    const DEFAULT: State;
}

impl DefaultState for State {
    const DEFAULT: State = State::Halted;
}

fn evaluate_pattern(value: i32, state: State, sentinel: Sentinel) {
    // Path pattern resolving to a constant
    match value {
        THRESHOLD => {} 
        _ => {}
    }

    // Path patterns resolving to unit enum variants and constants
    match state {
        <State as DefaultState>::DEFAULT => {} // Fully qualified path pattern (matches Halted)
        crate::State::Running => {}            // Absolute path pattern
        State::Paused => {}                    // Relative path pattern
    }

    // Path pattern resolving to a unit struct
    match sentinel {
        Sentinel => {}
    }
}

Semantics and Constraints

• Structural Equality: When a path pattern resolves to a constant, the pattern matching does not call the PartialEq::eq method. Executing user-defined trait methods during pattern matching would allow arbitrary code execution and side effects. Instead, the compiler relies on intrinsic structural equality.
• Trait Requirements: For a constant of a custom type to be valid in a path pattern, its type must have #[derive(PartialEq, Eq)]. This macro derives the hidden, compiler-internal StructuralPartialEq and StructuralEq traits, which authorize the compiler to perform a structural comparison (field-by-field) of the data.
• Structural Match Restrictions: If a constant contains types that do not implement the structural match traits (such as raw pointers, floating-point numbers, or types with custom, non-derived PartialEq implementations), the compiler will emit a structural match error.
• Refutability: The refutability of a path pattern depends entirely on the item it resolves to. A path pattern is irrefutable if it resolves to a unit struct, a variant of a single-variant enum, or a constant whose type is a singleton (a type with only one possible value, such as ()), meaning any match against it is inherently exhaustive. It is refutable if it resolves to a variant of a multi-variant enum or a constant of a type with multiple possible values (such as an integer or a multi-variant enum).

Master Rust with Deep Grasping Methodology!

Learn More