Trait std::error::Error

1.0.0 · source · [−]
pub trait Error: Debug + Display {
    fn source(&self) -> Option<&(dyn Error + 'static)> { ... }
    fn backtrace(&self) -> Option<&Backtrace> { ... }
    fn description(&self) -> &str { ... }
    fn cause(&self) -> Option<&dyn Error> { ... }
    fn provide<'a>(&'a self, req: &mut Demand<'a>) { ... }
}
Expand description

Error is a trait representing the basic expectations for error values, i.e., values of type E in Result<T, E>.

Errors must describe themselves through the Display and Debug traits. Error messages are typically concise lowercase sentences without trailing punctuation:

let err = "NaN".parse::<u32>().unwrap_err();
assert_eq!(err.to_string(), "invalid digit found in string");
Run

Errors may provide cause chain information. Error::source() is generally used when errors cross “abstraction boundaries”. If one module must report an error that is caused by an error from a lower-level module, it can allow accessing that error via Error::source(). This makes it possible for the high-level module to provide its own errors while also revealing some of the implementation for debugging via source chains.

Provided Methods

The lower-level source of this error, if any.

Examples
use std::error::Error;
use std::fmt;

#[derive(Debug)]
struct SuperError {
    source: SuperErrorSideKick,
}

impl fmt::Display for SuperError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "SuperError is here!")
    }
}

impl Error for SuperError {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        Some(&self.source)
    }
}

#[derive(Debug)]
struct SuperErrorSideKick;

impl fmt::Display for SuperErrorSideKick {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "SuperErrorSideKick is here!")
    }
}

impl Error for SuperErrorSideKick {}

fn get_super_error() -> Result<(), SuperError> {
    Err(SuperError { source: SuperErrorSideKick })
}

fn main() {
    match get_super_error() {
        Err(e) => {
            println!("Error: {e}");
            println!("Caused by: {}", e.source().unwrap());
        }
        _ => println!("No error"),
    }
}
Run
🔬 This is a nightly-only experimental API. (backtrace #53487)

Returns a stack backtrace, if available, of where this error occurred.

This function allows inspecting the location, in code, of where an error happened. The returned Backtrace contains information about the stack trace of the OS thread of execution of where the error originated from.

Note that not all errors contain a Backtrace. Also note that a Backtrace may actually be empty. For more information consult the Backtrace type itself.

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

if let Err(e) = "xc".parse::<u32>() {
    // Print `e` itself, no need for description().
    eprintln!("Error: {e}");
}
Run
👎 Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

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

Provides type based access to context intended for error reports.

Used in conjunction with Demand::provide_value and Demand::provide_ref to extract references to member variables from dyn Error trait objects.

Example
#![feature(provide_any)]
#![feature(error_generic_member_access)]
use core::fmt;
use core::any::Demand;

#[derive(Debug)]
struct MyBacktrace {
    // ...
}

impl MyBacktrace {
    fn new() -> MyBacktrace {
        // ...
    }
}

#[derive(Debug)]
struct SourceError {
    // ...
}

impl fmt::Display for SourceError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "Example Source Error")
    }
}

impl std::error::Error for SourceError {}

#[derive(Debug)]
struct Error {
    source: SourceError,
    backtrace: MyBacktrace,
}

impl fmt::Display for Error {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "Example Error")
    }
}

impl std::error::Error for Error {
    fn provide<'a>(&'a self, req: &mut Demand<'a>) {
        req
            .provide_ref::<MyBacktrace>(&self.backtrace)
            .provide_ref::<dyn std::error::Error + 'static>(&self.source);
    }
}

fn main() {
    let backtrace = MyBacktrace::new();
    let source = SourceError {};
    let error = Error { source, backtrace };
    let dyn_error = &error as &dyn std::error::Error;
    let backtrace_ref = dyn_error.request_ref::<MyBacktrace>().unwrap();

    assert!(core::ptr::eq(&error.backtrace, backtrace_ref));
}
Run

Implementations

Returns true if the inner type is the same as T.

Returns some reference to the inner value if it is of type T, or None if it isn’t.

Returns some mutable reference to the inner value if it is of type T, or None if it isn’t.

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

Request a reference of type T as context about this error.

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

Request a value of type T as context about this error.

Forwards to the method defined on the type dyn Error.

Forwards to the method defined on the type dyn Error.

Forwards to the method defined on the type dyn Error.

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

Request a reference of type T as context about this error.

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

Request a value of type T as context about this error.

Forwards to the method defined on the type dyn Error.

Forwards to the method defined on the type dyn Error.

Forwards to the method defined on the type dyn Error.

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

Request a reference of type T as context about this error.

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

Request a value of type T as context about this error.

