Stabilize let chains in the 2024 edition

[est31]

Stabilization report

This proposes the stabilization of let_chains (tracking issue, RFC 2497) in the 2024 edition of Rust.

What is being stabilized

The ability to &&-chain let statements inside if and while is being stabilized, allowing intermixture with boolean expressions. The patterns inside the let sub-expressions can be irrefutable or refutable.

struct FnCall<'a> {
    fn_name: &'a str,
    args: Vec<i32>,
}

fn is_legal_ident(s: &str) -> bool {
    s.chars()
        .all(|c| ('a'..='z').contains(&c) || ('A'..='Z').contains(&c))
}

impl<'a> FnCall<'a> {
    fn parse(s: &'a str) -> Option<Self> {
        if let Some((fn_name, after_name)) = s.split_once("(")
            && !fn_name.is_empty()
            && is_legal_ident(fn_name)
            && let Some((args_str, "")) = after_name.rsplit_once(")")
        {
            let args = args_str
                .split(',')
                .map(|arg| arg.parse())
                .collect::<Result<Vec<_>, _>>();
            args.ok().map(|args| FnCall { fn_name, args })
        } else {
            None
        }
    }
    fn exec(&self) -> Option<i32> {
        let iter = self.args.iter().copied();
        match self.fn_name {
            "sum" => Some(iter.sum()),
            "max" => iter.max(),
            "min" => iter.min(),
            _ => None,
        }
    }
}

fn main() {
    println!("{:?}", FnCall::parse("sum(1,2,3)").unwrap().exec());
    println!("{:?}", FnCall::parse("max(4,5)").unwrap().exec());
}

The feature will only be stabilized for the 2024 edition and future editions. Users of past editions will get an error with a hint to update the edition.

closes #53667

Why 2024 edition?

Rust generally tries to ship new features to all editions. So even the oldest editions receive the newest features. However, sometimes a feature requires a breaking change so much that offering the feature without the breaking change makes no sense. This occurs rarely, but has happened in the 2018 edition already with async and await syntax. It required an edition boundary in order for async/await to become keywords, and the entire feature foots on those keywords.

In the instance of let chains, the issue is the drop order of if let chains. If we want if let chains to be compatible with if let, drop order makes it hard for us to generate correct MIR. It would be strange to have different behaviour for if let ... {} and if true && let ... {}. So it's better to stay consistent with if let.

In edition 2024, drop order changes have been introduced to make if let temporaries be lived more shortly. These changes also affected if let chains. These changes make sense even if you don't take the if let chains MIR generation problem into account. But if we want to use them as the solution to the MIR generation problem, we need to restrict let chains to edition 2024 and beyond: for let chains, it's not just a change towards more sensible behaviour, but one required for correct function.

Introduction considerations

As edition 2024 is very new, this stabilization PR only makes it possible to use let chains on 2024 without that feature gate, it doesn't mark that feature gate as stable/removed. I would propose to continue offering the let_chains feature (behind a feature gate) for a limited time (maybe 3 months after stabilization?) on older editions to allow nightly users to adopt edition 2024 at their own pace. After that, the feature gate shall be marked as stabilized, not removed, and replaced by an error on editions 2021 and below.

Implementation history

