document if let guards by tshepang · Pull Request #693 · rust-lang/fls

tshepang · 2026-04-14T18:33:48Z

No description provided.

jyn514

c.f. https://doc.rust-lang.org/reference/expressions/match-expr.html#match-guards

kirtchev-adacore · 2026-04-21T11:20:40Z

 The :t:`value` of a :t:`match expression` is the :t:`value` of the :t:`operand`
 of the selected :t:`match arm`.

+:dp:`fls_DT4N2rr6wpvZ`


This paragraph should follow "6.18:8 A match arm guard ...".

View changes since the review

kirtchev-adacore · 2026-04-21T11:22:17Z


   MatchArmGuard ::=
-       $$if$$ Operand
+       $$if$$ (Operand | MatchGuardChain)


I wonder whether these new non-terminal should have "MatchArm" in their names, as opposed to just "Match".

View changes since the review

kirtchev-adacore · 2026-04-21T11:26:12Z

 of the selected :t:`match arm`.

+:dp:`fls_DT4N2rr6wpvZ`
+A :dt:`match guard chain` is a set of conditions that should each evaluate to ``true`` in the case of :t:`[match guard expression]s` or have a positive match in the case of a :t:`[match guard let pattern]s` for the :t:`match arm` to be selected.


From the way this rule is worded, it appears that a single positive match is sufficient to evaluate the guard to true. How about

Suggested change

A :dt:`match guard chain` is a set of conditions that should each evaluate to ``true`` in the case of :t:`[match guard expression]s` or have a positive match in the case of a :t:`[match guard let pattern]s` for the :t:`match arm` to be selected.

A :dt:`match guard chain` is a set of conditions that must each evaluate to ``true`` in the case of :t:`[match guard expression]s`, or must each produce a positive match in the case of a :t:`[match guard let pattern]s` for the :t:`match arm` to be selected.

View changes since the review

kirtchev-adacore · 2026-04-21T11:38:39Z

+A :dt:`match guard chain` is a set of conditions that should each evaluate to ``true`` in the case of :t:`[match guard expression]s` or have a positive match in the case of a :t:`[match guard let pattern]s` for the :t:`match arm` to be selected.
+
+:dp:`fls_AAuyKfxLgJ43`
+A :dt:`match guard let pattern` is a construct that evaluates if a :t:`match guard expression` matches the specified :t:`pattern`.


Suggested change

A :dt:`match guard let pattern` is a construct that evaluates if a :t:`match guard expression` matches the specified :t:`pattern`.

A :dt:`match guard let pattern` is evaluated when its :t:`match guard expression` matches the specified :t:`pattern`.

View changes since the review

kirtchev-adacore · 2026-04-21T11:40:15Z

+A :dt:`match guard let pattern` is a construct that evaluates if a :t:`match guard expression` matches the specified :t:`pattern`.
+
+:dp:`fls_uCDQMkWx5OMS`
+Each :t:`let binding` in a :t:`match guard let pattern` is in scope for the rest of the :t:`match arm guard` as well as the :t:`match arm body`.


Suggested change

Each :t:`let binding` in a :t:`match guard let pattern` is in scope for the rest of the :t:`match arm guard` as well as the :t:`match arm body`.

Each :t:`let binding` introduced in a :t:`match guard let pattern` is :t:`in scope` for the rest of the :t:`match arm guard` as well as the :t:`match arm body`.

View changes since the review

kirtchev-adacore · 2026-04-21T11:41:49Z

   Otherwise the :t:`match arm matcher` fails.

-:dp:`fls_sbtx1l6n2tp2`
-The :t:`evaluation` of a :t:`match arm guard` evaluates its :t:`operand`. A


Hmm, this paragraph is actually useful. In fact, there Dynamic Semantics section should be updated to account for match guard let patterns.

View changes since the review

thought it was redundant since fls_wkh5wztauwhu says the same thing

I agree the Dynamic Semantics section needs an explicit update here, not just a revised success criterion.

As written, fls_DT4N2rr6wpvZ still reads more like an unordered condition for when a guard succeeds. The Reference specifies this operationally: once the arm pattern matches, guard conditions are evaluated left-to-right; evaluation stops at the first false or failed let match; later conditions are not evaluated; and if the guard fails, matching resumes, including later | alternatives in the same arm.

Could we make those parts explicit in Dynamic Semantics, perhaps by replacing the removed fls_sbtx1l6n2tp2 with a chain-aware evaluation rule?

Support:

Reference expr.match.guard.behavior

Reference expr.match.guard.next

Reference expr.match.guard.chains.order

rustc test tests/ui/rfcs/rfc-2294-if-let-guard/move-guard-if-let-chain.rs

