Path Pattern

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.

​

Syntax

PathPattern :
    PathExpression | QualifiedPathInExpression

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

PathSegment :
    Identifier ( :: GenericArgs )?

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

​

Resolution Mechanics

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

• 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).