Skip to content
Tutorials Center
My learning

Topics

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 ...

Rust
#[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.

Rust Matching an enum that may grow

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.

Rust A struct other crates must build through a constructor

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

Rust
#[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_patterns lint is unstable, so there is no stable way to be warned about unlisted variants.
  • Standard library examples include std::io::ErrorKind and several error enums.