Match ergonomics reservations - The Rust Edition Guide

## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

# Match ergonomics reservations

## Summary

- Writing `mut`, `ref`, or `ref mut` on a binding is only allowed within a pattern when the pattern leading up to that binding is fully explicit (i.e. when it does not use match ergonomics).
  - Put differently, when the default binding mode is not `move`, writing `mut`, `ref`, or `ref mut` on a binding is an error.
- Reference patterns (`&` or `&mut`) are only allowed within the fully-explicit prefix of a pattern.
  - Put differently, reference patterns can only match against references in the scrutinee when the default binding mode is `move`.

## Details

### Background

Within `match`, `let`, and other constructs, we match a pattern against a scrutinee. E.g.:

    #![allow(unused)]
    fn main() {
    let &[&mut [ref x]] = &[&mut [()]]; // x: &()
    //  ~~~~~~~~~~~~~~~   ~~~~~~~~~~~~
    //      Pattern        Scrutinee
    }

Such a pattern is called fully explicit because it does not elide (i.e. “skip” or “pass”) any references within the scrutinee. By contrast, this otherwise-equivalent pattern is not fully explicit:

    #![allow(unused)]
    fn main() {
    let [[x]] = &[&mut [()]]; // x: &()
    }

Patterns such as this are said to be using match ergonomics, originally introduced in RFC 2005.

Under match ergonomics, as we incrementally match a pattern against a scrutinee, we keep track of the default binding mode. This mode can be one of `move`, `ref mut`, or `ref`, and it starts as `move`. When we reach a binding, unless an explicit binding mode is provided, the default binding mode is used to decide the binding’s type.

For example, here we provide an explicit binding mode, causing `x` to be bound by reference:

    #![allow(unused)]
    fn main() {
    let ref x = (); // &()
    }

By contrast:

    #![allow(unused)]
    fn main() {
    let [x] = &[()]; // &()
    }

Here, in the pattern, we pass the outer shared reference in the scrutinee. This causes the default binding mode to switch from `move` to `ref`. Since there is no explicit binding mode specified, the `ref` binding mode is used when binding `x`.

### `mut` restriction

In Rust 2021 and earlier editions, we allow this oddity:

    #![allow(unused)]
    fn main() {
    let [x, mut y] = &[(), ()]; // x: &(), mut y: ()
    }

Here, because we pass the shared reference in the pattern, the default binding mode switches to `ref`. But then, in these editions, writing `mut` on the binding resets the default binding mode to `move`.

This can be surprising as it’s not intuitive that mutability should affect the type.

To leave space to fix this, in Rust 2024 it’s an error to write `mut` on a binding when the default binding mode is not `move`. That is, `mut` can only be written on a binding when the pattern (leading up to that binding) is fully explicit.

In Rust 2024, we can write the above example as:

    #![allow(unused)]
    fn main() {
    let &[ref x, mut y] = &[(), ()]; // x: &(), mut y: ()
    }

### `ref` / `ref mut` restriction

In Rust 2021 and earlier editions, we allow:

    #![allow(unused)]
    fn main() {
    let [ref x] = &[()]; // x: &()
    }

Here, the `ref` explicit binding mode is redundant, as by passing the shared reference (i.e. not mentioning it in the pattern), the binding mode switches to `ref`.

To leave space for other language possibilities, we are disallowing explicit binding modes where they are redundant in Rust 2024. We can rewrite the above example as simply:

    #![allow(unused)]
    fn main() {
    let [x] = &[()]; // x: &()
    }

### Reference patterns restriction

In Rust 2021 and earlier editions, we allow this oddity:

    #![allow(unused)]
    fn main() {
    let [&x, y] = &[&(), &()]; // x: (), y: &&()
    }

Here, the `&` in the pattern both matches against the reference on `&()` and resets the default binding mode to `move`. This can be surprising because the single `&` in the pattern causes a larger than expected change in the type by removing both layers of references.

To leave space to fix this, in Rust 2024 it’s an error to write `&` or `&mut` in the pattern when the default binding mode is not `move`. That is, `&` or `&mut` can only be written when the pattern (leading up to that point) is fully explicit.

In Rust 2024, we can write the above example as:

    #![allow(unused)]
    fn main() {
    let &[&x, ref y] = &[&(), &()];
    }

## Migration

The `rust_2024_incompatible_pat` lint flags patterns that are not allowed in Rust 2024. This lint is part of the `rust-2024-compatibility` lint group which is automatically applied when running `cargo fix --edition`. This lint will automatically convert affected patterns to fully explicit patterns that work correctly in Rust 2024 and in all prior editions.

To migrate your code to be compatible with Rust 2024, run:

    cargo fix --edition

For example, this will convert this…

    #![allow(unused)]
    fn main() {
    let [x, mut y] = &[(), ()];
    let [ref x] = &[()];
    let [&x, y] = &[&(), &()];
    }

…into this:

    #![allow(unused)]
    fn main() {
    let &[ref x, mut y] = &[(), ()];
    let &[ref x] = &[()];
    let &[&x, ref y] = &[&(), &()];
    }

Alternatively, you can manually enable the lint to find patterns that will need to be migrated:

    #![allow(unused)]
    fn main() {
    // Add this to the root of your crate to do a manual migration.
    #![warn(rust_2024_incompatible_pat)]
    }