Rust Reference ยท Attributes
The #[non_exhaustive] attribute
Reference for Rust #[non_exhaustive]: how it affects structs, enums and variants for other crates, matching with a wildcard arm, and semver benefits.
#[non_exhaustive] tells other crates that a public struct, enum or enum variant may gain more fields or variants in the future. It lets a library add them in a minor release without breaking downstream code.
The restrictions apply only outside the crate that defines the type. For an enum, match expressions in other crates must include a wildcard arm. For a struct or variant, other crates cannot build it with a struct literal or match all its fields without ...
#[non_exhaustive] pub enum Error { NotFound, Denied }
Try it
Inside one crate the attribute changes nothing, and the runner only compiles one crate. The examples therefore show the code a downstream crate would have to write, and keep it valid inside the defining crate.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Syntax
#[non_exhaustive] pub struct S { pub a: i32 } #[non_exhaustive] pub enum E { A, #[non_exhaustive] B { x: i32 } }
| Applied to | Restriction in other crates |
|---|---|
| Enum | match must have a wildcard (or binding) arm; casting is unaffected |
| Enum variant | Cannot be constructed or exhaustively matched without .. |
| Struct | Cannot be built with a struct literal, nor matched without ..; the type with Default or a constructor is the way in |
Edge cases:
- Tuple structs with
#[non_exhaustive]cannot be constructed with their tuple syntax from other crates. - The attribute is ignored for code in the defining crate, so you will not see an error while testing locally.
- Applied to a struct whose fields are all private, it adds nothing.
Usage notes
- Semver tool. Adding a variant to an exhaustive public enum is a breaking change; with
#[non_exhaustive]it is not. - Cost for callers. Users must write a catch-all arm, which loses the compiler's help when a new variant appears. Choose it for types that really will grow (error enums, option bags), not for fixed sets like
Ordering. - Pair with constructors or builders for structs, because public fields alone cannot be used to create values.
- Prefer private fields when you need to forbid construction entirely; use
#[non_exhaustive]when readable public fields are the goal. - Lint helper. The
non_exhaustive_omitted_patternslint is unstable, so there is no stable way to be warned about unlisted variants. - Standard library examples include
std::io::ErrorKindand several error enums.