Trait std::error::Error

1.0.0 · source ·
pub trait Error: Debug + Display {
    // Provided methods
    fn source(&self) -> Option<&(dyn Error + 'static)> { ... }
    fn description(&self) -> &str { ... }
    fn cause(&self) -> Option<&dyn Error> { ... }
    fn provide<'a>(&'a self, request: &mut Request<'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 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.

Provided Methods§

1.30.0 · source

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

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
source

fn description(&self) -> &str

👎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
source

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

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

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

🔬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 Request::provide_value and Request::provide_ref to extract references to member variables from dyn Error trait objects.

§Example
#![feature(error_generic_member_access)]
#![feature(error_in_core)]
use core::fmt;
use core::error::{request_ref, Request};

#[derive(Debug)]
enum MyLittleTeaPot {
    Empty,
}

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

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

#[derive(Debug)]
struct Error {
    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, request: &mut Request<'a>) {
        request
            .provide_ref::<MyBacktrace>(&self.backtrace);
    }
}

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

    assert!(core::ptr::eq(&error.backtrace, backtrace_ref));
    assert!(request_ref::<MyLittleTeaPot>(dyn_error).is_none());
}
Run

Implementations§

source§

impl dyn Error

1.3.0 · source

pub fn is<T>(&self) -> bool
where T: Error + 'static,

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

1.3.0 · source

pub fn downcast_ref<T>(&self) -> Option<&T>
where T: Error + 'static,

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

1.3.0 · source

pub fn downcast_mut<T>(&mut self) -> Option<&mut T>
where T: Error + 'static,

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

source§

impl dyn Error + Send

1.3.0 · source

pub fn is<T>(&self) -> bool
where T: Error + 'static,

Forwards to the method defined on the type dyn Error.

1.3.0 · source

pub fn downcast_ref<T>(&self) -> Option<&T>
where T: Error + 'static,

Forwards to the method defined on the type dyn Error.

1.3.0 · source

pub fn downcast_mut<T>(&mut self) -> Option<&mut T>
where T: Error + 'static,

Forwards to the method defined on the type dyn Error.

source§

impl dyn Error + Sync + Send

1.3.0 · source

pub fn is<T>(&self) -> bool
where T: Error + 'static,

Forwards to the method defined on the type dyn Error.

1.3.0 · source

pub fn downcast_ref<T>(&self) -> Option<&T>
where T: Error + 'static,

Forwards to the method defined on the type dyn Error.

1.3.0 · source

pub fn downcast_mut<T>(&mut self) -> Option<&mut T>
where T: Error + 'static,

Forwards to the method defined on the type dyn Error.

source§

impl dyn Error

source

pub fn sources(&self) -> Source<'_>

🔬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.sources();

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
source§

impl dyn Error + Send

1.3.0 · source

pub fn downcast<T>( self: Box<dyn Error + Send> ) -> Result<Box<T>, Box<dyn Error + Send>>
where T: Error + 'static,

Attempts to downcast the box to a concrete type.

source§

impl dyn Error

1.3.0 · source

pub fn downcast<T>(self: Box<dyn Error>) -> Result<Box<T>, Box<dyn Error>>
where T: Error + 'static,

Attempts to downcast the box to a concrete type.

source§

impl dyn Error + Sync + Send

1.3.0 · source

pub fn downcast<T>( self: Box<dyn Error + Sync + Send> ) -> Result<Box<T>, Box<dyn Error + Sync + Send>>
where T: Error + 'static,

Attempts to downcast the box to a concrete type.

Trait Implementations§

1.6.0 · source§

impl<'a> From<&str> for Box<dyn Error + 'a>

source§

fn from(err: &str) -> Box<dyn Error + 'a>

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
source§

impl<'a> From<&str> for Box<dyn Error + Sync + Send + 'a>

source§

fn from(err: &str) -> Box<dyn Error + Sync + Send + 'a>

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
1.22.0 · source§

impl<'a, 'b> From<Cow<'b, str>> for Box<dyn Error + 'a>

source§

