Struct Error

pub struct Error { /* private fields */ }

The error type used by the library.

Errors generally form a chain, with higher-level errors typically providing additional context for lower level ones. E.g., an IO error such as file-not-found could be reported by a system level API (such as std::fs::File::open) and may be contextualized with the path to the file attempted to be opened.

use std::fs::File;
use std::error::Error as _;

let path = "/does-not-exist";
let result = File::open(path).with_context(|| format!("failed to open {path}"));

let err = result.unwrap_err();
assert_eq!(err.to_string(), "failed to open /does-not-exist");

// Retrieve the underlying error.
let inner_err = err.source().unwrap();
assert!(inner_err.to_string().starts_with("No such file or directory"));

For convenient reporting, the Display representation takes care of reporting the complete error chain when the alternate flag is set:

// > failed to open /does-not-exist: No such file or directory (os error 2)
println!("{err:#}");

The Debug representation similarly will print the entire error chain, but will do so in a multi-line format:

// > Error: failed to open /does-not-exist
// >
// > Caused by:
// >     No such file or directory (os error 2)
println!("{err:?}");

Implementations

impl Error

pub fn from_raw_os_error(code: i32) -> Self

Create an Error from an OS error code (typically errno).

Notes

An OS error code should always be positive.

pub fn kind(&self) -> ErrorKind

Retrieve a rough error classification in the form of an ErrorKind.

Trait Implementations

impl Debug for Error

fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult

Formats the value using the given formatter.

impl Display for Error

fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult

Formats the value using the given formatter.

impl Error for Error

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl ErrorExt for Error

type Output = Error

The output type produced by context and with_context.

fn context<C>(self, context: C) -> Self::Output

where C: IntoCowStr,

Add context to this error.

fn with_context<C, F>(self, f: F) -> Self::Output

where C: IntoCowStr, F: FnOnce() -> C,

Add context to this error, using a closure for lazy evaluation.

impl From<Error> for Error

fn from(other: Error) -> Self

Converts to this type from the input type.