`if let` guards documentation #1823

Kivooeo · 2025-05-10T16:49:57Z

It’s been a while since the original PR for if let guards was opened, so I decided to take the initiative and push it a bit closer to stabilization

This PR adds some documentation — I did my best to keep it consistent with the existing docs on if guards
There might still be some rough edges or small inaccuracies, so feel free to point them out

It’s also my first time contributing to the docs, so any feedback is appreciated!

Tracking issue rust-lang/rust#51114
Stabilization: rust-lang/rust#141295

rendered

WaffleLapkin · 2025-05-16T13:02:05Z

src/expressions/match-expr.md

+```rust,ignore
+match expression {
+    pattern if let subpattern = guard_expr => arm_body,
+    ...
+}
+```


Would it be possible to make a working example?

Im not really sure, because it's not stable feature and contains behind #![feature...] gate that's aren't allowed in documentation and CI will fail with this error

Running target/debug/style-check ../src error in ../src/expressions/match-expr.md: #![feature] attributes are not allowed

You can just add a full example that will fail CI for now.

src/expressions/match-expr.md

WaffleLapkin · 2025-05-16T13:19:43Z

src/expressions/match-expr.md

+* The `if let` guard may refer to variables bound by the outer match pattern.
+* New variables bound inside the `if let` guard (e.g., `y` in the example above) are available within the body of the match arm where the guard evaluates to `true`, but are not accessible in other arms or outside the match expression.
+
+```rust,ignore


Suggested change

```rust,ignore

```rust

WaffleLapkin · 2025-05-16T13:21:44Z

src/expressions/match-expr.md

+  2. Guard evaluation happens after that, and:
+      * It runs using a shared borrow of the scrutinee
+      * You cannot move from the scrutinee inside the guard.
+      * New bindings created inside the guard (e.g., via `if let Some(y) = expr`) are local to the guard and do not persist into the match arm body.


What does that mean?

I've updated it and it now should make more sense

src/expressions/match-expr.md

WaffleLapkin · 2025-05-16T13:23:10Z

src/expressions/match-expr.md

+      ```
+> [!NOTE]
+> Unlike regular if guards, `if let` guards execute only once per match arm, even if the pattern uses the `|` operator to match multiple patterns. This avoids repeated evaluation and potential side effects.
+> ```rust,ignore


Suggested change

> ```rust,ignore

