Stabilize let else

[est31]

🎉 Stabilizes the let else feature, added by RFC 3137. 🎉

Reference PR: rust-lang/reference#1156

closes #87335 (let else tracking issue)

FCP: #93628 (comment)

---

Stabilization report

Summary

The feature allows refutable patterns in let statements if the expression is
followed by a diverging else:

fn get_count_item(s: &str) -> (u64, &str) {
    let mut it = s.split(' ');
    let (Some(count_str), Some(item)) = (it.next(), it.next()) else {
        panic!("Can't segment count item pair: '{s}'");
    };
    let Ok(count) = u64::from_str(count_str) else {
        panic!("Can't parse integer: '{count_str}'");
    };
    (count, item)
}
assert_eq!(get_count_item("3 chairs"), (3, "chairs"));

Differences from the RFC / Desugaring

Outside of desugaring I'm not aware of any differences between the implementation and the RFC. The chosen desugaring has been changed from the RFC's original. You can read a detailed discussion of the implementation history of it in @cormacrelf 's summary in this thread, as well as the followup. Since that followup, further changes have happened to the desugaring, in #98574, #99518, #99954. The later changes were mostly about the drop order: On match, temporaries drop in the same order as they would for a let declaration. On mismatch, temporaries drop before the else block.

Test cases

In chronological order as they were merged.

