1.0.0[][src]Trait std::error::Error

pub trait Error: Debug + Display {
    fn description(&self) -> &str { ... }
fn cause(&self) -> Option<&dyn Error> { ... }
fn source(&self) -> Option<&(dyn Error + 'static)> { ... }
fn backtrace(&self) -> Option<&Backtrace> { ... } }

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, and may provide cause chain information:

The source method 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 access to that error via the source method. 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 description(&self) -> &str

This method is soft-deprecated.

Although using it won’t cause compilation warning, new code should use Display instead and new impls can omit it.

To obtain error description as a string, use to_string().

Examples

match "xc".parse::<u32>() {
    Err(e) => {
        // Print `e` itself, not `e.description()`.
        println!("Error: {}", e);
    }
    _ => println!("No error"),
}Run

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

Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

The lower-level cause 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 description(&self) -> &str {
        "I'm the superhero of errors"
    }

    fn cause(&self) -> Option<&dyn Error> {
        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 description(&self) -> &str {
        "I'm SuperError side kick"
    }
}

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

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

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

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 description(&self) -> &str {
        "I'm the superhero of errors"
    }

    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 description(&self) -> &str {
        "I'm SuperError side kick"
    }
}

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

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

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

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

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

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.

Loading content...

Methods

impl dyn Error + 'static[src]

pub fn is<T: Error + 'static>(&self) -> bool1.3.0[src]

Returns true if the boxed type is the same as T

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

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>1.3.0[src]

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[src]

pub fn is<T: Error + 'static>(&self) -> bool1.3.0[src]

Forwards to the method defined on the type dyn Error.

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

Forwards to the method defined on the type dyn Error.

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

Forwards to the method defined on the type dyn Error.

impl dyn Error + Send + Sync + 'static[src]

pub fn is<T: Error + 'static>(&self) -> bool1.3.0[src]

Forwards to the method defined on the type dyn Error.

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

Forwards to the method defined on the type dyn Error.

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

Forwards to the method defined on the type dyn Error.

impl dyn Error[src]

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

Attempts to downcast the box to a concrete type.

Important traits for ErrorIter<'a>
pub fn iter_chain(&self) -> ErrorIter[src]

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

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

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

Important traits for ErrorIter<'a>
pub fn iter_sources(&self) -> ErrorIter[src]

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

Returns an iterator starting with the source of this error and continuing with recursively calling source.

Examples

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

#[derive(Debug)]
struct A;

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

#[derive(Debug)]
struct C(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 fmt::Display for C {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "C")
    }
}

impl Error for A {}

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

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

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

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

let mut iter = err.iter_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

impl dyn Error + Send[src]

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

Attempts to downcast the box to a concrete type.

impl dyn Error + Send + Sync[src]

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

Attempts to downcast the box to a concrete type.

Implementors

impl Error for VarError[src]

impl Error for RecvTimeoutError[src]

impl Error for TryRecvError[src]

impl Error for ![src]

impl Error for AllocErr[src]

impl Error for CannotReallocInPlace[src]

impl Error for LayoutErr[src]

impl Error for TryFromSliceError[src]

impl Error for BorrowError[src]

impl Error for BorrowMutError[src]

impl Error for CharTryFromError[src]

impl Error for DecodeUtf16Error[src]

impl Error for ParseCharError[src]

impl Error for JoinPathsError[src]

impl Error for FromBytesWithNulError[src]

impl Error for IntoStringError[src]

impl Error for NulError[src]

impl Error for std::fmt::Error[src]

impl Error for std::io::Error[src]

impl Error for AddrParseError[src]

impl Error for ParseFloatError[src]

impl Error for ParseIntError[src]

impl Error for TryFromIntError[src]

impl Error for StripPrefixError[src]

impl Error for ParseBoolError[src]

impl Error for Utf8Error[src]

impl Error for FromUtf16Error[src]

impl Error for FromUtf8Error[src]

impl Error for RecvError[src]

impl Error for AccessError[src]

impl Error for SystemTimeError[src]

impl Error for ParseError[src]

impl<T> Error for TryLockError<T>[src]

impl<T> Error for PoisonError<T>[src]

impl<T: Error> Error for Box<T>[src]

impl<T: Send> Error for TrySendError<T>[src]

impl<T: Send> Error for SendError<T>[src]

impl<W: Send + Debug> Error for IntoInnerError<W>[src]

Loading content...