Stabilize if let guards (feature(if_let_guard))

[Kivooeo]

Summary

This proposes the stabilization of if let guards (tracking issue: #51114, RFC: rust-lang/rfcs#2294). This feature allows if let expressions to be used directly within match arm guards, enabling conditional pattern matching within guard clauses.

What is being stabilized

The ability to use if let expressions within match arm guards.

Example:

enum Command {
    Run(String),
    Stop,
    Pause,
}

fn process_command(cmd: Command, state: &mut String) {
    match cmd {
        Command::Run(name) if let Some(first_char) = name.chars().next() && first_char.is_ascii_alphabetic() => {
            // Both `name` and `first_char` are available here
            println!("Running command: {} (starts with '{}')", name, first_char);
            state.push_str(&format!("Running {}", name));
        }
        Command::Run(name) => {
            println!("Cannot run command '{}'. Invalid name.", name);
        }
        Command::Stop if state.contains("running") => {
            println!("Stopping current process.");
            state.clear();
        }
        _ => {
            println!("Unhandled command or state.");
        }
    }
}

Motivation

The primary motivation for if let guards is to reduce nesting and improve readability when conditional logic depends on pattern matching. Without this feature, such logic requires nested if let statements within match arms:

// Without if let guards
match value {
    Some(x) => {
        if let Ok(y) = compute(x) {
            // Both `x` and `y` are available here
            println!("{}, {}", x, y);
        }
    }
    _ => {}
}

// With if let guards
match value {
    Some(x) if let Ok(y) = compute(x) => {
        // Both `x` and `y` are available here
        println!("{}, {}", x, y);
    }
    _ => {}
}

Implementation and Testing

The feature has been implemented and tested comprehensively across different scenarios:

Core Functionality Tests

Scoping and variable binding:

• scope.rs - Verifies that bindings created in if let guards are properly scoped and available in match arms
• shadowing.rs - Tests that variable shadowing works correctly within guards
• scoping-consistency.rs - Ensures temporaries in guards remain valid for the duration of their match arms

Type system integration:

• type-inference.rs - Confirms type inference works correctly in if let guards
• typeck.rs - Verifies type mismatches are caught appropriately

Pattern matching semantics:

• exhaustive.rs - Validates that if let guards are correctly handled in exhaustiveness analysis
• move-guard-if-let.rs and move-guard-if-let-chain.rs - Test that conditional moves in guards are tracked correctly by the borrow checker

Error Handling and Diagnostics

• warns.rs - Tests warnings for irrefutable patterns and unreachable code in guards
• parens.rs - Ensures parentheses around let expressions are properly rejected
• macro-expanded.rs - Verifies macro expansions that produce invalid constructs are caught
• guard-mutability-2.rs - Tests mutability and ownership violations in guards
• ast-validate-guards.rs - Validates AST-level syntax restrictions

Drop Order and Temporaries

Key insight: Unlike let_chains in regular if expressions, if let guards do not have drop order inconsistencies because:

1. Match guards are clearly scoped to their arms
2. There is no "else block" equivalent that could cause temporal confusion

• drop-order.rs - Tests that temporaries in guards are dropped at the correct time
• compare-drop-order.rs - Compares drop order between if let guards and nested if let in match arms, confirming they behave identically across all editions
• Add match guard let chain drop order and scoping tests #140981 - A complicated drop order test involved let chain was made by @est31

Edition Compatibility

This feature stabilizes on all editions, unlike let_chains which was limited to edition 2024. This is safe because:

1. if let guards don't suffer from the drop order issues that affected let_chains in regular if expressions
2. The scoping is unambiguous - guards are clearly tied to their match arms
3. Extensive testing confirms identical behavior across all editions

Interactions with Future Features

The lang team has reviewed potential interactions with planned "guard patterns" and determined that stabilizing if let guards now does not create obstacles for future work. The scoping and evaluation semantics established here align with what guard patterns will need.

Unresolved Issues

• - Add match guard let chain drop order and scoping tests #140981
• - added tests description by @jieyouxu request
• - Concers from @scottmcm about stabilizing this across all editions
• - check if drop order in all edition when using let chains inside if let guard is the same
• - interactions with guard patters
• - pattern bindings drops before guard bindings add a scope for if let guard temporaries and bindings #143376
• - documentaion

---

Related:

• Tracking Issue: Tracking issue for RFC 2294, "if let guard" #51114
• RFC: propose if let guard rfcs#2294
• Documentation PR: if let guards documentation reference#1823

[rustbot]

r? @SparrowLii

rustbot has assigned @SparrowLii.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[rustbot]

Some changes occurred to the CTFE machinery

cc @RalfJung, @oli-obk, @lcnr

Some changes occurred to MIR optimizations

cc @rust-lang/wg-mir-opt

Some changes occurred in compiler/rustc_codegen_ssa

cc @WaffleLapkin

[rustbot]

rust-analyzer is developed in its own repository. If possible, consider making this change to rust-lang/rust-analyzer instead.

cc @rust-lang/rust-analyzer

Some changes occurred in src/tools/clippy

cc @rust-lang/clippy

[traviscross]

cc @est31 @ehuss

[traviscross]

cc @Nadrieril

[SparrowLii]

This needs a fcp so I'd like to roll this to someone more familiar with this feature
r? compiler

[oli-obk]

r? @est31

[Kivooeo]

(little off-topic but i have to say it) Thank you for the kind words! I also hope I’ll be able to return to working on Rust project. I still have some ambitious plans for reorganizing the tests that I wanted to finish this summer, but unfortunately I’ll have to postpone them until next year.

Regarding my previous message: I think it can serve as a good new starting point and help anyone interested in stabilizing this feature understand where things stand right now. I tried to summarize everything that’s currently relevant and that might help going forward.

Thanks again to everyone — I’ll definitely be back to work on Rust!

[bors]

☔ The latest upstream changes (presumably #143766) made this pull request unmergeable. Please resolve the merge conflicts.

[bors]

☔ The latest upstream changes (presumably #144526) made this pull request unmergeable. Please resolve the merge conflicts.

[dianne]

#143376 is merged now, so I believe the drop-order-bug-found-by-dianne concern can be resolved. cc @traviscross
I'm not totally sure how to go about guaranteeing test coverage for all corner cases, but we're closer now at least. The other unique/subtle scope/drop-related interaction I know if let guards have is with |s in the match arm's pattern. There's already quite a few tests for that, and as far as I can tell from reading the implementation it should work as expected. But only tests with if let guards over or-patterns will hit the relevant MIR-building codepath, so it's also worth considering if looking for corner cases.

And I'd be happy to pick up work on documenting if let guards and/or maintaining a stabilization PR if you're unable, @Kivooeo. I think you'd either need to give me permissions or I'd need to make my own PRs, but I'm interested in getting if_let_guard stabilized.

[jieyouxu]

Before reattempting stabilization, should a call for testing period be conducted to invite contributors to explicitly try to break this feature? Especially with a focus on weird (or even outright wrong) drop order interactions, given the near miss.

[Kivooeo]

Yes, if this is what we can easily do and have a lot of wishing to test this out then why not

About the documentation part, @dianne, yes you absolutely can open your own PR for documentation (I will close mine accordigly after that), but you might want to check mine if there anything valuable you can reuse (for examples syntax is correct)

As for this PR I could maintain this until October, hopefully we will get somewhere until this moment

And, feel free to ask anything to help when you will work on guard patterns in future!

[theemathas]

This code compiles. Is it supposed to?

#![feature(if_let_guard)]

struct One(Two);
struct Two(Box<i32>);

fn main() {
    let a = One(Two(Box::new(1)));
    println!("{:p}", &a);
    match a {
        One(x) if let Two(ref y) = x => {
            // Using y here causes a compile error
            println!("{:p}", &x);
        }
        _ => {}
    }
}

[dianne]

I'd argue yes: y can be used later within the guard:

#![feature(if_let_guard)]

struct One(Two);
struct Two(Box<i32>);

fn main() {
    let a = One(Two(Box::new(1)));
    println!("{:p}", &a);
    match a {
        One(x) if let Two(ref y) = x
            // `y` is `&a.0` before `a.0` is moved into `x`
            && { println!("{y:p}"); true } =>
        {
            // Using y here causes a compile error
            println!("{:p}", &x);
        }
        _ => {}
    }
}

This is in essence the same as a guard like One(x) if guard(&x): guard runs before the binding is moved out of the scrutinee, so it sees the pre-move address.

[theemathas]

This isn't necessarily wrong, but I think users will find this behavior surprising:

#![feature(if_let_guard)]

fn main() {
    match 1 {
        mut x if let y = &x => {
            x = 2;
            // prints 1
            println!("{y}");
        }
        _ => {}
    }
}

[dianne]

That is a bit funny.. it's consistent with stable non-if let guard behavior, but it's definitely easier to hit with an if let guard. I wonder if it'd be worth linting (maybe in clippy?) on guards that do certain things with references to by-mut-copy bindings. We could suggest making the binding non-mut and adding a separate let mut in the arm body, to make it clearer that the mutable x is a copy and y is not a reference to it.

For comparison, a normal guard that also exhibits this, which I'd want to behave the same as your if let guard:

fn main() {
    let y;
    match 1 {
        mut x if { y = &x; true } => {
            x = 2;
            // prints 1
            println!("{y}");
        }
        _ => {}
    }
}

[theemathas]

This compiles. Is it supposed to?

#![feature(if_let_guard)]

struct Thing;

fn foo() -> &'static Thing {
    match Thing {
        x if let y = &x => {
            {
                // This should drop `x`, invalidating `y`.
                let a = x;
            }
            y
        }
        _ => {
            panic!();
        }
    }
}

See also #144939, which has similar behavior.

Edit: This seems to have similar behavior on normal if guards. I'm filing a separate issue.