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 - Check drop order of temporaries create in match guards
• 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
• drop-order-comparisons-let-chains.rs - Compares drop order between let chains in if let guard and regular if expressions
• if-let-guards.rs - Test correctness of drop order for bindings and temporaries
• if-let-guards-2 - The same test as above but more comprehensive and tests more interactions between different features and their drop order, checking that drop order is correct, created by @traviscross

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 (specify if let guards with updated scoping rules reference#1957)
• (non-blocking) add tests for this and this

---

Related:

• Tracking Issue: Tracking issue for RFC 2294, "if let guard" #51114
• RFC: propose if let guard rfcs#2294
• Documentation PR: specify if let guards with updated scoping rules reference#1957

[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

[rustbot]

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

[est31]

Today I had the time to give this a closer look/load the problem space back into memory, and re-read this thread as well as the code changes.

The implementation looks good to me. Since my earlier positive review, the stabilization has been held back by two issues: the reference PR as well as drop order concerns raised by @dianne .

Since then, the reference PR has been approved (I found a minor issue in it but it's easy to fix), and @dianne 's concerns have been resolved.

Giving the tests another look and what is being tested, there is some minor things that could get tests:

• There is two outstanding tests mentioned here but I'd agree they are not blockers. Would be useful to have them though!

• I had a look at the if let chains edition 2024 gating I added in Stabilize let chains in the 2024 edition #132833 (for let chains in normal if's and while, not match guards). I couldn't find an instance where it's tested that the edition gating of if let chains survives being nested into if let guards. I.e. it's a common mistake to make to track such thing via a global bool variable, instead of having something stack-like that gets opened/destroyed if a new construct is entered/left. The current behavior of the compiler is fine, but it would be nice to have a test to ensure that code like errors on editions<2024:

  let foo = Some(123);
  match foo {
    Some(x) if let v = (if let Some(0) = None && true {} else {}) && let Some(3u32) = None => {}
    _ => {}
  }

• Lastly, I wonder if warns.rs could be extended to test for irrefutable_let_patterns, especially trailing irrefutable patterns i.e. let x = 0.

r=me with the latter two concerns addressed.

[Kivooeo]

• Lastly, I wonder if warns.rs could be extended to test for irrefutable_let_patterns, especially trailing irrefutable patterns i.e. let x = 0

could you take a look on warns.rs, it's a bit of unclear to me on "trailing irrefutable patterns" part, i added two new cases, but yet not sure if that's what you originally meant

[fee1-dead]

LGTM, had a tiny nit but doesn't need to affect this landing. Thanks to everyone who pushed to made this happen!

View changes since this review

[fee1-dead]

nit: this should be #![deny(irrefutable_let_patterns)] - no point in only applying to the individual functions

[fee1-dead]

@bors r=fee1-dead,est31

[rust-bors]

📌 Commit 964b63f has been approved by fee1-dead,est31

It is now in the queue for this repository.

[fee1-dead]

@bors rollup=never

[est31]

could you take a look on warns.rs, it's a bit of unclear to me on "trailing irrefutable patterns" part

it's precisely what I wanted, thanks!

[traviscross]

Cc @rust-lang/fls on an upcoming stabilization.

[JonathanBrouwer]

@bors p=2
Scheduling this before the stdarch subtree update

[rust-bors]

☀️ Test successful - CI
Approved by: fee1-dead,est31
Duration: 4h 13m 40s
Pushing e0cb264 to main...

[github-actions]

What is this?

This is an experimental post-merge analysis report that shows differences in test outcomes between the merged PR and its parent PR.

Comparing c043085 (parent) -> e0cb264 (this PR)

Test differences

Show 68 test diffs

Stage 1

• [ui] tests/ui/drop/if-let-guards-2.rs: [missing] -> pass (J0)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/compare-drop-order.rs#edition2015: [missing] -> pass (J0)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/compare-drop-order.rs#edition2018: [missing] -> pass (J0)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/compare-drop-order.rs#edition2021: [missing] -> pass (J0)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/compare-drop-order.rs#edition2024: [missing] -> pass (J0)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/const-expr.rs: pass -> [missing] (J0)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/const-expr.rs#edition2021: [missing] -> pass (J0)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/const-expr.rs#edition2024: [missing] -> pass (J0)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/drop-order.rs: pass -> [missing] (J0)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/drop-order.rs#edition2021: [missing] -> pass (J0)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/drop-order.rs#edition2024: [missing] -> pass (J0)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/drop-scope.rs: pass -> [missing] (J0)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/drop-scope.rs#edition2021: [missing] -> pass (J0)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/drop-scope.rs#edition2024: [missing] -> pass (J0)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/feature-gate.rs: pass -> [missing] (J0)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/let-chains-gated-correctly-in-guard.rs: [missing] -> pass (J0)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/move-guard-if-let-chain.rs: pass -> [missing] (J0)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/move-guard-if-let-chain.rs#edition2021: [missing] -> pass (J0)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/move-guard-if-let-chain.rs#edition2024: [missing] -> pass (J0)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/scope.rs: pass -> [missing] (J0)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/scope.rs#edition2021: [missing] -> pass (J0)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/scope.rs#edition2024: [missing] -> pass (J0)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/scoping-consistency-async.rs: pass -> [missing] (J0)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/scoping-consistency-async.rs#edition2018: [missing] -> pass (J0)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/scoping-consistency-async.rs#edition2021: [missing] -> pass (J0)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/scoping-consistency-async.rs#edition2024: [missing] -> pass (J0)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/scoping-consistency.rs: pass -> [missing] (J0)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/scoping-consistency.rs#edition2021: [missing] -> pass (J0)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/scoping-consistency.rs#edition2024: [missing] -> pass (J0)
• [ui] tests/ui/rfcs/rfc-2497-if-let-chains/if_let_guard_indirect_let_chains.rs: [missing] -> pass (J0)
• [ui] tests/ui/rfcs/rfc-2497-if-let-chains/issue-93150.rs: pass -> [missing] (J0)

Stage 2

• [ui] tests/ui/drop/if-let-guards-2.rs: [missing] -> pass (J1)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/compare-drop-order.rs#edition2015: [missing] -> pass (J1)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/compare-drop-order.rs#edition2018: [missing] -> pass (J1)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/compare-drop-order.rs#edition2021: [missing] -> pass (J1)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/compare-drop-order.rs#edition2024: [missing] -> pass (J1)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/const-expr.rs: pass -> [missing] (J1)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/const-expr.rs#edition2021: [missing] -> pass (J1)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/const-expr.rs#edition2024: [missing] -> pass (J1)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/drop-order.rs: pass -> [missing] (J1)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/drop-order.rs#edition2021: [missing] -> pass (J1)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/drop-order.rs#edition2024: [missing] -> pass (J1)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/drop-scope.rs: pass -> [missing] (J1)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/drop-scope.rs#edition2021: [missing] -> pass (J1)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/drop-scope.rs#edition2024: [missing] -> pass (J1)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/feature-gate.rs: pass -> [missing] (J1)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/let-chains-gated-correctly-in-guard.rs: [missing] -> pass (J1)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/move-guard-if-let-chain.rs: pass -> [missing] (J1)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/move-guard-if-let-chain.rs#edition2021: [missing] -> pass (J1)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/move-guard-if-let-chain.rs#edition2024: [missing] -> pass (J1)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/scope.rs: pass -> [missing] (J1)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/scope.rs#edition2021: [missing] -> pass (J1)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/scope.rs#edition2024: [missing] -> pass (J1)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/scoping-consistency-async.rs: pass -> [missing] (J1)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/scoping-consistency-async.rs#edition2018: [missing] -> pass (J1)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/scoping-consistency-async.rs#edition2021: [missing] -> pass (J1)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/scoping-consistency-async.rs#edition2024: [missing] -> pass (J1)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/scoping-consistency.rs: pass -> [missing] (J1)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/scoping-consistency.rs#edition2021: [missing] -> pass (J1)
• [ui] tests/ui/rfcs/rfc-2294-if-let-guard/scoping-consistency.rs#edition2024: [missing] -> pass (J1)
• [ui] tests/ui/rfcs/rfc-2497-if-let-chains/if_let_guard_indirect_let_chains.rs: [missing] -> pass (J1)
• [ui] tests/ui/rfcs/rfc-2497-if-let-chains/issue-93150.rs: pass -> [missing] (J1)

Additionally, 6 doctest diffs were found. These are ignored, as they are noisy.

Job group index

• J0: x86_64-gnu-llvm-20-3, x86_64-gnu-llvm-21-3
• J1: aarch64-apple, aarch64-gnu, aarch64-gnu-llvm-20-1, aarch64-msvc-1, arm-android, armhf-gnu, dist-i586-gnu-i586-i686-musl, i686-gnu-1, i686-gnu-nopt-1, i686-msvc-1, test-various, x86_64-gnu, x86_64-gnu-debug, x86_64-gnu-gcc, x86_64-gnu-llvm-20, x86_64-gnu-llvm-20-2, x86_64-gnu-llvm-21-2, x86_64-gnu-nopt, x86_64-gnu-stable, x86_64-mingw-1, x86_64-msvc-1

Test dashboard

Run

cargo run --manifest-path src/ci/citool/Cargo.toml -- \
    test-dashboard e0cb264b814526acb82def4b5810e394a2ed294f --output-dir test-dashboard

And then open test-dashboard/index.html in your browser to see an overview of all executed tests.

Job duration changes

1. dist-arm-linux-musl: 5h 51m -> 1h 40m (-71.5%)
2. dist-x86_64-solaris: 5h 3m -> 1h 43m (-66.0%)
3. dist-sparcv9-solaris: 4h 34m -> 1h 34m (-65.6%)
4. dist-x86_64-musl: 5h 6m -> 2h 13m (-56.6%)
5. dist-powerpc64le-linux-musl: 2h 50m -> 1h 32m (-45.6%)
6. dist-powerpc64-linux-musl: 2h 47m -> 1h 32m (-44.6%)
7. dist-powerpc64le-linux-gnu: 2h 49m -> 1h 34m (-44.4%)
8. dist-x86_64-netbsd: 2h 32m -> 1h 25m (-44.1%)
9. dist-armhf-linux: 2h 39m -> 1h 31m (-42.8%)
10. dist-powerpc-linux: 2h 31m -> 1h 27m (-42.2%)

How to interpret the job duration changes?

Job durations can vary a lot, based on the actual runner instance
that executed the job, system noise, invalidated caches, etc. The table above is provided
mostly for t-infra members, for simpler debugging of potential CI slow-downs.

[rust-timer]

Finished benchmarking commit (e0cb264): comparison URL.

Overall result: ❌ regressions - no action needed

@rustbot label: -perf-regression

Instruction count

Our most reliable metric. Used to determine the overall result above. However, even this metric can be noisy.

	mean	range	count
Regressions ❌ (primary)	-	-	0
Regressions ❌ (secondary)	0.4%	[0.3%, 0.5%]	7
Improvements ✅ (primary)	-	-	0
Improvements ✅ (secondary)	-	-	0
All ❌✅ (primary)	-	-	0

Max RSS (memory usage)

Results (primary 2.6%, secondary 0.2%)

A less reliable metric. May be of interest, but not used to determine the overall result above.

	mean	range	count
Regressions ❌ (primary)	3.8%	[3.3%, 4.8%]	5
Regressions ❌ (secondary)	2.9%	[2.1%, 3.8%]	3
Improvements ✅ (primary)	-3.5%	[-3.5%, -3.5%]	1
Improvements ✅ (secondary)	-3.9%	[-5.5%, -2.2%]	2
All ❌✅ (primary)	2.6%	[-3.5%, 4.8%]	6

Cycles

This benchmark run did not return any relevant results for this metric.

Binary size

This benchmark run did not return any relevant results for this metric.

Bootstrap: 479.769s -> 487.064s (1.52%)
Artifact size: 397.87 MiB -> 397.85 MiB (-0.00%)