Added by df9a2e0 (#87688):

• ui/pattern/usefulness/top-level-alternation.rs to ensure the unreachable pattern lint visits patterns inside let else.

Added by 5b95df4 (#87688):

• ui/let-else/let-else-bool-binop-init.rs to ensure that no lazy boolean expressions (using && or ||) are allowed in the expression, as the RFC mandates.
• ui/let-else/let-else-brace-before-else.rs to ensure that no } directly preceding the else is allowed in the expression, as the RFC mandates.
• ui/let-else/let-else-check.rs to ensure that #[allow(...)] attributes added to the entire let statement apply for the else block.
• ui/let-else/let-else-irrefutable.rs to ensure that the irrefutable_let_patterns lint fires.
• ui/let-else/let-else-missing-semicolon.rs to ensure the presence of semicolons at the end of the let statement.
• ui/let-else/let-else-non-diverging.rs to ensure the else block diverges.
• ui/let-else/let-else-run-pass.rs to ensure the feature works in some simple test case settings.
• ui/let-else/let-else-scope.rs to ensure the bindings created by the outer let expression are not available in the else block of it.

Added by bf7c32a (#89965):

• ui/let-else/issue-89960.rs as a regression test for the ICE-on-error bug Erroneous 'ref mut' in let-else binding causes ICE #89960 . Later in 102b912 this got removed in favour of more comprehensive tests.

Added by 8565419 (#89974):

• ui/let-else/let-else-if.rs to test for the improved error message that points out that let else if is not possible.

Added by 9b45713:

• ui/let-else/let-else-allow-unused.rs as a regression test for let-else: linting for unused bindings is not handled correctly #89807, to ensure that #[allow(...)] attributes added to the entire let statement apply for bindings created by the let else pattern.

Added by 61bcd8d (#89841):

• ui/let-else/let-else-non-copy.rs to ensure that a copy is performed out of non-copy wrapper types. This mirrors if let behaviour. The test case bases on rustc internal changes originally meant for Adopt let_else across the compiler #89933 but then removed from the PR due to the error prior to the improvements of Implement let-else type annotations natively #89841.
• ui/let-else/let-else-source-expr-nomove-pass.rs to ensure that while there is a move of the binding in the successful case, the else case can still access the non-matching value. This mirrors if let behaviour.

Added by 102b912 (#89841):

• ui/let-else/let-else-ref-bindings.rs and ui/let-else/let-else-ref-bindings-pass.rs to check ref and ref mut keywords in the pattern work correctly and error when needed.

Added by 2715c5f (#89841):

• Match ergonomic tests adapted from the rfc2005 test suite.

Added by fec8a50 (#89841):

• ui/let-else/let-else-deref-coercion-annotated.rs and ui/let-else/let-else-deref-coercion.rs to check deref coercions.

Added since this stabilization report was originally written (2022-02-09)

Added by 76ea566 (#94211):

• ui/let-else/let-else-destructuring.rs to give a nice error message if an user tries to do an assignment with a (possibly refutable) pattern and an else block, like asked for in destructuring assignment and let else #93995.

Added by e7730dc (#94208):

• ui/let-else/let-else-allow-in-expr.rs to test whether #[allow(unused_variables)] works in the expr, as well as its non presence, as well as putting it on the entire let else affects the expr, too. This was adding a missing test as pointed out by the stabilization report.
• Expansion of ui/let-else/let-else-allow-unused.rs and ui/let-else/let-else-check.rs to ensure that non-presence of #[allow(unused)] does issue the unused lint. This was adding a missing test case as pointed out by the stabilization report.

Added by 5bd7106 (#94208):

• ui/let-else/let-else-slicing-error.rs, a regression test for Wrong suggestion for slice patterns when using let-else statement #92069, which got fixed without addition of a regression test. This resolves a missing test as pointed out by the stabilization report.

Added by 5374688 (#98574):

• src/test/ui/async-await/async-await-let-else.rs to test the interaction of async/await with let else

Added by 6c529de (#98574):

• src/test/ui/let-else/let-else-temporary-lifetime.rs as a (partial) regression test for Let-else does not drop temporaries at the end of the statement #98672

Added by 9b56640 (#99518):

• src/test/ui/let-else/let-else-temp-borrowck.rs as a regression test for let_else returns in surprising borrowck errors with impl trait #93951
• Extension of src/test/ui/let-else/let-else-temporary-lifetime.rs to include a partial regression test for Let-else does not drop temporaries at the end of the statement #98672 (especially regarding else drop order)

Added by baf9a7c (#99518):

• Extension of src/test/ui/let-else/let-else-temporary-lifetime.rs to include a partial regression test for let_else returns in surprising borrowck errors with impl trait #93951, similar to let-else-temp-borrowck.rs

Added by 60be2de (#99518):

• Extension of src/test/ui/let-else/let-else-temporary-lifetime.rs to include a program that can now be compiled thanks to borrow checker implications of Let-else: break out scopes when a let-else pattern fails to match #99518

Added by 47a7a91 (#100132):

• src/test/ui/let-else/issue-100103.rs, as a regression test for ICE trying to use Err(1)? with let_else in a try block #100103, to ensure that there is no ICE when doing Err(...)? inside else blocks.

Added by e3c5bd6 (#100443):

• src/test/ui/let-else/let-else-then-diverge.rs, to verify that there is no unreachable code error with the current desugaring.

Added by 9818526 (#100443):

• src/test/ui/let-else/issue-94176.rs, to make sure that a correct span is emitted for a missing trailing expression error. Regression test for Missing trailing expression in block with let else yields incorrectly spanned error message #94176.

Added by e182d12 (#100434):

• src/test/ui/unpretty/pretty-let-else.rs, as a regression test to ensure pretty printing works for let else (this bug surfaced in many different ways)

Added by e262856 (#99954):

• src/test/ui/let-else/let-else-temporary-lifetime.rs extended to contain & borrows as well, as this was identified as an earlier issue with the desugaring: Let-else does not drop temporaries at the end of the statement #98672 (comment)

Added by 2d8460e (#99291):

• src/test/ui/let-else/let-else-drop-order.rs a matrix based test for various drop order behaviour of let else. Especially, it verifies equality of let and let else drop orders, resolving a stabilization blocker.

Added by 1b87ce0 (#101410):

• Edit to src/test/ui/let-else/let-else-temporary-lifetime.rs to add the -Zvalidate-mir flag, as a regression test for ICE: broken mir with let-else, -Zvalidate-mir #99228

Added by af591eb (#101410):

• src/test/ui/let-else/issue-99975.rs as a regression test for the ICE Internal Compiler Error: Broken MIR in Item(...) With let_else Usage #99975.

Added by this PR:

• ui/let-else/let-else.rs, a simple run-pass check, similar to ui/let-else/let-else-run-pass.rs.

Things not currently tested

• The #[allow(...)] tests check whether allow works, but they don't check whether the non-presence of allow causes a lint to fire. → test added by e7730dc
• There is no #[allow(...)] test for the expression, as there are tests for the pattern and the else block. → test added by e7730dc
• let-else-brace-before-else.rs forbids the let ... = {} else {} pattern and there is a rustfix to obtain let ... = ({}) else {}. I'm not sure whether the .fixed files are checked by the tooling that they compile. But if there is no such check, it would be neat to make sure that let ... = ({}) else {} compiles. → test added by e7730dc
• Wrong suggestion for slice patterns when using let-else statement #92069 got closed as fixed, but no regression test was added. Not sure it's worth to add one. → test added by 5bd7106
• consistency between let else and if let regarding lifetimes and drop order: Stabilize let else #93628 (comment) → test added by 2d8460e

Edit: they are all tested now.

Possible future work / Refutable destructuring assignments

RFC 2909 specifies destructuring assignment, allowing statements like FooBar { a, b, c } = foo();.
As it was stabilized, destructuring assignment only allows irrefutable patterns, which before the advent of let else were the only patterns that let supported.
So the combination of let else and destructuring assignments gives reason to think about extensions of the destructuring assignments feature that allow refutable patterns, discussed in #93995.

A naive mapping of let else to destructuring assignments in the form of Some(v) = foo() else { ... }; might not be the ideal way. let else needs a diverging else clause as it introduces new bindings, while assignments have a default behaviour to fall back to if the pattern does not match, in the form of not performing the assignment. Thus, there is no good case to require divergence, or even an else clause at all, beyond the need for having some introducer syntax so that it is clear to readers that the assignment is not a given (enums and structs look similar). There are better candidates for introducer syntax however than an empty else {} clause, like maybe which could be added as a keyword on an edition boundary:

let mut v = 0;
maybe Some(v) = foo(&v);
maybe Some(v) = foo(&v) else { bar() };

Further design discussion is left to an RFC, or the linked issue.

[rust-highfive]

r? @jackh726

(rust-highfive has picked a reviewer for you, use r? to override)

[joshtriplett]

This looks good to me; I'll start a T-lang FCP.

[joshtriplett]

Shall we stabilize let else syntax? We've had many demonstrated uses, including extensively throughout rust-lang/rust, we've seen the value of it, and there aren't any known issues with it.

@rfcbot merge

[rfcbot]

Team member @joshtriplett has proposed to merge this. The next step is review by the rest of the tagged team members:

• @cramertj
• @joshtriplett
• @nikomatsakis
• @pnkfelix
• @scottmcm

Concerns:

• need-consistency-rvalue-temporary-rules-between-let-and-let-else resolved by Stabilize let else #93628 (comment)
• not-while-rustfmt-breaks-on-it resolved by Stabilize let else #93628 (comment)
• semicolon resolved by Stabilize let else #93628 (comment)
• stabilization-report resolved by Stabilize let else #93628 (comment)
• summarize-concerns resolved by Stabilize let else #93628 (comment)

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[scottmcm]

@rfcbot concern not-while-rustfmt-breaks-on-it

I remembered it not formatting last I tried using it in rustc, and sure enough it still seems to fail when I try it in playground: https://play.rust-lang.org/?version=nightly&mode=debug&edition=2021&gist=350415c3adb74101bbdc002031976b70

(There's enough people using rustfmt in CI that I think adding formatting support for it after stabilization would be impolite.)

EDIT: "breaks" is not the word I should have used here. I meant "while rustfmt is unable to normalize formatting for the construct", since that's what I'd expect rustfmt to do for all stable syntax.

[calebcartwright]

I remembered it not formatting last I tried using it in rustc, and sure enough it still seems to fail when I try it in playground:

It's not that rustfmt is "breaking" on it, but the formatting rules aren't established yet so rustfmt is just leaving whatever you wrote in place. You have trailing whitespace in your snippet, and rustfmt is just acknowledging the presence of what was originally written; it's not modifying what was already there/inserting trailing whitespace itself.

[scottmcm]

it's not modifying what was already there

I think that's my complaint. I think it's clear that we'd want rustfmt to format it, but based on https://rust-lang.github.io/rfcs/2437-rustfmt-stability.html it'd need to be a new version to add formatting support for it if we did so after stabilization. And I don't think that dance is worth it; it should just have formatting support in the release that stabilizes it.

[calebcartwright]

it'd need to be a new version to add formatting support for it if we did so after stabilization. And I don't think that dance is worth it; it should just have formatting support in the release that stabilizes it

That's not the case actually.

rustfmt has always had leeway to make formatting changes for "new" syntax (we have to) until such time as the formatting has actually been stabilized. We try very hard to only do this once, which is why the "first do no harm" pattern followed for syntax that's new to rustfmt.

I've never seen a case where stabilization of a feature was held up on rustfmt, and doing so would be a big mistake IMO. Throughout my time working on rustfmt it's often been an after thought where we weren't even aware of syntax changes until long after they'd been in use, and there's plenty of cases where rustfmt exhibits this same behavior on long-standing syntax (e.g. try adding comments between trait bounds).

I'd think that blocking feature stabilization on style guide + formatting stabilization would either greatly elongate the lead time for feature availability on stable, or create large amounts of friction on the rustfmt side between expediency (not wanting to block) and formatting stability + quality/correctness.

Also, and I say this as someone that spends a large chunk of my free time trying to maintain and improve rustfmt 😄, there's a non-zero subset of the Rust population that dislikes rustfmt and doesn't use it whatsoever. If I were one of those folks I think it would be extremely frustrating to not have access to a language feature on stable simply because of an optional tool I don't leverage.

[joshtriplett]

No objections since it's been being reviewed for far longer than 10 days.

[joshtriplett]

@bors r+

[bors]

📌 Commit 37dde3f has been approved by joshtriplett

It is now in the queue for this repository.

[slanterns]

Maybe we can give it some priority if we want it to be merged before the branching.

[joshtriplett]

@slanterns I don't think we should get in the habit of skipping the queue; if it makes it it makes it, if not it'll make the next one.

[rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

This will be merged soon.

[joshtriplett]

Looks like this failed in a rollup.

[est31]

Yeah, seems the problems from earlier are plaguing us again: #101910 (comment) , which is weird as I've thought that #98147 fixed the problem. Apparently doc-tests of the rustc_macros crate are affected now. I guess those don't get the right flags passed, but need to investigate how exactly we are hitting the bug.

[est31]

I can reproduce it locally with ./x.py test compiler/rustc_macros/. It seems that the rustdoc wrapper needs adjustments too, similar to how #98147 adjusted the rustc wrapper. Also, ./x.py test --stage 0 compiler/rustc_macros/ is broken as well. It complains about a missing feature(let_else), which occurs when no --cfg=bootstrap is passed. This is probably because cargo doesn't pass RUSTDOCFLAGS to proc-macro crate rustdoc invocations similar to how it doesn't pass RUSTFLAGS to proc-macro rustc invocations for $reasons (the PR i linked links to the cargo issue for that). The rustc wrapper has code to deal with this for rustc, but probably the rustdoc wrapper needs similar logic.

[est31]

I've filed #101921 to fix the issue. I've locally applied that PR to this one, the issue is resolved.

[Fishrock123]

@est31 Big thanks for carrying this over the finish line!!

[est31]

🎉 the stabilization PR has been merged 🎉

Getting let else into the language was very much a team effort, and I would like to thank everyone who was involved in their introduction and stabilization. In particular I would like to thank:

Authors of the RFCs 1303 and 3137:

@Fishrock123 @mbrubeck

PR authors for the implementation in the compiler:

@camsteffen (lowering, tests) @compiler-errors (diagnostics, ICE fixes) @cormacrelf (initial implementation, lowering, tests) @dingxiangfei2009 (lowering, tests) @est31 (stabilization, diagnostics, tests) @JohnTitor (ICE fixes)

Reviewers of those PRs:

@cjgillot @petrochenkov @nagisa @matthewjasper @oli-obk @Mark-Simulacrum @pnkfelix @joshtriplett @jackh726

Everyone who tested out let-else, filed issues/bug reports, provided guidance and feedback in the RFCs, PRs and issues, including team members who approved FCPs.