为 no_std 环境提供 derive(Error)

这是使用 no_std 环境中 nightly 仅有的实验性 error_in_core 功能对 thiserror 的分支。

使用方法

// Cargo.toml
[dependencies]
thiserror = { version = "1.0", package = "thiserror-core", default-features = false }

编译器支持：需要 rustc 1.56+ @@ -23,200 +18,16 @@ thiserror = "1.0"

示例

// main.rs / lib.rs
#![no_std]
#![feature(error_in_core)]

此错误与 thiserror-core 之间的差异

差异保持在最小，thiserror master 的更改将通过重新基础 thiserror-core 被采用。

默认启用 std 功能时，此错误和 thiserror-core 之间的任何功能性差异都视为错误。

一旦采用等效更改，此 crate 将更新以重新导出 thiserror。

lib.rs:

此库为标准库的 std::error::Error 特性提供了一个方便的 derive 宏。

示例

use thiserror::Error;

#[derive(Error, Debug)]
pub enum DataStoreError {
    #[error("data store disconnected")]
    Disconnect(#[from] io::Error),
    #[error("the data for key `{0}` is not available")]
    Redaction(String),
    #[error("invalid header (expected {expected:?}, found {found:?})")]
    InvalidHeader {
        expected: String,
        found: String,
    },
    #[error("unknown data store error")]
    Unknown,
}

详细信息

• Thiserror 故意不在您的公共 API 中出现。您将获得与手动编写 std::error::Error 实现相同的结果，从手动实现切换到 thiserror 或反之亦然不会引起破坏性更改。

• 错误可以是枚举、具有命名字段的元组结构体、元组结构体或单元结构体。

• 如果您在结构体或枚举的每个变体上提供 #[error)] 消息，将为您的错误生成一个 Display 实现如下例所示。

  消息支持从错误中插值字段的缩写。

  • #[error("{var}")] ⟶ write!("{}", self.var)
  • #[error("{0}")] ⟶ write!("{}", self.0)
  • #[error("{var:?}")] ⟶ write!("{:?}", self.var)
  • #[error("{0:?}")] ⟶ write!("{:?}", self.0)

  这些缩写可以与任何额外的格式参数一起使用，这些参数可以是任意表达式。例如

  #
  #[derive(Error, Debug)]
  pub enum Error {
      #[error("invalid rdo_lookahead_frames {0} (expected < {})", i32::MAX)]
      InvalidLookahead(u32),
  }
  

  如果其中一个额外的表达式参数需要引用结构体或枚举的字段，那么可以将命名字段作为 .var 引用，并将元组字段作为 .0 引用。

  #
  #
  #
  #[derive(Error, Debug)]
  pub enum Error {
      #[error("first letter must be lowercase but was {:?}", first_char(.0))]
      WrongCase(String),
      #[error("invalid index {idx}, expected at least {} and at most {}", .limits.lo, .limits.hi)]
      OutOfBounds { idx: usize, limits: Limits },
  }
  

• 为每个包含具有 #[from] 属性的变体的 From 实现生成。

  请注意，变体不得包含任何其他字段，除了源错误以及可能的堆栈跟踪。如果存在相应的字段，堆栈跟踪将在 From 实现内部捕获。

  #[derive(Error, Debug)]
  pub enum MyError {
      Io {
          #[from]
          source: io::Error,
          backtrace: Backtrace,
      },
  }
  

• 实现了 Error 特质的 source() 方法，以返回具有 #[source] 属性或名为 source 的任何字段。这是为了识别导致您错误的底层错误。

  #[from] 属性始终意味着相同的字段是 #[source]，因此您永远不需要指定这两个属性。

  实现了 std::error::Error 或对 dyn std::error::Error 的解引用都将作为源。

  #
  #[derive(Error, Debug)]
  pub struct MyError {
      msg: String,
      #[source]  // optional if field name is `source`
      source: anyhow::Error,
  }
  #
  

• Error 特性的 provide() 方法被实现，用于提供具有名为 Backtrace 的类型的字段，如果有，作为一个 std::backtrace::Backtrace。

  use std::backtrace::Backtrace;
  
  #[derive(Error, Debug)]
  pub struct MyError {
      msg: String,
      backtrace: Backtrace,  // automatically detected
  }
  

• 如果一个字段既是源（命名为 source，或者有 #[source] 或 #[from] 属性）并且被标记为 #[backtrace]，那么 Error 特性的 provide() 方法将被转发到源对象的 provide，以便错误的两层都能共享相同的回溯。

  #[derive(Error, Debug)]
  pub enum MyError {
      Io {
          #[backtrace]
          source: io::Error,
      },
  }
  

• 错误可以使用 error(transparent) 来直接将源和显示方法转发到底层的错误，而不添加额外的消息。这对于需要“其他”变体的枚举来说将是很合适的。

  #
  #[derive(Error, Debug)]
  pub enum MyError {
      # /*
      ...
      # */
  
      #[error(transparent)]
      Other(#[from] anyhow::Error),  // source and Display delegate to anyhow::Error
  }
  

  另一个用例是在不破坏crate的公共API的情况下，隐藏错误表示的实现细节，使表示能够进化。

  #
  // PublicError is public, but opaque and easy to keep compatible.
  #[derive(Error, Debug)]
  #[error(transparent)]
  pub struct PublicError(#[from] ErrorRepr);
  
  impl PublicError {
      // Accessors for anything we do want to expose publicly.
  }
  
  // Private and free to change across minor version of the crate.
  #[derive(Error, Debug)]
  enum ErrorRepr {
      # /*
      ...
      # */
  }
  

• 有关在应用程序代码中使用方便的单个错误类型，请参阅 anyhow 库。