Repository: rust
Issue: Tracking Issue for Never Patterns (`never_patterns`)
Labels: T-lang,B-unstable,C-tracking-issue,A-exhaustiveness-checking,S-tracking-impl-incomplete,F-never_patterns,B-experimental

This is a tracking issue for the experimental "never patterns" feature (as per the T-lang [experimental feature](https://github.com/rust-lang/lang-team/blob/master/src/how_to/experiment.md) process).
The feature gate for the issue is `#![feature(never_patterns)]`.

RFC: https://github.com/rust-lang/rfcs/pull/3719

This feature introduces a new syntax for patterns: `!`. In a pattern, `!` is valid for any uninhabited type and simply acknowledges that the type is empty. Because a never pattern is statically known to be unreachable, it obeys slightly different rules:

```rust
enum Void {}
let result: *const Result<u32, Void> = ...;
unsafe {
    match *result {
        Ok(x) => { foo(x) }
        Err(!), // no need for `=> <expr>`
    }
    let (Ok(x) | Err(!)) = *result; // valid
}

fn blah(!: Void) -> SomeType {} // the function can never be called so it doesn't need a body
```

This feature does _not_ affect exhaustiveness or pattern reachability; see the [`exhaustive_patterns`](https://github.com/rust-lang/rust/issues/51085) and [`min_exhaustive_patterns`](https://github.com/rust-lang/rust/issues/119612) features for that.

### 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
<!--
Include each step required to complete the feature. Typically this is a PR
implementing a feature, followed by a PR that stabilises the feature. However
for larger features an implementation could be broken up into multiple PRs.
-->

- [ ] Implement the feature
- [ ] Write an RFC and have it accepted
- [ ] Adjust documentation ([see instructions on rustc-dev-guide][doc-guide])
- [ ] Formatting for new syntax has been added to the [Style Guide] ([nightly-style-procedure])
- [ ] Stabilization PR ([see instructions on rustc-dev-guide][stabilization-guide])

[stabilization-guide]: https://rustc-dev-guide.rust-lang.org/stabilization_guide.html#stabilization-pr
[doc-guide]: https://rustc-dev-guide.rust-lang.org/stabilization_guide.html#documentation-prs
[nightly-style-procedure]: https://github.com/rust-lang/style-team/blob/master/nightly-style-procedure.md 
[Style Guide]: https://github.com/rust-lang/rust/tree/master/src/doc/style-guide

### Unresolved Questions
<!--
Include any open questions that need to be answered before the feature can be
stabilised.
-->

```[tasklist]
### Implementation plans/details
- [x] `!` is parsed as a pattern.
- [x] Parsing of `match` expressions allows `match <expr> { <pat>, ... }` i.e. a pattern without a body. We later check to only allow that if the pattern is a never pattern.
- [ ] The lack of body is desugared into something equivalent to `unreachable_unchecked!()`.
- [x] Never patterns skip the or-pattern bindings check, to allow `Ok(x) | Err(!)`
- [x] Never patterns don't allow bindings, like in `(x, !)`
- [x] Allow `fn foo(!: Void) -> SomeType {}`
- [x] `!` is typechecked like a wildcard; it adds no type constraint
- [x] In match checking we check that `!` is only used on an uninhabited type (modulo match ergonomics).
- [ ] The `!` pattern is lowered to MIR.
- [ ] A `!` pattern asserts validiy of the matched place
- [x] Exhaustiveness understands `!`.
- [x] Exhaustiveness recommends using never patterns where sensible.
- [ ] Rustfmt understands never patterns
- [ ] Check every bit of the compiler that handles or-patterns to see if it handles never patterns properly
- [x] Write up the RFC
- [ ] https://github.com/rust-lang/rust/issues/120240
```

```[tasklist]
### Implementation history
- [ ] https://github.com/rust-lang/rust/pull/118157
- [ ] #118527
- [ ] https://github.com/rust-lang/rust/pull/118868
- [ ] https://github.com/rust-lang/rust/pull/119610
- [ ] https://github.com/rust-lang/rust/pull/119622
- [ ] https://github.com/rust-lang/rust/pull/120009
- [ ] https://github.com/rust-lang/rust/pull/120097
- [ ] https://github.com/rust-lang/rust/pull/120104
- [ ] https://github.com/rust-lang/rust/pull/120517
- [ ] https://github.com/rust-lang/rust/pull/120758
- [ ] https://github.com/rust-lang/rust/pull/121391
- [ ] https://github.com/rust-lang/rust/pull/121823
- [ ] https://github.com/rust-lang/rust/pull/123332
```