Skip to content

document if let guards #693

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
tshepang wants to merge 7 commits into
base: main
Choose a base branch
from
Open

document if let guards #693

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
a9d2416
document if-let guards
tshepang Apr 14, 2026
79c2910
remove redundant paragraph
tshepang Apr 14, 2026
695990c
use a list to ease reading
tshepang Apr 21, 2026
9045712
reoder
tshepang Apr 21, 2026
d44f6c2
use a consistent and more complete prefix
tshepang Apr 21, 2026
f2bef9f
clarity
tshepang Apr 21, 2026
eba5309
be more crisp, and add a link
tshepang Apr 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions src/changelog.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,25 @@ Language changes in Rust 1.95.0
-------------------------------

- `Stabilize if let guards on match arms <https://github.com/rust-lang/rust/pull/141295>`_

Changed syntax: :s:`MatchArmGuard`

New syntax:

- :s:`MatchGuardChain`
- :s:`MatchGuardCondition`
- :s:`MatchGuardExpression`
- :s:`MatchGuardLetPattern`

New paragraphs:

- :p:`fls_UlxLrpyPlVmv`
- :p:`fls_DT4N2rr6wpvZ`
- :p:`fls_AAuyKfxLgJ43`
- :p:`fls_uCDQMkWx5OMS`

Removed paragraph: :p:`fls_sbtx1l6n2tp2`

- `irrefutable_let_patterns lint no longer lints on let chains <https://github.com/rust-lang/rust/pull/146832>`_

- Lints are outside the scope of the FLS.
Expand Down
31 changes: 25 additions & 6 deletions src/expressions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4645,7 +4645,22 @@ Match Expressions
OuterAttributeOrDoc* Pattern MatchArmGuard?

MatchArmGuard ::=
$$if$$ Operand
$$if$$ (Operand | MatchGuardChain)
Copy link
Copy Markdown
Contributor

@kirtchev-adacore kirtchev-adacore Apr 21, 2026 •
edited by rustbot
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

View changes since the review


MatchGuardChain ::=
MatchGuardCondition ($$&&$$ MatchGuardCondition)*
Comment thread
kirtchev-adacore marked this conversation as resolved.
Outdated

MatchGuardCondition ::=
(MatchGuardExpression | OuterAttributeOrDoc* MatchGuardLetPattern)

MatchGuardLetPattern ::=
$$let$$ Pattern $$=$$ MatchGuardExpression

MatchGuardExpression ::=
Expression

:dp:`fls_UlxLrpyPlVmv`
A :dt:`match guard expression` is any expression in category :s:`Expression`, except :s:`LazyBooleanExpression`, :s:`RangeFromToExpression`, :s:`RangeFromExpression`, :s:`RangeInclusiveExpression`, :s:`AssignmentExpression`, and :s:`CompoundAssignmentExpression`.
Comment thread
tshepang marked this conversation as resolved.
Outdated

.. rubric:: Legality Rules

Expand Down Expand Up @@ -4715,6 +4730,15 @@ match the :t:`[subject expression]'s` :t:`type`.
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`
Copy link
Copy Markdown
Contributor

@kirtchev-adacore kirtchev-adacore Apr 21, 2026 •
edited by rustbot
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

View changes since the review

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.
Copy link
Copy Markdown
Contributor

@kirtchev-adacore kirtchev-adacore Apr 21, 2026 •
edited by rustbot
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


:dp:`fls_AAuyKfxLgJ43`
Copy link
Copy Markdown
Contributor

@PLeVasseur PLeVasseur Apr 22, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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

@kirtchev-adacore kirtchev-adacore Apr 21, 2026 •
edited by rustbot
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


:dp:`fls_uCDQMkWx5OMS`
Copy link
Copy Markdown
Contributor

@PLeVasseur PLeVasseur Apr 22, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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`.
Copy link
Copy Markdown
Contributor

@kirtchev-adacore kirtchev-adacore Apr 21, 2026 •
edited by rustbot
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


.. rubric:: Dynamic Semantics

:dp:`fls_g551l8r8yh6d`
Expand Down Expand Up @@ -4767,11 +4791,6 @@ The :t:`evaluation` of a :t:`match arm matcher` proceeds as follows:
#. :dp:`fls_yk8l9zjh7i0d`
Otherwise the :t:`match arm matcher` fails.

:dp:`fls_sbtx1l6n2tp2`
The :t:`evaluation` of a :t:`match arm guard` evaluates its :t:`operand`. A
Copy link
Copy Markdown
Contributor

@kirtchev-adacore kirtchev-adacore Apr 21, 2026 •
edited by rustbot
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Member Author

@tshepang tshepang Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thought it was redundant since fls_wkh5wztauwhu says the same thing

Copy link
Copy Markdown
Contributor

@PLeVasseur PLeVasseur Apr 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

:t:`match arm guard` evaluates to ``true`` when its :t:`operand` evaluates to
``true``, otherwise it evaluates to ``false``.

.. rubric:: Examples

.. code-block:: rust
Expand Down
Loading