Stabilize min_exhaustive_patterns

[Nadrieril]

Stabilisation report

I propose we stabilize the min_exhaustive_patterns language feature.

With this feature, patterns of empty types are considered unreachable when matched by-value. This allows:

enum Void {}
fn foo() -> Result<u32, Void>;

fn main() {
  let Ok(x) = foo();
  // also
  match foo() {
    Ok(x) => ...,
  }
}

This is a subset of the long-unstable exhaustive_patterns feature. That feature is blocked because omitting empty patterns is tricky when not matched by-value. This PR stabilizes the by-value case, which is not tricky.

The not-by-value cases (behind references, pointers, and unions) stay as they are today, e.g.

enum Void {}
fn foo() -> Result<u32, &Void>;

fn main() {
  let Ok(x) = foo(); // ERROR: missing `Err(_)`
}

The consequence on existing code is some extra "unreachable pattern" warnings. This is fully backwards-compatible.

Comparison with today's rust

This proposal only affects match checking of empty types (i.e. types with no valid values). Non-empty types behave the same with or without this feature. Note that everything below is phrased in terms of match but applies equallly to if let and other pattern-matching expressions.

To be precise, a visibly empty type is:

• an enum with no variants;
• the never type !;
• a struct with a visible field of a visibly empty type (and no #[non_exhaustive] annotation);
• a tuple where one of the types is visibly empty;
• en enum with all variants visibly empty (and no #[non_exhaustive] annotation);
• a [T; N] with N != 0 and T visibly empty;
• all other types are nonempty.

(An extra change was proposed below: that we ignore #[non_exhaustive] for structs since adding fields cannot turn an empty struct into a non-empty one)

For normal types, exhaustiveness checking requires that we list all variants (or use a wildcard). For empty types it's more subtle: in some cases we require a _ pattern even though there are no valid values that can match it. This is where the difference lies regarding this feature.

Today's rust

Under today's rust, a _ is required for all empty types, except specifically: if the matched expression is of type ! (the never type) or EmptyEnum (where EmptyEnum is an enum with no variants), then the _ is not required.

let foo: Result<u32, !> = ...;
match foo {
    Ok(x) => ...,
    Err(_) => ..., // required
}
let foo: Result<u32, &!> = ...;
match foo {
    Ok(x) => ...,
    Err(_) => ..., // required
}
let foo: &! = ...;
match foo {
    _ => ..., // required
}
fn blah(foo: (u32, !)) {
    match foo {
        _ => ..., // required
    }
}
unsafe {
    let ptr: *const ! = ...;
    match *ptr {} // allowed
    let ptr: *const (u32, !) = ...;
    match *ptr {
        (x, _) => { ... } // required
    }
    let ptr: *const Result<u32, !> = ...;
    match *ptr {
        Ok(x) => { ... }
        Err(_) => { ... } // required
    }
}

After this PR

After this PR, a pattern of an empty type can be omitted if (and only if):

• the match scrutinee expression has type ! or EmptyEnum (like before);
• or the empty type is matched by value (that's the new behavior).

In all other cases, a _ is required to match on an empty type.

let foo: Result<u32, !> = ...;
match foo {
    Ok(x) => ..., // `Err` not required
}
let foo: Result<u32, &!> = ...;
match foo {
    Ok(x) => ...,
    Err(_) => ..., // required because `!` is under a dereference
}
let foo: &! = ...;
match foo {
    _ => ..., // required because `!` is under a dereference
}
fn blah(foo: (u32, !)) {
    match foo {} // allowed
}
unsafe {
    let ptr: *const ! = ...;
    match *ptr {} // allowed
    let ptr: *const (u32, !) = ...;
    match *ptr {
        (x, _) => { ... } // required because the matched place is under a (pointer) dereference
    }
    let ptr: *const Result<u32, !> = ...;
    match *ptr {
        Ok(x) => { ... }
        Err(_) => { ... } // required because the matched place is under a (pointer) dereference
    }
}

Documentation

The reference does not say anything specific about exhaustiveness checking, hence there is nothing to update there. The nomicon does, I opened rust-lang/nomicon#445 to reflect the changes.

Tests

The relevant tests are in tests/ui/pattern/usefulness/empty-types.rs.

Unresolved Questions

None that I know of.

try-job: dist-aarch64-apple

[rustbot]

r? @cjgillot

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

[rustbot]

Some changes occurred in compiler/rustc_codegen_cranelift

cc @bjorn3

Some changes occurred in compiler/rustc_codegen_gcc

cc @antoyo, @GuillaumeGomez

Some changes occurred in src/tools/clippy

cc @rust-lang/clippy

The Miri subtree was changed

cc @rust-lang/miri

[kpreid]

I filed issue #129031 to give this matter more visibility.

[rylev]

@Nadrieril @fee1-dead seems this has a negative impact on the performance of coherence checking which I imagined is expected, right? I'm not sure if there's anything we would want to do given that there's simply more work happening. Thoughts?

[Nadrieril]

@rylev yeah, at the very least it's calculating inhabitedness of essentially all types involed in patterns, which has unavoidable cost.

[Dr-Emann]

I think I found either a bug, or a confusing error: https://play.rust-lang.org/?version=nightly&mode=debug&edition=2024&gist=08d6bead0bfb94e25a784eb88f8d059f

let x: Result<(), Infallible> = Ok(());
match *&x {
  Ok(()) => { println!("Must be OK"); }
}

Errors (it doesn't seem to consider *&x to be matching by value):

note: the matched value is of type `Result<(), Infallible>`
note: `Infallible` is uninhabited but is not being matched by value, so a wildcard `_` is required

As far as I know, I would consider that to be matching by value, but it's possible there's some "place vs value" theory that means it's not technically by value.

[Nadrieril]

Indeed this isn't by-value because the Infallible value isn't copied: this is matching on the *&x place which is located behind a reference. It would be matching by-value if you forced a copy with match {*&x} { ... }.

Tbf the line above says "the matched value is of type" when it might be less confusing to say "the matched place is of type".