类型系统属性

以下属性用于更改类型的使用方式。

[attributes.type-system.non_exhaustive]

`non_exhaustive` 属性

[attributes.type-system.non_exhaustive.intro]

non_exhaustive 属性指示类型或变体将来可能会添加更多字段或变体。

[attributes.type-system.non_exhaustive.allowed-positions]

它可以应用于结构体、枚举和 enum 变体。

[attributes.type-system.non_exhaustive.syntax]

non_exhaustive 属性使用 MetaWord 语法，因此不接受任何输入。

[attributes.type-system.non_exhaustive.same-crate]

在定义 crate 内，non_exhaustive 没有效果。

#![allow(unused)]
fn main() {
#[non_exhaustive]
pub struct Config {
    pub window_width: u16,
    pub window_height: u16,
}

#[non_exhaustive]
pub struct Token;

#[non_exhaustive]
pub struct Id(pub u64);

#[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 };
let token = Token;
let id = Id(4);

// Non-exhaustive structs can be matched on exhaustively within the defining crate.
let Config { window_width, window_height } = config;
let Token = token;
let Id(id_number) = id;

let error = Error::Other;
let message = Message::Reaction(3);

// 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(id) => { },
    Message::Quit => { },
}
}

[attributes.type-system.non_exhaustive.external-crate]

在定义 crate 外部，带有 non_exhaustive 注释的类型在添加新字段或变体时具有保留向后兼容性的限制。

[attributes.type-system.non_exhaustive.construction]

非穷举类型无法在定义 crate 外部构造：

非穷举变体（struct 或 enum 变体）无法使用 StructExpression 构造（包括使用函数式更新语法）。
类单元结构体的隐式定义的同名常量，或元组结构体的同名构造函数，其可见性不超过 pub(crate)。也就是说，如果结构体的可见性是 pub，则常量或构造函数的可见性是 pub(crate)，否则两个项的可见性相同（与没有 #[non_exhaustive] 时的情况相同）。
enum 实例可以被构造。

以下构造示例在定义 crate 外部无法编译：

// These are types defined in an upstream crate that have been annotated as
// `#[non_exhaustive]`.
use upstream::{Config, Token, Id, 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 };

// Cannot construct an instance of `Token`; if new fields were added, then
// it would not be a unit-like struct any more, so the same-named constant
// created by it being a unit-like struct is not public outside the crate;
// this code fails to compile.
let token = Token;

// Cannot construct an instance of `Id`; if new fields were added, then
// its constructor function signature would change, so its constructor
// function is not public outside the crate; this code fails to compile.
let id = Id(5);

// 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 enum variant `upstream`, this would fail to compile.
let message = Message::Quit;

[attributes.type-system.non_exhaustive.match]

在定义 crate 外部匹配非穷举类型时有限制：

当对非穷举变体（struct 或 enum 变体）进行模式匹配时，必须使用包含 .. 的 StructPattern。元组枚举变体构造函数的可见性被降低到不超过 pub(crate)。
当对非穷举 enum 进行模式匹配时，匹配变体不会对分支的穷举性有贡献。以下匹配示例在定义 crate 外部无法编译：

// These are types defined in an upstream crate that have been annotated as
// `#[non_exhaustive]`.
use upstream::{Config, Token, Id, 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: `..`
}

// Cannot match a non-exhaustive unit-like or tuple struct except by using
// braced struct syntax with a wildcard.
// This would compile as `let Token { .. } = token;`
let Token = token;
// This would compile as `let Id { 0: id_number, .. } = id;`
let Id(id_number) = id;

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 => { },
}

也不允许对包含任何非穷举变体的枚举使用数值类型转换（as）。

例如，以下枚举可以被转换，因为它不包含任何非穷举变体：

#![allow(unused)]
fn main() {
#[non_exhaustive]
pub enum Example {
    First,
    Second,
}
}

但是，如果枚举包含哪怕一个非穷举变体，转换也会导致错误。考虑同一个枚举的这个修改版本：

#![allow(unused)]
fn main() {
#[non_exhaustive]
pub enum EnumWithNonExhaustiveVariants {
    First,
    #[non_exhaustive]
    Second,
}
}

use othercrate::EnumWithNonExhaustiveVariants;

// Error: cannot cast an enum with a non-exhaustive variant when it's defined in another crate
let _ = EnumWithNonExhaustiveVariants::First as u8;

非穷举类型在下游 crate 中始终被视为已居住。

Keyboard shortcuts

The Rust Reference (中文版)

类型系统属性

non_exhaustive 属性

`non_exhaustive` 属性