rustc test tests/ui/rfcs/rfc-2294-if-let-guard/drop-order.rs

Co-authored-by: Hristian Kirtchev <60669983+kirtchev-adacore@users.noreply.github.com>

PLeVasseur · 2026-04-22T17:12:47Z

+   MatchArmGuardChain ::=
+       MatchArmGuardCondition ($$&&$$ MatchArmGuardCondition)*
+
+   MatchArmGuardCondition ::=


The new grammar now admits two different kinds of guard condition, but the old single-bool rules are still in place.

For if let PAT = EXPR, EXPR is a scrutinee matched against PAT; EXPR itself is not required to have type bool. Only expression-valued guard conditions are bool-typed. As written, that seems to conflict with both the existing legality rule in src/expressions.rst (fls_bzhz5wjd90ii) and the stale inference rule in src/types-and-traits.rst (fls_st9onPgDrc8y), which still infer all match-arm-guard operands with expected type bool.

Could this be split the same way the Reference and the existing FLS already distinguish ordinary boolean conditions from if let / while let scrutinees? One possible shape would be a distinct guard-scrutinee rule with the pattern's type as its expected type.

Support:

Reference grammar MatchGuardCondition

Reference grammar MatchGuardScrutinee

Reference expr.match.guard.condition

FLS src/expressions.rst fls_bzhz5wjd90ii

FLS src/types-and-traits.rst fls_st9onPgDrc8y

rustc test tests/ui/rfcs/rfc-2294-if-let-guard/type-inference.rs

rustc test tests/ui/rfcs/rfc-2294-if-let-guard/typeck.rs

View changes since the review

PLeVasseur · 2026-04-22T17:12:47Z

+:dp:`fls_AAuyKfxLgJ43`
+A :dt:`match arm guard let pattern` is evaluated when its :t:`match arm guard expression` matches the specified :t:`pattern`.
+
+:dp:`fls_uCDQMkWx5OMS`


I think this stabilization is still incomplete outside src/expressions.rst.

The new local rule says bindings introduced by a guard let are in scope for the rest of the guard and the arm body, but the shared scope / destructor chapters still describe the older model: src/entities-and-resolution.rst fls_xbnki64un70v only covers arm-pattern bindings, and src/ownership-and-deconstruction.rst fls_lbsfhg42yiqy, fls_fnvr5w2wzxns, and fls_ptk6yibqyfzi still talk about a single guard operand rather than pattern-matching guard conditions with arm-scope bindings and temporaries.

