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

All blocking issues have been resolved:

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

---

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

[fee1-dead]

I have some issues with how the stabilization report and the tests (especially related to this file) are presented.

I think one of the main reasons I was confused about the choice to stabilize let_chains in the 2024 edition was that it wasn't justified as clear as I wanted to. Having taken another look I figured putting it with my own words might be helpful:

let_chains was stabilized on the 2024 edition only, partly because #124085 is only on the 2024 edition. That specifically fixes the drop order of the following code: (play)

#![feature(if_let_guard)]
#![feature(let_chains)]
struct LoudDrop(&'static str);

impl LoudDrop {
    fn meow(&self) -> bool {
        true
    }
} 

impl Drop for LoudDrop {
    fn drop(&mut self) {
        print!("{}", self.0);
    }
}

fn main() {
    if let true = LoudDrop("1").meow()
            && let true = LoudDrop("2").meow()
            && let true = LoudDrop("3").meow()
            && let true = LoudDrop("4").meow()
            && 5 == 2 + 2 {
                
    } else {
        let _x = LoudDrop("5");
    }
    
    println!();
}

Before edition 2024, this code prints 54321. On edition 2024, this code prints 43215. Edition 2024 makes it so that the temporaries created as part of the chain gets dropped before we go to the else block instead of after the else block finishes. #104843 is extremely hard to get fixed before edition 2024, so it was proposed that let chains would only be usable on edition 2024.

Now, coming back to this feature. I was originally confused as to why the "drop order issue" only affected normal if let chains, not while let or if let guards. That's because drop order is only inconsistent when an else block exists. while lets do not have else blocks. if let guards on matches are clearly scoped to the arms. There is no "drop order MIR ICE issue" on these.

But this stabilization report, and the collection of tests should definitely be improved. Some sections, such as

MIR Generation: The Mid-level Intermediate Representation (MIR) generated for if let guards has been carefully reviewed to ensure it aligns with the expected runtime behavior, particularly concerning variable lifetimes and drop order.

and

Unlike let chains in while and regular if the drop order in if let guard is predictable and stable across all editions and even if we writes let chains in if let guard it also works stable across all editions, this was tested by #140981 and compare-drop-order.rs

read like fluff to me. The relationship between drop-order.rs and compare-drop-order.rs was also confusing to me, before taking a closer look to realize that drop-order.rs compares the drop order temporaries as part of a normal if boolean versus an if let in a guard, whereas compare-drop-order.rs compares drop orders in an if let guard over an if let nested in the match.

Except it actually doesn't test the real issue. Here's a different test I wrote (play):

#![feature(if_let_guard)]
#![feature(let_chains)]
struct LoudDrop(&'static str);

impl LoudDrop {
    fn louder(&self) -> LoudDrop {
        Self(Box::leak(format!("({})", self.0).into_boxed_str()))
    }
} 

impl Drop for LoudDrop {
    fn drop(&mut self) {
        print!("{}", self.0);
    }
}

fn main() {
    match () {
        () if let Some(_a) = Some(LoudDrop("1").louder()) &&
        let Some(_b) = Some(LoudDrop("2").louder()) &&
        let 5 = 2 + 2 => (),

        () if let Some(_a) = Some(LoudDrop("3").louder()) &&
        let Some(_b) = Some(LoudDrop("4").louder()) => (),

        () => ()
    }
    
    println!();
    
    if let Some(_a) = Some(LoudDrop("1").louder()) &&
        let Some(_b) = Some(LoudDrop("2").louder()) && let 5 = 2+2 {
    }
    
    if let Some(_a) = Some(LoudDrop("3").louder()) &&
        let Some(_b) = Some(LoudDrop("4").louder()) {
    }

    println!();
}

On edition 2024 it prints

(2)2(1)1(4)4(3)3
(2)2(1)1(4)4(3)3

But before edition 2024 it prints

(2)2(1)1(4)4(3)3
(2)(1)21(4)(3)43

This is part of the issue with the drop order changes. These tests are not targeted enough for the subtlety at play with how consistent if let guard appears with let_chains. In fact, these tests do not test chains at all, and I was primarily concerned with how these components interact.

There are also several issues with the way some tests are described:

exhaustive.rs - validates that if let guards do not affect exhaustiveness checking in match expressions, test fails due missing match arm

This is weird. I would normally write, "validates that if let guards are correctly treated in exhaustiveness checking"

Specifically, a move of a variable inside a guard pattern only actually occurs if that guard pattern matches. This means the move is conditional, and the borrow checker must track this precisely to avoid false move errors or unsound behavior

The test is saying that a conditional move that happens in an if let guard does not affect other arms that try to use the same variable being moved. I wouldn't describe it as "false move errors or unsound behavior".

warns.rs, parens.rs, macro-expanded.rs, guard-mutability-2.rs, ast-validate-guards.rs - shows that if let guards are parsed with strict syntax rules, disallowing parentheses around the let expression and rejecting macro expansions that produce statements instead of expressions. The compiler correctly diagnoses irrefutable patterns, unreachable patterns, mutability violations, and unsupported constructs inside guards, ensuring soundness and clear error messages. The parser fails on invalid syntax without complex recovery, preventing cascading errors and maintaining clarity

reads like fluff. warns.rs does not "ensure soundness". It checks that irrefutable guards and unreachable patterns in guards are correctly warned. (was there rationale and justification for not warning let guards that are irrefutable but bind to some variable? maybe w.r.t moves and stuff, unexplored) guard-mutability-2.rs is not about syntax rules it is about ownership/mutability.

I'm not sure how to proceed and perhaps this is a reason why writing stabilization reports are discouraged for people who are less familiar with the feature. Perhaps it would read better to me if it was rewritten or have the descriptions reworked, but I'm not sure who should be responsible for doing that. And I'm not actually sure if that is necessary given that people on lang already ticked their checkboxes.

[Kivooeo]

i've asked here in this thread about mir tests, i got clear answer that current tests are fine and we dont need more, i did compare mir during pre stabilization to remove some concerns about this, and again, ive asked about adding mir tests here, got answer that we dont need this

compare-drop-order.rs was originally created to show that there is no difference between if let inside match arm and if let guard, to show that they are the same in terms of drop order, this concerns was from @Nadrieril. this test wasnt mean to test let chains inside if let guard, because there is already a test for it #140981

i agree about not best description

reads like fluff. warns.rs does not "ensure soundness". It checks that irrefutable guards and unreachable patterns in guards are correctly warned. (was there rationale and justification for not warning let guards that are irrefutable but bind to some variable? maybe w.r.t moves and stuff, unexplored) guard-mutability-2.rs is not about syntax rules it is about ownership/mutability.

except this part, this is overview of all this tests, it's not a describe of each test, it doesnt mean that warns.rs shows exatcly this and only need for "ensure soundness", i said about this word for word about this test little bit before this part

The compiler correctly diagnoses irrefutable patterns, unreachable patterns

also, i want to acknowledge that a big part of the problem here is simply my inexperience, this is my first time writing a stabilization report, i’ve tried to do my best here, i read many past stabilization PRs before drafting this one, but since there’s no standardized template for stabilization PRs, some parts (especially the descriptions) were challenging

id love to improve this and learn the best practices from those with more experience, im definitely open to questions or suggestions for clarifying parts of the report beyond the points you already mentioned, which i really appreciate

[est31]

reads like fluff

Yeah @Kivooeo 's writings read a bit as if they were LLM enhanced, which sometimes make them less pleasant to read. However that shouldn't itself be a reason to reject the stabilization proposal itself. the intent, covered areas, content, etc of course can always see improvements, but I'd say it's enough for a stabilization report. One needs to give people room to grow and improve, and @Kivooeo has demonstrated willingness of that.

Except it actually doesn't test the real issue. Here's a different test I wrote [...]

Such a comparison is included via #140981 / dcd2736, namely in drop-order-comparisons.rs where:

• t_guard_if_let_chains_then_else is a clone of the edition 2024 variant of t_if_let_chains_then_else, but it's edition independent so it demonstrates that the drop order is the same across all editions.
• same for t_guard_if_let_chains_then and t_if_let_chains_then: we see that edition 2024 drop order prevails.

Note that @Kivooeo linked #140981 in the snippet you were quoting, so the link to a "complicated" drop order test was there.

I was originally confused as to why the "drop order issue" only affected normal if let chains, not while let or if let guards. That's because drop order is only inconsistent when an else block exists. while lets do not have else blocks. if let guards on matches are clearly scoped to the arms. There is no "drop order MIR ICE issue" on these.

As you can see with t_if_let_chains_then, and the example you gave, if let chains do have differing drop order on different editions, even if there is no else block. I have made statements in the past, esp in #140204, that indicate that the absence of an else is enough to get 2024 drop order also on edition 2021, but my understanding has evolved since then. I was wrong, I'm sorry. Please don't get confused by them.

What stopped #140204 from progressing is that the ICE and compilation error inconsistency persists with while let chains, which are the reasons for why we can't stabilize if let chains on 2021. If you look at #140981, it adds tests that show that the match guard variants of those specific examples work both on edition 2021 and edition 2024. I can't find a single test that shows any if let guards edition inconsistency wrt drop order or scoping. So that's why I said it's fine to stabilize them, esp with the experience behind me of all the weird drop order edge cases encountered with if let.

Also, if you take a look, while let is affected by the drop order rescoping. that example has while let give the same output as if let, i.e. edition inconsistent, while if let guard chains are edition consistent and match edition 2024 behaviour of if let and while let. Maybe a possible resolution of #140204 is to apply edition independent drop order rescoping for while. If that doesn't break anyone (as while doesn't have an else), we can roll it out to get while let chains stable across editions. IDK, it needs further experiments.

I hope I could make it a little bit more clear why I think that it's fine to stabilize if let guards on all editions.

[Kivooeo]

i updated description, please take a look, it should be a way better now, more straightforward and clear to readers

i also wondering, if i should mention such case, because i said earlier that regular if let and if let guard are the same in terms of drop order, which is true when we are not using let chains inside, for example it wont be true that drop order is the same here for all editions if i understand that correctly, but not sure if i should mention this in description or write a test for it?

match Some(2) {
    Some(x)
        if let Some(y) = Some(3)
            && y > 5
            && x > 5 => {}
    _ => (),
}


match Some(2) {
    Some(x) => {
        if let Some(y) = Some(3)
            && y > 5
            && x > 5
        {}
    }
    _ => (),
}

[est31]

Note that those already are let chains, as there is a let and there is an &&. Even if in those simpler cases the drop order is the same (not 100% sure if it is indeed the same), that doesn't imply that drop order is the same in every possible way to use the feature.

[fee1-dead]

re Kivooeo:

this is overview of all this tests, it's not a describe of each test, it doesnt mean that warns.rs shows exatcly this and only need for "ensure soundness", i said about this word for word about this test little bit before this part

The compiler correctly diagnoses irrefutable patterns, unreachable patterns

Yes, but that is being grouped with other tests that supposedly ensure soundness, and I dislike the grouping. Warnings like those shouldn't be grouped with the other tests.

also, i want to acknowledge that a big part of the problem here is simply my inexperience, this is my first time writing a stabilization report, i’ve tried to do my best here, i read many past stabilization PRs before drafting this one, but since there’s no standardized template for stabilization PRs, some parts (especially the descriptions) were challenging

I appreciate your boldness in writing stabilization reports, and I appreciate the work you have put in. On the other hand, I also want to make sure that everyone who has agreed to stabilizing the feature to fully understand what the state of the feature is. Improving the stabilization report not only helps current people who are interested in the feature, but also for future people stabilizing similar features looking for past stabilization reports, or for people interested in our language design and this feature's history.

I want our stabilization reports to be something that is first and foremost accurate. This includes not having potentially misleading summaries.

re est31:

that shouldn't itself be a reason to reject the stabilization proposal itself

I don't personally want to reject it, but I want to strongly urge something to be done. And given that this proposal is in FCP, nothing else would prevent it from passing except registering it as a blocker. And it would be unfortunate if this passes and no improvements are made.

Such a comparison is included via #140981 / dcd2736, namely in drop-order-comparisons.rs where:

That's nice, but it looks like that was added after my review? Anyways, all good if we can include some summary/explanation for this.

I can't find a single test that shows any if let guards edition inconsistency wrt drop order or scoping. So that's why I said it's fine to stabilize them

I trust your expertise in this area, but stabilization of language features also involve summarizing the language feature. Absence of compiler bugs, while reassuring on its own, does not give us insight to the hows and whys. I wrote those tests in my comment above in hopes of having a concise example of some of the drop order changes we're dealing with and using those to justify our decision. IMO, we should have both compiler ui tests to point to to say that these bugs/issues don't carry over, as well as conceptual reasoning for why these bugs/issues don't apply to if let guards. To me it seemed like the latter was lacking.

[Kivooeo]

thanks for your feedback - i just want to make sure that we are on the same page

i updated the stabilization pr description a couple of days ago, based on your prev comments, the overview section is now clarified what each test is meant to show

could you please take a look at the updated version when you get the chance? i believe it already addresses most of the concers you've raised here, if there anything i can improve, please tell me, we can work on this together to make it clearer to readers

thanks again for taking the time to review it - i really appreaciate the push for clarity and accuracy

[bors]

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

[est31]

Just as a note, I'll be doing a trip from June 7 until June 16, and I don't think I will be bringing my laptop so I won't be able to review this right after the FCP finishes. This might put the stabilization into a later release due to the cutoff being June 20. Feel free to look for other reviewers or wait until I'm back again.

[Kivooeo]

@est31
since you'll be away when the FCP ends, maybe it would make sense to share some of your thoughts on the final review a bit earlier? It doesn't have to be anything formal — even a rough idea of what you'd be looking for could be helpful for another reviewer stepping in while you're offline
given that it's unlikely any new blockers will show up before the FCP finishes, I think it would make sense to share your thoughts now if you have the time
i really appreciate your insights and want to make sure the process goes as smoothly as possible before the cutoff
(also hope you have a great trip!)

[est31]

r=me if FCP passes, PR is squashed, and the nits are addressed

[fee1-dead]

This, and the change at library/std/src/lib.rs are no longer needed after #119899

[fee1-dead]

This should be removed

[Kivooeo]

i actually cant remove this ones too because CI fails

[fee1-dead]

This should be removed

[fee1-dead]

This should be removed

[Kivooeo]

actually not gives me to remove this one, but all above was removed successfuly

   Compiling rustdoc v0.0.0 (/Users/meow/projects/rust/src/librustdoc)
error[E0658]: `if let` guards are experimental
   --> src/librustdoc/clean/mod.rs:852:49
    |
852 |                     ty::ClauseKind::Trait(pred) if let ty::Param(param) = pred.self_ty().kind() => {
    |                                                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    |
    = note: see issue #51114 <https://github.com/rust-lang/rust/issues/51114> for more information
    = help: add `#![feature(if_let_guard)]` to the crate attributes to enable
    = note: this compiler was built on 2025-05-25; consider upgrading it if it is out of date
    = help: you can write `if matches!(<expr>, <pattern>)` instead of `if let <pattern> = <expr>`