Attempts to downcast the box to a concrete type.

🔬 This is a nightly-only experimental API. (error_iter #58520)

Returns an iterator starting with the current error and continuing with recursively calling Error::source.

If you want to omit the current error and only use its sources, use skip(1).

Examples
#![feature(error_iter)]
use std::error::Error;
use std::fmt;

#[derive(Debug)]
struct A;

#[derive(Debug)]
struct B(Option<Box<dyn Error + 'static>>);

impl fmt::Display for A {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "A")
    }
}

impl fmt::Display for B {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "B")
    }
}

impl Error for A {}

impl Error for B {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        self.0.as_ref().map(|e| e.as_ref())
    }
}

let b = B(Some(Box::new(A)));

// let err : Box<Error> = b.into(); // or
let err = &b as &(dyn Error);

let mut iter = err.chain();

assert_eq!("B".to_string(), iter.next().unwrap().to_string());
assert_eq!("A".to_string(), iter.next().unwrap().to_string());
assert!(iter.next().is_none());
assert!(iter.next().is_none());
Run

Attempts to downcast the box to a concrete type.

Attempts to downcast the box to a concrete type.

Trait Implementations

Converts a str into a box of dyn Error + Send + Sync.

Examples
use std::error::Error;
use std::mem;

let a_str_error = "a str error";
let a_boxed_error = Box::<dyn Error + Send + Sync>::from(a_str_error);
assert!(
    mem::size_of::<Box<dyn Error + Send + Sync>>() == mem::size_of_val(&a_boxed_error))
Run

Converts a str into a box of dyn Error.

Examples
use std::error::Error;
use std::mem;

let a_str_error = "a str error";
let a_boxed_error = Box::<dyn Error>::from(a_str_error);
assert!(mem::size_of::<Box<dyn Error>>() == mem::size_of_val(&a_boxed_error))
Run

Converts a Cow into a box of dyn Error.

Examples
use std::error::Error;
use std::mem;
use std::borrow::Cow;

let a_cow_str_error = Cow::from("a str error");
let a_boxed_error = Box::<dyn Error>::from(a_cow_str_error);
assert!(mem::size_of::<Box<dyn Error>>() == mem::size_of_val(&a_boxed_error))
Run

Converts a Cow into a box of dyn Error + Send + Sync.

Examples
use std::error::Error;
use std::mem;
use std::borrow::Cow;

let a_cow_str_error = Cow::from("a str error");
let a_boxed_error = Box::<dyn Error + Send + Sync>::from(a_cow_str_error);
assert!(
    mem::size_of::<Box<dyn Error + Send + Sync>>() == mem::size_of_val(&a_boxed_error))
Run

Converts a type of Error into a box of dyn Error.

Examples
use std::error::Error;
use std::fmt;
use std::mem;

#[derive(Debug)]
struct AnError;

impl fmt::Display for AnError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "An error")
    }
}

impl Error for AnError {}

let an_error = AnError;
assert!(0 == mem::size_of_val(&an_error));
let a_boxed_error = Box::<dyn Error>::from(an_error);
assert!(mem::size_of::<Box<dyn Error>>() == mem::size_of_val(&a_boxed_error))
Run

Converts a type of Error + Send + Sync into a box of dyn Error + Send + Sync.

Examples
use std::error::Error;
use std::fmt;
use std::mem;

#[derive(Debug)]
struct AnError;

impl fmt::Display for AnError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "An error")
    }
}

impl Error for AnError {}

unsafe impl Send for AnError {}

unsafe impl Sync for AnError {}

let an_error = AnError;
assert!(0 == mem::size_of_val(&an_error));
let a_boxed_error = Box::<dyn Error + Send + Sync>::from(an_error);
assert!(
    mem::size_of::<Box<dyn Error + Send + Sync>>() == mem::size_of_val(&a_boxed_error))
Run

Converts a String into a box of dyn Error + Send + Sync.

Examples
use std::error::Error;
use std::mem;

let a_string_error = "a string error".to_string();
let a_boxed_error = Box::<dyn Error + Send + Sync>::from(a_string_error);
assert!(
    mem::size_of::<Box<dyn Error + Send + Sync>>() == mem::size_of_val(&a_boxed_error))
Run

Converts a String into a box of dyn Error.

Examples
use std::error::Error;
use std::mem;

let a_string_error = "a string error".to_string();
let a_boxed_error = Box::<dyn Error>::from(a_string_error);
assert!(mem::size_of::<Box<dyn Error>>() == mem::size_of_val(&a_boxed_error))
Run
🔬 This is a nightly-only experimental API. (provide_any #96024)

Data providers should implement this method to provide all values they are able to provide by using demand. Read more

Implementors