> ```rust

src/expressions/match-expr.md

Kivooeo · 2025-05-16T15:57:18Z

@WaffleLapkin not sure if you got notifications when i update something, but i update almost all your reviews expect ones that asks to make code runnable, because im not sure if this is possible, we can remove ignore after it will stabilize, is that fine?

src/expressions/match-expr.md

…31,fee1-dead Stabilize `if let` guards (`feature(if_let_guard)`) ## Summary This proposes the stabilization of `if let` guards (tracking issue: rust-lang#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: ```rust 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: ```rust // 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`](https://github.com/rust-lang/rust/blob/5796073c134eaac30475f9a19462c4e716c9119c/tests/ui/rfcs/rfc-2294-if-let-guard/scope.rs) - Verifies that bindings created in `if let` guards are properly scoped and available in match arms - [`shadowing.rs`](https://github.com/rust-lang/rust/blob/5796073c134eaac30475f9a19462c4e716c9119c/tests/ui/rfcs/rfc-2294-if-let-guard/shadowing.rs) - Tests that variable shadowing works correctly within guards - [`scoping-consistency.rs`](https://github.com/rust-lang/rust/blob/5796073c134eaac30475f9a19462c4e716c9119c/tests/ui/rfcs/rfc-2294-if-let-guard/scoping-consistency.rs) - Ensures temporaries in guards remain valid for the duration of their match arms **Type system integration:** - [`type-inference.rs`](https://github.com/rust-lang/rust/blob/5796073c134eaac30475f9a19462c4e716c9119c/tests/ui/rfcs/rfc-2294-if-let-guard/type-inference.rs) - Confirms type inference works correctly in `if let` guards - [`typeck.rs`](https://github.com/rust-lang/rust/blob/5796073c134eaac30475f9a19462c4e716c9119c/tests/ui/rfcs/rfc-2294-if-let-guard/typeck.rs) - Verifies type mismatches are caught appropriately **Pattern matching semantics:** - [`exhaustive.rs`](https://github.com/rust-lang/rust/blob/5796073c134eaac30475f9a19462c4e716c9119c/tests/ui/rfcs/rfc-2294-if-let-guard/exhaustive.rs) - Validates that `if let` guards are correctly handled in exhaustiveness analysis - [`move-guard-if-let.rs`](https://github.com/rust-lang/rust/blob/5796073c134eaac30475f9a19462c4e716c9119c/tests/ui/rfcs/rfc-2294-if-let-guard/move-guard-if-let.rs) and [`move-guard-if-let-chain.rs`](https://github.com/rust-lang/rust/blob/5796073c134eaac30475f9a19462c4e716c9119c/tests/ui/rfcs/rfc-2294-if-let-guard/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`](https://github.com/rust-lang/rust/blob/5796073c134eaac30475f9a19462c4e716c9119c/tests/ui/rfcs/rfc-2294-if-let-guard/warns.rs) - Tests warnings for irrefutable patterns and unreachable code in guards - [`parens.rs`](https://github.com/rust-lang/rust/blob/5796073c134eaac30475f9a19462c4e716c9119c/tests/ui/rfcs/rfc-2294-if-let-guard/parens.rs) - Ensures parentheses around `let` expressions are properly rejected - [`macro-expanded.rs`](https://github.com/rust-lang/rust/blob/5796073c134eaac30475f9a19462c4e716c9119c/tests/ui/rfcs/rfc-2294-if-let-guard/macro-expanded.rs) - Verifies macro expansions that produce invalid constructs are caught - [`guard-mutability-2.rs`](https://github.com/rust-lang/rust/blob/5796073c134eaac30475f9a19462c4e716c9119c/tests/ui/rfcs/rfc-2294-if-let-guard/guard-mutability-2.rs) - Tests mutability and ownership violations in guards - [`ast-validate-guards.rs`](https://github.com/rust-lang/rust/blob/5796073c134eaac30475f9a19462c4e716c9119c/tests/ui/rfcs/rfc-2497-if-let-chains/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`](https://github.com/rust-lang/rust/blob/5796073c134eaac30475f9a19462c4e716c9119c/tests/ui/rfcs/rfc-2294-if-let-guard/drop-order.rs) - Tests that temporaries in guards are dropped at the correct time - [`compare-drop-order.rs`](https://github.com/rust-lang/rust/blob/aef3f5fdf052fbbc16e174aef5da6d50832ca316/tests/ui/rfcs/rfc-2294-if-let-guard/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 - rust-lang#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: - [x] - rust-lang#140981 - [x] - added tests description by `@jieyouxu` request - [x] - Concers from `@scottmcm` about stabilizing this across all editions - [x] - check if drop order in all edition when using `let chains` inside `if let` guard is the same - [x] - interactions with guard patters --- **Related:** - Tracking Issue: rust-lang#51114 - RFC: rust-lang/rfcs#2294 - Documentation PR: rust-lang/reference#1823

workingjubilee · 2025-06-07T21:42:44Z

@rustbot label -S-waiting-on-stabilization

jackh726 · 2025-06-09T15:11:16Z

src/expressions/match-expr.md

+
+r[expr.match.if.let.guard.scope]
+* The `if let` guard may refer to variables bound by the outer match pattern.
+* New variables bound inside the `if let` guard (e.g., `y` in the example above) are available within the body of the match arm where the guard evaluates to `true`, but are not accessible in other arms or outside the match expression.


May be worth being a bit more precise w.r.t drop behavior (i.e. that anything bound in the if let guards are dropped before evaluating other match arms)?

Sure, we can add something like this

r[expr.match.if.let.guard.drop] * Variables bound inside `if let` guards are dropped before evaluating subsequent match arms. * Temporaries created during guard evaluation follow standard drop semantics and are cleaned up appropriately.

What's your opinion on this?

Drop behavior should be documented in the destructors chapter. I would expect it to be somewhat similar to the changes that were made for if (such as in destructors.scope.temporary.enclosing).

The stabilization report doesn't explain what the drop order is or how temporaries are handled, so it is difficult for me to evaluate what this should say.

Something like this? I'm just not sure how full should be explanation about drop order

r[destructors.scope.temporary.if-let-guard] ### If Let Guards in Match Expressions When an `if let` guard is evaluated in a match expression: 1. **Guard evaluation scope**: Variables bound by the `if let` pattern and any temporaries created during guard evaluation have a scope that extends through the match arm body if the guard succeeds. 2. **Failed guard cleanup**: If the `if let` guard fails to match: - Any variables bound by the guard pattern are immediately dropped - Temporaries created during guard evaluation are dropped - Pattern matching continues to the next arm 3. **Successful guard**: If the guard succeeds: - Guard-bound variables remain live for the duration of the match arm body - They are dropped at the end of the match arm execution 4. **Multiple guards**: In arms with multiple guards connected by `&&`: - Each failed guard drops its own bindings before evaluating the next guard - Only successful guard bindings are available in the arm body #### Example ...

ehuss

Later I'm going to do a cleanup pass, as there are a number of changes I want to make.

I'm wondering if it is possible to defer most of this documentation to the if chapter? It already explains how chains work and such, and it seems like it could just link to that instead of re-explaining it?

Are there changes to names.scopes.pattern-bindings needed to define the scopes of these bindings?

ehuss · 2025-06-09T18:54:06Z

src/expressions/match-expr.md

+MatchArmGuard ->
+    `if` MatchConditions
+
+MatchConditions ->
+    MatchCondition ( `&&` MatchCondition )*
+
+MatchCondition ->
+      OuterAttribute* `let` Pattern `=` Scrutinee
+    | Expression


This seems to be missing some things.

Similar to if expressions, this will need two separate rules. Something like Expression | MatchConditions because without a let it is allowed to have LazyBooleanExpression. Then, MatchConditions will need to exclude LazyBooleanExpression.

I don't think this should use Scrutinee, because that rejects StructExpression, but that is allowed here.

This will also need similar precedence restrictions as if let has with restricting LazyBooleanExpression | RangeExpr | RangeFromExpr | RangeInclusiveExpr | AssignmentExpression | CompoundAssignmentExpression.

I guess, something simple like this should work right? I just not sure if I can reuse LetChain like this

MatchArmGuard -> `if` MatchConditions MatchConditions -> Expression _except [StructExpression]_ | LetChain

No, because LetChain excludes StructExpression, but we don't want to exclude that here.
We also don't want MatchConditions to exclude StructExpression.

Ok, it's little bit hard to write a working syntax to cover all cases, let's try something like this as a start

MatchArmGuard -> `if` MatchConditions MatchConditions -> MatchCondition ( `&&` MatchCondition )* MatchCondition -> OuterAttribute* `let` Pattern `=` Expression _except [ExcludedConditions]_ | Expression _except [ExcludedConditions]_ @root ExcludedConditions -> LazyBooleanExpression | RangeExpr | RangeFromExpr | RangeInclusiveExpr | AssignmentExpression | CompoundAssignmentExpression

I think there needs to be a separate case for a chain vs not-chain.

For example:

match () { _ if x || y => {} // OK _ if x || y && let _ = () => {} // ERROR _ => {} }

so I think what it needs is something like:

MatchConditions -> Expression | MatchConditionChain MatchConditionChain -> MatchChainCondition ( `&&` MatchChainCondition )* MatchChainCondition -> Expression _except [ExcludedMatchConditions]_ | OuterAttribute* `let` Pattern `=` MatchGuardScrutinee MatchGuardScrutinee -> Expression _except [ExcludedMatchConditions]_ @root ExcludedMatchConditions -> LazyBooleanExpression | RangeExpr | RangeFromExpr | RangeInclusiveExpr | AssignmentExpression | CompoundAssignmentExpression

right?

well, yeah, separate MatchGuardScrutinee is a good idea

ehuss · 2025-06-09T18:57:49Z

src/expressions/match-expr.md

+```rust,ignore
+match expression {
+    pattern if let subpattern = guard_expr => arm_body,
+    ...
+}
+```


You can just add a full example that will fail CI for now.

ehuss · 2025-06-09T19:06:35Z

src/expressions/match-expr.md

+
+r[expr.match.if.let.guard.scope]
+* The `if let` guard may refer to variables bound by the outer match pattern.
+* New variables bound inside the `if let` guard (e.g., `y` in the example above) are available within the body of the match arm where the guard evaluates to `true`, but are not accessible in other arms or outside the match expression.


Drop behavior should be documented in the destructors chapter. I would expect it to be somewhat similar to the changes that were made for if (such as in destructors.scope.temporary.enclosing).

The stabilization report doesn't explain what the drop order is or how temporaries are handled, so it is difficult for me to evaluate what this should say.

Kivooeo · 2025-06-09T22:44:24Z

@ehuss could you please check last commit if this any better than before

…ved ingore from some blocks

ehuss · 2025-06-10T23:09:19Z

src/destructors.md

@@ -126,6 +126,15 @@ r[destructors.scope.nesting.match-arm]
 * The parent of the expression after the `=>` in a `match` expression is the
  scope of the arm that it's in.

+r[destructors.scope.nesting.match-guard-pattern]
+* The parent of an `if let` guard pattern is the scope of the guard expression.


I'm struggling with this one. Isn't the parent of both the scrutinee and the bindings of an if let guard the entire arm? I'm not able to find a way that it is different from destructors.scope.nesting.match-guard.

For example, in:

match x { Some(a) if let [one] = some_expression => {} _ => {} }

I would expect the parent of both one and some_expression to be the match arm (and drop after the arm body).

Can you clarify this for me?

Hm, yes, we can delete this because it duplucate of destructors.scope.nesting.match-guard, or at least alligns in a way it shouldnt

ehuss · 2025-06-10T23:12:13Z

src/destructors.md

+r[destructors.scope.nesting.match-guard-bindings]
+* Variables bound by `if let` guard patterns have their drop scope determined by
+  guard success:
+  - On guard failure: dropped immediately after guard evaluation
+  - On guard success: scope extends to the end of the match arm body


I'm not sure I understand the need for this rule. Since the bindings are scoped to the match arm, I would expect destructors.scope.nesting.match-guard to cover this. That is, as we leave the arm (success or failure), the bindings will get dropped. Can you clarify how this would be different from the other rule?

This one also can be removed by the same reason as above

But I'm unsure where should I write about drop on failure case, because they are different on success and failure, I think we can keep it, but I'm not sure where exactly

ehuss · 2025-06-10T23:14:13Z

src/destructors.md

@@ -204,8 +213,8 @@ smallest scope that contains the expression and is one of the following:
 * A statement.
 * The body of an [`if`], [`while`] or [`loop`] expression.
 * The `else` block of an `if` expression.
-* The non-pattern matching condition expression of an `if` or `while` expression,
-  or a `match` guard.
+* The condition expression of an `if` or `while` expression.


Why is this changing if and while to drop the "non-pattern matching" qualifier?

i forgot to return it actually, but after this change i realise that we should keep them separatly actually, something like this would be better?

* The non-pattern matching condition expression of an `if` or `while` expression. * A `match` guard expression. * The scrutinee expression of an `if let` guard pattern.

ehuss · 2025-06-10T23:24:52Z

src/destructors.md

-* The non-pattern matching condition expression of an `if` or `while` expression,
-  or a `match` guard.
+* The condition expression of an `if` or `while` expression.
+* A `match` guard expression, including `if let` guard patterns.


I'm a little confused by this. Don't match guards have different temporary behavior of non-pattern matching conditions versus let conditions? Looking at drop-order.rs I see that if_guard and if_let_guard have different drop orders.

ehuss · 2025-06-10T23:28:10Z

src/destructors.md

+r[destructors.scope.match-guards]
+### Match Guards and Pattern Binding


Overall I'm uncertain what this section is saying that is different from the temporary scope rules in destructors.scope.temporary.enclosing. I'm also unclear about why this is differentiating if the pattern matches or not. Either case is handled when execution leaves the arm (success or failure), right?

i guess im over-engineering documentation, i will try to look on it from different angle

This applies some editorial rework, mainly to match the style of `if` conditions.

rustbot added the S-waiting-on-review Status: The marked PR is awaiting review from a maintainer label May 10, 2025

Kivooeo force-pushed the master branch 6 times, most recently from 65337a7 to e704b43 Compare May 10, 2025 19:44

Kivooeo mentioned this pull request May 10, 2025

if let pre-stabilization preview rust-lang/rust#140908

Closed

est31 mentioned this pull request May 12, 2025

Tracking issue for RFC 2294, "if let guard" rust-lang/rust#51114

Open

8 tasks

WaffleLapkin suggested changes May 16, 2025

View reviewed changes

Kivooeo force-pushed the master branch 4 times, most recently from d925c41 to 303dab2 Compare May 16, 2025 15:55

Kivooeo mentioned this pull request May 20, 2025

Stabilize if let guards (feature(if_let_guard)) rust-lang/rust#141295

Open

5 tasks

ehuss reviewed May 21, 2025

View reviewed changes

src/expressions/match-expr.md Outdated Show resolved Hide resolved

ehuss added the S-waiting-on-stabilization Waiting for a stabilization PR to be merged in the main Rust repository label Jun 3, 2025

rustbot removed the S-waiting-on-stabilization Waiting for a stabilization PR to be merged in the main Rust repository label Jun 7, 2025

Kivooeo force-pushed the master branch 2 times, most recently from 486818c to 7799977 Compare June 7, 2025 22:14

Kivooeo requested a review from ehuss June 8, 2025 13:16

jackh726 reviewed Jun 9, 2025

View reviewed changes

added documentation for if let

19de488

Kivooeo force-pushed the master branch from 7799977 to 19de488 Compare June 9, 2025 18:47

ehuss reviewed Jun 9, 2025

View reviewed changes

Kivooeo force-pushed the master branch from 8002a0f to fa42259 Compare June 10, 2025 16:40

Kivooeo force-pushed the master branch 5 times, most recently from 5ebc113 to 060501c Compare June 10, 2025 17:26

cutted down match-expr, added info in destructors, fixed syntax, remo…

b7317ce

…ved ingore from some blocks

Kivooeo force-pushed the master branch from 060501c to b7317ce Compare June 10, 2025 18:47

ehuss reviewed Jun 10, 2025

View reviewed changes

Rework match guard chain

60740c8

This applies some editorial rework, mainly to match the style of `if` conditions.

		r[destructors.scope.match-guards]
		### Match Guards and Pattern Binding

if let guards documentation #1823

Are you sure you want to change the base?

if let guards documentation #1823

Uh oh!

Conversation

Kivooeo commented May 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Kivooeo May 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Kivooeo commented May 16, 2025

Uh oh!

Uh oh!

workingjubilee commented Jun 7, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ehuss left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Kivooeo Jun 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Kivooeo commented Jun 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Kivooeo Jun 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Kivooeo Jun 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

`if let` guards documentation #1823

`if let` guards documentation #1823

Kivooeo commented May 10, 2025 •

edited

Loading

Kivooeo May 16, 2025 •

edited

Loading

Kivooeo Jun 9, 2025 •

edited

Loading

Kivooeo commented Jun 9, 2025 •

edited

Loading

Kivooeo Jun 11, 2025 •

edited

Loading

Kivooeo Jun 11, 2025 •

edited

Loading

Kivooeo Jun 11, 2025 •

edited

Loading