thiserror_core2

thiserror 但使用 core2 以支持 no_std

lib.rs:

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

示例

use thiserror_core2::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 中出现。你可以获得与手动实现 core2::error::Error 特性相同的结果，从手动实现 impl 切换到 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,
      },
  }
  

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

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

  实现 core2::error::Error 或解引用到 dyn core2::error::Error 的任何错误类型都将作为一个源。

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

• 错误特质的 backtrace() 方法被实现为返回任何具有名为 Backtrace 的类型的字段，如果有的话。

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

• 如果一个字段既是源（命名为 source 或有 #[source] 或 #[from] 属性）并且被标记为 #[backtrace]，那么错误特质的 backtrace() 方法将转发到源的后向跟踪。

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

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

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