Trait std::error::Error

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> { ... }
}

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");

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

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 {
    side: 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.side)
    }
}

#[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 { side: SuperErrorSideKick })
}

fn main() {
    match get_super_error() {
        Err(e) => {
            println!("Error: {}", e);
            println!("Caused by: {}", e.source().unwrap());
        }
        _ => println!("No error"),
    }
}

fn backtrace(&self) -> Option<&Backtrace>

🔬 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.

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);
}

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

👎 Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

Loading content...

Implementations

impl dyn Error + 'static

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

Returns true if the boxed type is the same as T

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

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

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

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

impl dyn Error + Send + 'static

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

Forwards to the method defined on the type dyn Error.

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

Forwards to the method defined on the type dyn Error.

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

Forwards to the method defined on the type dyn Error.

impl dyn Error + Send + Sync + 'static

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

Forwards to the method defined on the type dyn Error.

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

Forwards to the method defined on the type dyn Error.

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

Forwards to the method defined on the type dyn Error.

impl dyn Error

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

Attempts to downcast the box to a concrete type.

pub fn chain(&self) -> Chain<'_>

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

impl dyn Error + Send

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

Attempts to downcast the box to a concrete type.

impl dyn Error + Send + Sync

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

Attempts to downcast the box to a concrete type.

Implementors

impl Error for TryReserveError

impl Error for Infallible

fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

impl Error for VarError

fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

impl Error for RecvTimeoutError

fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

impl Error for TryRecvError

fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

impl Error for !

impl Error for AllocError

impl Error for LayoutError

impl Error for TryFromSliceError

fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

impl Error for BorrowError

fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

impl Error for BorrowMutError

fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

impl Error for CharTryFromError

fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

impl Error for DecodeUtf16Error

fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

impl Error for ParseCharError

fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

impl Error for JoinPathsError

fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

impl Error for FromBytesWithNulError

fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

impl Error for FromVecWithNulError

impl Error for IntoStringError

fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

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

impl Error for NulError

fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

impl Error for std::fmt::Error

fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

impl Error for std::io::Error

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 source(&self) -> Option<&(dyn Error + 'static)>

impl Error for AddrParseError

fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

impl Error for ParseFloatError

fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

impl Error for ParseIntError

fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

impl Error for TryFromIntError

fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

impl Error for StripPrefixError

fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

impl Error for ParseBoolError

fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

impl Error for Utf8Error

fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

impl Error for FromUtf8Error

fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

impl Error for FromUtf16Error

fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

impl Error for RecvError

fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

impl Error for AccessError

impl Error for SystemTimeError

fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

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

fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

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

fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

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

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 source(&self) -> Option<&(dyn Error + 'static)>

fn backtrace(&self) -> Option<&Backtrace>

🔬 This is a nightly-only experimental API. (backtrace #53487)

impl<T> Error for TryLockError<T>

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

impl<T> Error for PoisonError<T>

fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

impl<T: Send> Error for TrySendError<T>

fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

impl<T: Send> Error for SendError<T>

fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

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

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 source(&self) -> Option<&(dyn Error + 'static)>

fn backtrace(&self) -> Option<&Backtrace>

🔬 This is a nightly-only experimental API. (backtrace #53487)

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

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 source(&self) -> Option<&(dyn Error + 'static)>

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

fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

Loading content...