Stabilization proposal

Tracking issue: #44019
Version target: TBD

As per the stabilization guide, I'd like to propose stabilizing #[non_exhaustive]:

cc @rust-lang/lang

What is stabilized

The non_exhaustive attribute is used to indicate that a type will have
more fields/variants added in the future. It can be applied to
structs, enums and enum variants.

Within the defining crate, types annotated with non_exhaustive behave exactly
the same as if the type were not annotated with non_exhaustive:

#[non_exhaustive]
pub struct Config {
    pub window_width: u16,
    pub window_height: u16,
}
#[non_exhaustive]
pub enum Error {
    Message(String),
    Other,
}
pub enum Message {
    #[non_exhaustive] Send { from: u32, to: u32, contents: String },
    #[non_exhaustive] Reaction(u32),
    #[non_exhaustive] Quit,
}
// Non-exhaustive structs can be constructed as normal within the defining crate.
let config = Config { window_width: 640, window_height: 480 };
// Non-exhaustive structs can be matched on exhaustively within the defining crate.
if let Ok(Config { window_width, window_height }) = config {
    // ...
}
// Non-exhaustive enums can be matched on exhaustively within the defining crate.
match error {
    Error::Message(ref s) => { },
    Error::Other => { },
}
match message {
    // Non-exhaustive variants can be matched on exhaustively within the defining crate.
    Message::Send { from, to, contents } => { },
    Message::Reaction(type) => { },
    Message::Quit => { },
}

In downstream crates, types annotated with non_exhaustive have limitations that
preserve backwards compatibility when new fields/variants are added.

Non-exhaustive types cannot be constructed in downstream crates:

// `Config`, `Error` and `Message` are types defined in an upstream crate that have been
// annotated as `#[non_exhaustive]`.
use upstream::{Config, Error, Message};
// Cannot construct an instance of `Config`, if new fields were added in
// a new version of `upstream` then this would fail to compile, so it is
// disallowed.
let config = Config { window_width: 640, window_height: 480 };
// Can construct an instance of `Error`, new variants being introduced would
// not result in this failing to compile.
let error = Error::Message("foo".to_string());
// Cannot construct an instance of `Message::Send` or `Message::Reaction`,
// if new fields were added in a new version of `upstream` then this would
// fail to compile, so it is disallowed.
let message = Message::Send { from: 0, to: 1, contents: "foo".to_string(), };
let message = Message::Reaction(0);
// Cannot construct an instance of `Message::Quit`, if this were converted to
// a tuple-variant `upstream` then this would fail to compile.
let message = Message::Quit;

Non-exhaustive types cannot be used in a match/if let expression without a
wildcard arm:

// `Config`, `Error` and `Message` are types defined in an upstream crate that have been
// annotated as `#[non_exhaustive]`.
use upstream::{Config, Error, Message};
// Cannot match on a non-exhaustive enum without including a wildcard arm.
match error {
  Error::Message(ref s) => { },
  Error::Other => { },
  // would compile with: `_ => {},`
}
// Cannot match on a non-exhaustive struct without a wildcard.
if let Ok(Config { window_width, window_height }) = config {
    // would compile with: `..`
}
match message {
  // Cannot match on a non-exhaustive struct enum variant without including a wildcard.
  Message::Send { from, to, contents } => { },
  // Cannot match on a non-exhaustive tuple or unit enum variant.
  Message::Reaction(type) => { },
  Message::Quit => { },
}

Non-exhaustive types are always considered inhabited in downstream crates.

What is not stabilized

N/A

Divergences from RFC

It is not specified in the RFC what the inhabitedness of non-exhaustive types used extern
crates should be. Since #60529, non-exhaustive types are always considered inhabited in
extern crates.

Tests

The tests are all in src/test/ui/rfc-2008-non-exhaustive. Here are some of them:

Motivation

See RFC 2008.

History

Was originally proposed in RFC rust-lang/rfcs#2008.
Implemented for enums/structs in #45394 by @davidtwco (reviewed by @nikomatsakis, @petrochenkov, @oli-obk, @arielb1).
Merged on Nov 4th 2017.
Attribute prohibited on unions, other incorrect locations in #49345 by @davidtwco (reviewed by @nikomatsakis)
Merged on Apr 5th 2018.
Support in rustdoc in #51854 by @davidtwco (reviewed by @QuietMisdreavus, @clarfon, @frewsxcv)
Merged on Jul 19th 2018.
Improved in #53721 by @arielb1 (reviewed by @nikomatsakis, @eddyb)
Merged on Sep 6th 2018.
Fixed #53549.
Implemented for enum variants in #59376 by @davidtwco (reviewed by @petrochenkov, @QuietMisdreavus, @GuillaumeGomez)
Merged on March 30th 2019.
Fixed and added tests for uninhabitedness in #60529 by @davidtwco (reviewed by @petrochenkov, @Centril)
Merged on May 10th 2019.
Update reference for #[non_exhaustive] in rust-lang-nursery/reference#609 by @davidtwco
Submitted on May 12th 2019. Not yet merged!
Update book for #[non_exhaustive] in rust-lang/book#1955 by @davidtwco
Submitted on May 12th 2019. Not yet merged!