Upstream needed matching updates in names/scopes and destructors for the same feature (rust-lang/reference#1957). Could this PR update those shared chapters too? Otherwise the new local rule here will not match the shared scope / drop-scope text.

Support:

Reference PR rust-lang/reference#1957

Reference names.scopes.pattern-bindings.match-guard-let

Reference expr.match.guard.chains.bindings

Reference destructors.scope.bindings.match-arm

rustc test tests/ui/rfcs/rfc-2294-if-let-guard/scope.rs

rustc test tests/ui/rfcs/rfc-2294-if-let-guard/scoping-consistency.rs

rustc test tests/ui/drop/if-let-guards.rs

View changes since the review

PLeVasseur · 2026-04-22T17:12:47Z

 The :t:`value` of a :t:`match expression` is the :t:`value` of the :t:`operand`
 of the selected :t:`match arm`.

+:dp:`fls_AAuyKfxLgJ43`


I think FLS still needs an explicit guard-specific rule for when arm-pattern bindings become values.

Today the shared pattern rules say by-value bindings move or copy during pattern matching (src/patterns.rst fls_pxvtqxke1enp), but the stabilized guard behavior is different for arm-pattern bindings: during guard evaluation they are observed through shared references, and only after the guard succeeds are values moved or copied from the scrutinee into the arm bindings. Without that exception, the spec still reads as though a by-value arm binding may move before guard evaluation.

Could we add the guard-specific rule from the Reference here (or in the shared pattern / guard text), and tie it back to the existing immutability rule for match-arm-guard bindings? That would also explain why mutation through those bindings is rejected while the guard runs.

Support:

Reference expr.match.guard.shared-ref

Reference expr.match.guard.value

Reference expr.match.guard.no-mutation

rustc test tests/ui/rfcs/rfc-2294-if-let-guard/guard-mutability-2.rs

rustc test tests/ui/rfcs/rfc-2294-if-let-guard/move-guard-if-let.rs

rustc test tests/ui/rfcs/rfc-2294-if-let-guard/move-guard-if-let-chain.rs

View changes since the review

PLeVasseur · 2026-04-22T17:35:40Z

   Otherwise the :t:`match arm matcher` fails.

-:dp:`fls_sbtx1l6n2tp2`
-The :t:`evaluation` of a :t:`match arm guard` evaluates its :t:`operand`. A


I agree the Dynamic Semantics section needs an explicit update here, not just a revised success criterion.

As written, fls_DT4N2rr6wpvZ still reads more like an unordered condition for when a guard succeeds. The Reference specifies this operationally: once the arm pattern matches, guard conditions are evaluated left-to-right; evaluation stops at the first false or failed let match; later conditions are not evaluated; and if the guard fails, matching resumes, including later | alternatives in the same arm.

Could we make those parts explicit in Dynamic Semantics, perhaps by replacing the removed fls_sbtx1l6n2tp2 with a chain-aware evaluation rule?

Support:

Reference expr.match.guard.behavior

Reference expr.match.guard.next

Reference expr.match.guard.chains.order

rustc test tests/ui/rfcs/rfc-2294-if-let-guard/move-guard-if-let-chain.rs

rustc test tests/ui/rfcs/rfc-2294-if-let-guard/drop-order.rs

tshepang added 2 commits April 14, 2026 20:26

document if-let guards

a9d2416

remove redundant paragraph

79c2910

jyn514 reviewed Apr 15, 2026

View reviewed changes

Comment thread src/expressions.rst Outdated

jyn514 approved these changes Apr 16, 2026

View reviewed changes

kirtchev-adacore self-requested a review April 21, 2026 11:10

kirtchev-adacore requested changes Apr 21, 2026

View reviewed changes

tshepang and others added 2 commits April 21, 2026 16:35

use a list to ease reading

695990c

Co-authored-by: Hristian Kirtchev <60669983+kirtchev-adacore@users.noreply.github.com>

reoder

9045712

tshepang force-pushed the tshepang/document-if-let-guards branch from 7931d63 to 38075b5 Compare April 21, 2026 15:15

tshepang added 3 commits April 21, 2026 17:20

use a consistent and more complete prefix

d44f6c2

clarity

f2bef9f

be more crisp, and add a link

eba5309

tshepang force-pushed the tshepang/document-if-let-guards branch from 38075b5 to eba5309 Compare April 21, 2026 15:20

PLeVasseur requested changes Apr 22, 2026

View reviewed changes

	A :dt:`match guard chain` is a set of conditions that should each evaluate to ``true`` in the case of :t:`[match guard expression]s` or have a positive match in the case of a :t:`[match guard let pattern]s` for the :t:`match arm` to be selected.
	A :dt:`match guard chain` is a set of conditions that must each evaluate to ``true`` in the case of :t:`[match guard expression]s`, or must each produce a positive match in the case of a :t:`[match guard let pattern]s` for the :t:`match arm` to be selected.

	A :dt:`match guard let pattern` is a construct that evaluates if a :t:`match guard expression` matches the specified :t:`pattern`.
	A :dt:`match guard let pattern` is evaluated when its :t:`match guard expression` matches the specified :t:`pattern`.

	Each :t:`let binding` in a :t:`match guard let pattern` is in scope for the rest of the :t:`match arm guard` as well as the :t:`match arm body`.
	Each :t:`let binding` introduced in a :t:`match guard let pattern` is :t:`in scope` for the rest of the :t:`match arm guard` as well as the :t:`match arm body`.

Conversation

tshepang commented Apr 14, 2026

Uh oh!

jyn514 left a comment • edited by rustbot 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!

Uh oh!

kirtchev-adacore Apr 21, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kirtchev-adacore Apr 21, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kirtchev-adacore Apr 21, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kirtchev-adacore Apr 21, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kirtchev-adacore Apr 21, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kirtchev-adacore Apr 21, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tshepang Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

PLeVasseur Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

PLeVasseur Apr 22, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PLeVasseur Apr 22, 2026 • 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!

PLeVasseur Apr 22, 2026 • 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!

PLeVasseur Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jyn514 left a comment •

edited by rustbot

Loading

kirtchev-adacore Apr 21, 2026 •

edited by rustbot

Loading

kirtchev-adacore Apr 21, 2026 •

edited by rustbot

Loading

kirtchev-adacore Apr 21, 2026 •

edited by rustbot

Loading

kirtchev-adacore Apr 21, 2026 •

edited by rustbot

Loading

kirtchev-adacore Apr 21, 2026 •

edited by rustbot

Loading

kirtchev-adacore Apr 21, 2026 •

edited by rustbot

Loading

PLeVasseur Apr 22, 2026 •

edited by rustbot

Loading

PLeVasseur Apr 22, 2026 •

edited

Loading

PLeVasseur Apr 22, 2026 •

edited

Loading