Tracking Issue for match ergonomics 2024 (RFC 3627)

[Jules-Bertholet]

This is a tracking issue for changes to match ergonomics for the 2024 edition, as described in rust-lang/rfcs#3627.

About tracking issues

Tracking issues are used to record the overall progress of implementation.
They are also used as hubs connecting to other relevant issues, e.g., bugs or open design questions.
A tracking issue is however not meant for large scale discussion, questions, or bug reports about a feature.
Instead, open a dedicated issue for the specific matter and add the relevant feature gate label.

Steps

• mut ref/mut ref mut (#![feature(mut_ref)]) Match ergonomics 2024: implement mutable by-reference bindings #123080
  • Bikeshed (ref (mut/ref mut (mut?)
  • Update all pattern diagnostics to ensure they know about this
• Changes to & and &mut patterns (#![feature(ref_pat_eat_one_layer_2024, ref_pat_eat_one_layer_2024_structural)]) Match ergonomics 2024: Implement eat-one-layer #123512
• Allow & patterns to consume &mut references Match ergonomics 2024: let & patterns eat &mut #124567
• Don't reset binding mode on mut with edition >= 2024 Match ergonomics 2024: mut doesn't reset binding mode #123535
  • Edition migration lint (without rustfix)
• Rustfix Match ergonomics 2024: migration lint #124639
• RFC Match ergonomics 2024 rfcs#3627
  • Original design doc: https://hackmd.io/YLKslGwpQOeAyGBayO9mdw.
• N/A: Add documentation to the dev guide.
  • See the instructions.
• Stabilize Rule 1C, Rule 2C for Rust 2024.
  • Implement edition 2024 match ergonomics restrictions #131381
• Stabilize Rules 3-5 for all editions.
• Add documentation to the reference.
  • See the instructions.
• Add documentation to the edition guide.
• Ensure ready for Rust 2024 stabilization.

Tracking for Rust 2024 changes:

• Tracking issue for Rust 2024: Match ergonomics rules 1C/2C #131414

Unresolved Questions

• mut ref mut vs ref mut (mut syntax
• The HackMD says the reference types should be "compatible", what does this mean and why?

Implementation history

Beta Give feedback

1. Implement match ergonomics 2024 #122978
   A-edition-2024 A-patterns S-waiting-on-review T-compiler T-lang +5
   
2. Match ergonomics 2024: implement mutable by-reference bindings #123080
   A-edition-2024 A-patterns S-waiting-on-bors T-compiler merged-by-bors +5
   
3. Match ergonomics: implement "&pat everywhere" #123311
   A-edition-2024 A-patterns S-waiting-on-bors T-compiler +4
   
4. Match ergonomics 2024: Implement eat-one-layer #123512
   A-edition-2024 A-patterns S-waiting-on-bors T-compiler +4
   
5. Match ergonomics 2024: mut doesn't reset binding mode #123535
   A-edition-2024 A-patterns S-waiting-on-bors T-compiler +4
   
6. Match ergonomics 2024: miscellaneous code cleanups #124047
   A-patterns S-waiting-on-bors T-compiler +3
   
7. Match ergonomics 2024: let & patterns eat &mut #124567
   A-edition-2024 A-patterns S-waiting-on-bors T-compiler merged-by-bors +5
   
8. Match ergonomics 2024: migration lint #124639
   A-edition-2024 A-patterns S-waiting-on-bors T-compiler merged-by-bors +5
   
9. Match ergonomics 2024 rfcs#3627
   A-edition-2024 A-patterns I-lang-nominated T-lang disposition-merge finished-final-comment-period to-announce +7
10. ICE: explicit deref of non-derefable type #125058
    C-bug I-ICE T-compiler +3
    
11. rustc_hir_typeck: Account for skipped_ref_pats in expr_use_visitor #125084
    A-edition-2024 A-patterns S-waiting-on-bors T-compiler merged-by-bors +5
    
12. Match ergonomics 2024: align implementation with RFC #125168
    A-edition-2024 A-patterns S-waiting-on-bors T-compiler +4
    
13. Match ergonomics 2024: Implement TC's match ergonomics proposal #127008
    A-edition-2024 A-patterns A-testsuite S-waiting-on-bors T-bootstrap T-compiler merged-by-bors +7
    
14. Decide on Rule 4 variant for match ergonomics #127257
    C-discussion T-lang +2
15. Match ergonomics 2024: align with RFC again #127369
    A-edition-2024 A-patterns S-waiting-on-bors T-compiler +4
    
16. Fix discrepancy between match ergonomics Rule 4 and implementation #127559
    C-discussion T-lang +2

See also #105647, #64586

@rustbot label T-lang A-patterns A-edition-2024

[Nadrieril]

Noting here that I no longer think we need the "&<pat> everywhere" part of the proposal. This makes the proposed fix less local but saves us in design and possible conflicts with deref patterns.

[Jules-Bertholet]

possible conflicts with deref patterns.

Can you elaborate? edit: oh I see, https://hackmd.io/YLKslGwpQOeAyGBayO9mdw#Deref-patterns

[traviscross]

@rustbot labels +I-lang-nominated

@Jules-Bertholet has picked up this work and is looking for a liaison for the experiment. Let's nominate to discuss.

[traviscross]

@rustbot labels -I-lang-nominated

We discussed this is in the lang meeting today, and I'll be picking up liaisoning on this one. Please let me know whenever anything is needed to move this forward.

Thanks to @Nadrieril for the original work here, and thanks to @Jules-Bertholet for carrying the torch forward.

[Jules-Bertholet]

Proposal for the lang team

Here's my current plan for this feature. Assumes familarity with https://hackmd.io/YLKslGwpQOeAyGBayO9mdw, I'll be going into detail only where my proposal differs.

mut ref/mut ref mut

Adding mut before ref makes the binding mutable, as opposed to mut after ref which makes the reference mutable. This would be available in all editions. I chose this syntax over ref (mut because it's simpler and easier to parse.

Note that, if we choose to go with the eat-one-layer option below, the migration lint would not need to rely on this feature, so it would become independent of the edition. (Though without it, non-dereferencing mut as described below won't have a no-match-ergonomics equivalent.)

Non-dereferencing mut <binding>

In edition 2024, mut no longer resets the binding mode.

Eat-one-layer

I'm proposing to go with a variant of the "eat-one-layer" option: in edition 2024, a reference pattern matches against exactly one reference: either the inherited match ergonomics reference, or if this is not possible the reference in the scrutinee. Subtleties:

• For now, the implementation requires the mutability of the matching and matched references to be the same. I'm open to changing this to allow an immutable reference pattern to match against a mutable reference; this would be a backward-compatible change, so I'm leaving it as a future possibility in light of the edition time crunch. Edit: & patterns can match against &mut references (whether inherited or not).

• As implemented, an &mut pattern will consume an &mut in the scrutinee even if there is an inherited &:

if let Some(Some(&mut x)) = &Some(Some(&mut 0)) {
    let _: &u32 = x;
}

• As a further extension, an &mut pattern can "peel off" multiple layers of & in the scrutinee:

let &mut x = &&mut 0;
let _: &u32 = x;

let &mut x = &&&&&&&&&&&&&&&&&&&&&&&&&&&&mut 0;
let _: &u32 = x;

let &mut &mut &mut &mut x = &mut &&&&mut &&&mut &mut 0;
let _: &u32 = x;

Alternatives

The alternative "eat-two-layers" proposal is also implemented behind its own feature gate, if the lang team feels that eat-one-layer is too ambitious we can switch to it. We could also do eat-two-layers in ≤ 2021 along with eat-one-layer in ≥ 2024, but that would require (slightly) more complexity, and "editions are meant to be adopted."

Never inherit mutable reference behind shared

As implemented, in edition 2024 a mutable match-ergonomics reference is never generated behind a shared reference pattern. This is necessary for the code below to work even though & patterns can't yet consume &mut:

if let Some(&Some(x)) = &mut Some(&Some(0)) {
    let _: &u32 = x;
}

It also allows the below to compile:

if let &Some(Some(x)) = &Some(&mut Some(0)) {
               // ^ ERROR cannot borrow as mutable (on today's Rust) → shared borrow (with current impl on Rust 2024)
    let a: &u8 = x;
} 

This behavior could be extended to all editions, as implemented it's 2024 only. A future possibility is to be even smarter, and downgrade to & in more situations where staying as &mut leads to an error.

Migration lint + rustfix

The major missing piece that's not implemented yet. The rustfix suggestion entirely desugars the match ergonomics of any pattern whose meaning is changed. Maybe we can be smarter than that, but it's probably not worth the additional complexity.

@traviscross go ahead and nominate this if you'd like

[traviscross]

@rustbot labels -A-edition-2024

We're going to move the edition tag over to...

• Tracking issue for Rust 2024: Match ergonomics rules 1C/2C #131414

...so as to track what's going in Rust 2024 separately from the broader RFC 3627 work.