• History from before March 14, 2022 can be found in the original stabilization PR that was reverted.
• Stabilize let_chains in Rust 1.64 #94927
• Extend the irrefutable_let_patterns lint to let chains #94951
• Ensure that let_else does not interact with let_chains #94974
• [let_chains] Forbid let inside parentheses #95008
• [rustc_parse] Forbid lets in certain places #97295
• Fix last let_chains blocker #98633
• Remove let-chain close brace check. #99731
• Fix unwind drop glue for if-then scopes #102394
• Add tests for the drop behavior of some control flow constructs #100526
• Revert let_chains stabilization #100538
• Drop temporaries created in a condition, even if it's a let chain #102998
• Detect incorrect chaining of if and if let conditions and recover #103405
• Remove drop order twist of && and || and make them associative #103293
• Rescope temp lifetime in if-let into IfElse with migration lint #107251
• docs(style): add let-chain style rules #110568
• Improve invalid let expression handling #115677
• Suggest removing ; for ; within let-chains #117743
• Catch stray { in let-chains #117770
• Suggest let or == on typo'd let-chain #118191
• Fix scoping for let chains in match guards #119554
• Don't lint irrefutable_let_patterns on leading patterns if else if let-chains #129394
• Additional tests to ensure let is rejected during parsing #132828
• Add let_chains references reference#1179
• Revert let chains reference docs reference#1251
• Support let-chains rustfmt#5910

Adoption history

In the compiler

• History before March 14, 2022 can be found in the original stabilization PR.
• fix confusing let chain indentation in rustc_resolve #115983
• Simplify some mir passes by using let chains #116549
• Format all the let-chains in compiler crates #116688

Outside of the compiler

• Replace if_chain with let chains rust-clippy#11750
• rspack
• risingwave
• dylint
• convex-backend
• tikv
• Daft
• greptimedb

Tests

Intentional restrictions

partially-macro-expanded.rs, macro-expanded.rs: it is possible to use macros to expand to both the pattern and the expression inside a let chain, but not to the entire let pat = expr operand.
parens.rs: if (let pat = expr) is not allowed in chains
ensure-that-let-else-does-not-interact-with-let-chains.rs: let...else doesn't support chaining.

Overlap with match guards

move-guard-if-let-chain.rs: test for the use moved value error working well in match guards. could maybe be extended with let chains that have more than one let
shadowing.rs: shadowing in if let guards works as expected
ast-validate-guards.rs: let chains in match guards require the match guards feature gate

Simple cases from the early days

PR #88642 has added some tests with very simple usages of let else, mostly as regression tests to early bugs.

then-else-blocks.rs
ast-lowering-does-not-wrap-let-chains.rs
issue-90722.rs
issue-92145.rs

Drop order/MIR scoping tests

issue-100276.rs: let expressions on RHS aren't terminating scopes
drop_order.rs: exhaustive temporary drop order test for various Rust constructs, including let chains
scope.rs: match guard scoping test
drop-scope.rs: another match guard scoping test, ensuring that temporaries in if-let guards live for the arm
drop_order_if_let_rescope.rs: if let rescoping on edition 2024, including chains
mir_let_chains_drop_order.rs: comprehensive drop order test for let chains, distinguishes editions 2021 and 2024.
issue-99938.rs, issue-99852.rs both bad MIR ICEs fixed by #102394

Linting

irrefutable-lets.rs: trailing and leading irrefutable let patterns get linted for, others don't. The lint is turned off for else if.
issue-121070-let-range.rs: regression test for false positive of the unused parens lint, precedence requires the ()s here

Parser: intentional restrictions

disallowed-positions.rs: let in expression context is rejected everywhere except at the top level
invalid-let-in-a-valid-let-context.rs: nested let is not allowed (let's are no legal expressions just because they are allowed in if and while).

Parser: recovery

issue-103381.rs: Graceful recovery of incorrect chaining of if and if let
semi-in-let-chain.rs: Ensure that stray ;s in let chains give nice errors (if_chain! users might be accustomed to ;s)
deli-ident-issue-1.rs, brace-in-let-chain.rs: Ensure that stray unclosed {s in let chains give nice errors and hints

Misc

conflicting_bindings.rs: the conflicting bindings check also works in let chains. Personally, I'd extend it to chains with multiple let's as well.
let-chains-attr.rs: attributes work on let chains

Tangential tests with #![feature(let_chains)]

if-let.rs: MC/DC coverage tests for let chains
logical_or_in_conditional.rs: not really about let chains, more about dropping/scoping behaviour of ||
stringify.rs: exhaustive test of the stringify macro
expanded-interpolation.rs, expanded-exhaustive.rs: Exhaustive test of -Zunpretty
diverges-not.rs: Never type, mostly tangential to let chains

Possible future work

• There is proposals to allow if let Pat(bindings) = expr {} to be written as if expr is Pat(bindings) {} (RFC 3573). if let chains are a natural extension of the already existing if let syntax, and I'd argue orthogonal towards is syntax.
  • Consensus check: let-chains and is are not mutually exclusive lang-team#297
• One could have similar chaining inside let ... else statements. There is no proposed RFC for this however, nor is it implemented on nightly.
• Match guards have the if keyword as well, but on stable Rust, they don't support let. The functionality is available via an unstable feature (if_let_guard tracking issue). Stabilization of let chains affects this feature in so far as match guards containing let chains now only need the if_let_guard feature gate be present instead of also the let_chains feature (NOTE: this PR doesn't implement this simplification, it's left for future work).

Open questions / blockers

• bad recovery if you don't put a let (I don't think this is a blocker): #117977
• An instance where a temporary lives shorter than with nested ifs, breaking compilation: #103476. Personally I don't think this is a blocker either, as it's an edge case. Edit: turns out to not reproduce in edition 2025 any more, due to let rescoping. regression test added in Let chains tests #133093
• One should probably extend the tests for move-guard-if-let-chain.rs and conflicting_bindings.rs to have chains with multiple let's: done in 133093
• Parsing rejection tests: addressed by Additional tests to ensure let is rejected during parsing #132828
• Style: style guide: add let-chain rules #139456
• Non-terminals, e.g. expr, have diverged between parser and macro matcher #86730 explicitly mentions let_else. I think we can live with let pat = expr not evaluating as expr for macro_rules macros, especially given that let pat = expr is not a legal expression anywhere except inside if and while.
• Documentation in the reference: Document let_chains again reference#1740
• Add chapter to the Rust 2024 edition guide: Document if/while let chains edition-guide#337
• Resolve open questions on desired drop order.

[traviscross]

Process-wise, we normally do the FCP on the stabilization PR, and I think that'd make the most sense here. Let us know if you need us on lang to weigh in on anything specifically, e.g. any of the open questions, to make such a stabilization PR possible.

cc @rust-lang/lang for visibility.

And cc @rust-lang/style given the open item on the style guide.

@rustbot labels +I-style-nominated

Putting on the edition hat, since this would be an edition item in some sense, we should talk about this in our next edition call.

@rustbot labels +I-edition-nominated

[rustbot]

r? @fee1-dead

rustbot has assigned @fee1-dead.
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

[est31]

Process-wise, we normally do the FCP on the stabilization PR, and I think that'd make the most sense here.

@traviscross understood, I've converted it to a pull request using the gh cli. Thanks for cc'ing the relevant teams.

[traviscross]

Beautiful, thanks. Let's nominate this for lang discussion too then.

@rustbot labels +I-lang-nominated

[traviscross]

@rustbot labels -I-edition-nominated

We talked this one through in the edition call. Since there's no breakage or migration here, we're happy for this one to land in Rust 2024 either ahead of or after the release of Rust 2024 itself as long as there is an edition guide chapter for it.

[fee1-dead]

Am I also understanding this correctly that this PR will also stablize the following on all editions?

fn main() {
    let x: Option<Option<i32>> = None;
    while let Some(x) = x && let Some(_) = x {}
}

Has there been any discussion to stabilize that? My understanding is that only 2024 was discussed and FCP'd, but maybe I missed something. If only 2024 was discussed then we probably can't stabilize any form of let chains with edition < 2024.

[fee1-dead]

Suggested change

	/// Whether let chains are allowed on all editions, or it's edition dependent.
	/// In case of edition dependence, specify the currently present edition.
	pub enum LetChainsPolicy {
	AlwaysAllowed,
	Edition(Edition),
	}
	/// Whether let chains are allowed on all editions, or it's edition dependent.
	/// In case of edition dependence, specify the currently present edition.
	pub enum LetChainsContext {
	AlwaysAllowed,
	EditionDependent { current_edition: Edition },
	}

When you write it as LetChainsPolicy it feels like the edition that you are passing in is some sort of condition that must be passed, as compared to the current edition. I believe this change would help clarify things better.

[est31]

changed

[est31]

Has there been any discussion to stabilize that? My understanding is that only 2024 was discussed and FCP'd, but maybe I missed something.

No you are right, only 2024 has been discussed. The reason why if let chains are stabilized on 2024 doesn't apply to while though, so such a case can be made. But it still needs to be discussed. I don't think this stabilization PR should be held up more than necessary, so I've removed that part. It can happen in a later PR.

[fee1-dead]

Would be nice to leave a note here that this is allowed since it is already gated behind if_let_guard, so it is still unstable and not being stabilized. But that can be done as a followup.

[fee1-dead]

@bors r+

[bors]

📌 Commit 5258cb7 has been approved by fee1-dead

It is now in the queue for this repository.

[bors]

⌛ Testing commit 5258cb7 with merge 8bf5a8d...

[bors]

☀️ Test successful - checks-actions
Approved by: fee1-dead
Pushing 8bf5a8d to master...

[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 9bfa31f (parent) -> 8bf5a8d (this PR)

Test differences

Show 16 test diffs

Stage 1

• [ui] tests/ui/drop/issue-100276.rs: pass -> [missing] (J0)
• [ui] tests/ui/drop/issue-100276.rs#edition2021: [missing] -> pass (J0)
• [ui] tests/ui/drop/issue-100276.rs#edition2024: [missing] -> pass (J0)
• [ui] tests/ui/rfcs/rfc-2497-if-let-chains/edition-gate-macro-error.rs#edition2021: [missing] -> pass (J0)
• [ui] tests/ui/rfcs/rfc-2497-if-let-chains/edition-gate-macro-error.rs#edition2024: [missing] -> pass (J0)
• [ui] tests/ui/rfcs/rfc-2497-if-let-chains/edition-gate-macro.rs#edition2021: [missing] -> pass (J0)
• [ui] tests/ui/rfcs/rfc-2497-if-let-chains/edition-gate-macro.rs#edition2024: [missing] -> pass (J0)

Stage 2

• [ui] tests/ui/drop/issue-100276.rs: pass -> [missing] (J1)
• [ui] tests/ui/drop/issue-100276.rs#edition2021: [missing] -> pass (J1)
• [ui] tests/ui/drop/issue-100276.rs#edition2024: [missing] -> pass (J1)
• [ui] tests/ui/rfcs/rfc-2497-if-let-chains/edition-gate-macro-error.rs#edition2021: [missing] -> pass (J1)
• [ui] tests/ui/rfcs/rfc-2497-if-let-chains/edition-gate-macro-error.rs#edition2024: [missing] -> pass (J1)
• [ui] tests/ui/rfcs/rfc-2497-if-let-chains/edition-gate-macro.rs#edition2021: [missing] -> pass (J1)
• [ui] tests/ui/rfcs/rfc-2497-if-let-chains/edition-gate-macro.rs#edition2024: [missing] -> pass (J1)

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

Job group index

• J0: x86_64-gnu-llvm-19-3, x86_64-gnu-llvm-20-3
• J1: aarch64-apple, aarch64-gnu, arm-android, armhf-gnu, dist-i586-gnu-i586-i686-musl, i686-gnu-1, i686-gnu-nopt-1, i686-msvc-1, test-various, x86_64-apple-2, x86_64-gnu, x86_64-gnu-llvm-19-1, x86_64-gnu-llvm-19-2, x86_64-gnu-llvm-20-1, x86_64-gnu-llvm-20-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 8bf5a8d12feea10dfada53fb2d119283b0e0107c --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. x86_64-apple-2: 4820.0s -> 5488.8s (13.9%)
2. aarch64-apple: 3816.6s -> 4320.5s (13.2%)
3. dist-apple-various: 8806.0s -> 7932.1s (-9.9%)
4. dist-aarch64-apple: 4610.6s -> 5043.8s (9.4%)
5. aarch64-gnu-debug: 3958.6s -> 4239.4s (7.1%)
6. dist-x86_64-apple: 8865.3s -> 9279.8s (4.7%)
7. i686-gnu-1: 8354.2s -> 8724.8s (4.4%)
8. i686-gnu-nopt-1: 8268.3s -> 8596.6s (4.0%)
9. i686-msvc-2: 7236.4s -> 6959.1s (-3.8%)
10. dist-loongarch64-musl: 5311.2s -> 5480.4s (3.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 (8bf5a8d): comparison URL.

Overall result: ✅ improvements - no action needed

@rustbot label: -perf-regression

Instruction count

This is the most reliable metric that we have; it was used to determine the overall result at the top of this comment. However, even this metric can sometimes exhibit noise.

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

Max RSS (memory usage)

Results (primary -1.1%, secondary 2.7%)

This is a less reliable metric that may be of interest but was not used to determine the overall result at the top of this comment.

	mean	range	count
Regressions ❌ (primary)	2.6%	[2.0%, 3.2%]	2
Regressions ❌ (secondary)	2.7%	[2.7%, 2.7%]	1
Improvements ✅ (primary)	-3.5%	[-6.5%, -1.4%]	3
Improvements ✅ (secondary)	-	-	0
All ❌✅ (primary)	-1.1%	[-6.5%, 3.2%]	5

Cycles

Results (primary -0.7%)

This is a less reliable metric that may be of interest but was not used to determine the overall result at the top of this comment.

	mean	range	count
Regressions ❌ (primary)	-	-	0
Regressions ❌ (secondary)	-	-	0
Improvements ✅ (primary)	-0.7%	[-0.7%, -0.7%]	1
Improvements ✅ (secondary)	-	-	0
All ❌✅ (primary)	-0.7%	[-0.7%, -0.7%]	1

Binary size

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

Bootstrap: 775.125s -> 776.303s (0.15%)
Artifact size: 365.14 MiB -> 365.05 MiB (-0.02%)