fn from(err: Cow<'b, str>) -> Box<dyn Error + 'a>

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
1.22.0 · source§

impl<'a, 'b> From<Cow<'b, str>> for Box<dyn Error + Sync + Send + 'a>

source§

fn from(err: Cow<'b, str>) -> Box<dyn Error + Sync + Send + 'a>

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
source§

impl<'a, E> From<E> for Box<dyn Error + 'a>
where E: Error + 'a,

source§

fn from(err: E) -> Box<dyn Error + 'a>

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
source§

impl<'a, E> From<E> for Box<dyn Error + Sync + Send + 'a>
where E: Error + Send + Sync + 'a,

source§

fn from(err: E) -> Box<dyn Error + Sync + Send + 'a>

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
1.6.0 · source§

impl<'a> From<String> for Box<dyn Error + 'a>

source§

fn from(str_err: String) -> Box<dyn Error + 'a>

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
source§

impl<'a> From<String> for Box<dyn Error + Sync + Send + 'a>

source§

fn from(err: String) -> Box<dyn Error + Sync + Send + 'a>

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

Implementors§

source§

impl !Error for &str

1.8.0 · source§

impl Error for Infallible

source§

impl Error for VarError

1.15.0 · source§

impl Error for RecvTimeoutError

source§

impl Error for TryRecvError

source§

impl Error for !

source§

impl Error for AllocError

1.28.0 · source§

impl Error for LayoutError

1.34.0 · source§

impl Error for TryFromSliceError

1.13.0 · source§

impl Error for BorrowError

1.13.0 · source§

impl Error for BorrowMutError

1.34.0 · source§

impl Error for CharTryFromError

1.9.0 · source§

impl Error for DecodeUtf16Error

1.20.0 · source§

impl Error for ParseCharError

1.59.0 · source§

impl Error for TryFromCharError

source§

impl Error for UnorderedKeyError

1.57.0 · source§

impl Error for TryReserveError

source§

impl Error for JoinPathsError

1.69.0 · source§

impl Error for FromBytesUntilNulError

1.17.0 · source§

impl Error for FromBytesWithNulError

1.58.0 · source§

impl Error for FromVecWithNulError

1.7.0 · source§

impl Error for IntoStringError

source§

impl Error for NulError

1.11.0 · source§

impl Error for std::fmt::Error

source§

impl Error for std::io::Error

1.56.0 · source§

impl Error for WriterPanicked

1.4.0 · source§

impl Error for AddrParseError

source§

impl Error for ParseFloatError

source§

impl Error for ParseIntError

1.34.0 · source§

impl Error for TryFromIntError

1.63.0 · source§

impl Error for InvalidHandleError

Available on Windows only.
1.63.0 · source§

impl Error for NullHandleError

Available on Windows only.
1.7.0 · source§

impl Error for StripPrefixError

source§

impl Error for ExitStatusError

source§

impl Error for ParseBoolError

source§

impl Error for Utf8Error

source§

impl Error for FromUtf8Error

source§

impl Error for FromUtf16Error

source§

impl Error for RecvError

1.26.0 · source§

impl Error for AccessError

1.8.0 · source§

impl Error for SystemTimeError

1.66.0 · source§

impl Error for TryFromFloatSecsError

source§

impl<'a, K, V> Error for std::collections::btree_map::OccupiedError<'a, K, V>
where K: Debug + Ord, V: Debug,

source§

impl<'a, K: Debug, V: Debug> Error for std::collections::hash_map::OccupiedError<'a, K, V>

1.51.0 · source§

impl<'a, T> Error for &'a T
where T: Error + ?Sized,

source§

impl<T> Error for TryLockError<T>

source§

impl<T> Error for TrySendError<T>

1.8.0 · source§

impl<T> Error for Box<T>
where T: Error,

source§

impl<T> Error for ThinBox<T>
where T: Error + ?Sized,

source§

impl<T> Error for SendError<T>

1.52.0 · source§

impl<T> Error for Arc<T>
where T: Error + ?Sized,

source§

impl<T> Error for PoisonError<T>

source§

impl<W: Send + Debug> Error for IntoInnerError<W>

source§

impl<const N: usize> Error for GetManyMutError<N>