std::error::Error - Rust
Description: API documentation for the Rust `Error` trait in crate `std`.
Keywords: rust, rustlang, rust-lang, Error

# 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 `impl`s 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) -> bool`1.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) -> bool`1.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) -> bool`1.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>

### Important traits for ErrorIter<'a>

`impl<'a> Iterator for ErrorIter<'a> type Item = &'a (dyn Error + 'static);`
`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>

### Important traits for ErrorIter<'a>

`impl<'a> Iterator for ErrorIter<'a> type Item = &'a (dyn Error + 'static);`
`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]

#### `fn description(&self) -> &str`[src]

### `impl Error for RecvTimeoutError`[src]

#### `fn description(&self) -> &str`[src]

### `impl Error for TryRecvError`[src]

#### `fn description(&self) -> &str`[src]

### `impl Error for !`[src]

#### `fn description(&self) -> &str`[src]

### `impl Error for AllocErr`[src]

#### `fn description(&self) -> &str`[src]

### `impl Error for CannotReallocInPlace`[src]

#### `fn description(&self) -> &str`[src]

### `impl Error for LayoutErr`[src]

#### `fn description(&self) -> &str`[src]

### `impl Error for TryFromSliceError`[src]

#### `fn description(&self) -> &str`[src]

### `impl Error for BorrowError`[src]

#### `fn description(&self) -> &str`[src]

### `impl Error for BorrowMutError`[src]

#### `fn description(&self) -> &str`[src]

### `impl Error for CharTryFromError`[src]

#### `fn description(&self) -> &str`[src]

### `impl Error for DecodeUtf16Error`[src]

#### `fn description(&self) -> &str`[src]

### `impl Error for ParseCharError`[src]

#### `fn description(&self) -> &str`[src]

### `impl Error for JoinPathsError`[src]

#### `fn description(&self) -> &str`[src]

### `impl Error for FromBytesWithNulError`[src]

#### `fn description(&self) -> &str`[src]

### `impl Error for IntoStringError`[src]

#### `fn description(&self) -> &str`[src]

#### `fn source(&self) -> Option<&(dyn Error + 'static)>`[src]

### `impl Error for NulError`[src]

#### `fn description(&self) -> &str`[src]

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

#### `fn description(&self) -> &str`[src]

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

#### `fn description(&self) -> &str`[src]

#### `fn cause(&self) -> Option<&dyn Error>`[src]

Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

#### `fn source(&self) -> Option<&(dyn Error + 'static)>`[src]

### `impl Error for AddrParseError`[src]

#### `fn description(&self) -> &str`[src]

### `impl Error for ParseFloatError`[src]

#### `fn description(&self) -> &str`[src]

### `impl Error for ParseIntError`[src]

#### `fn description(&self) -> &str`[src]

### `impl Error for TryFromIntError`[src]

#### `fn description(&self) -> &str`[src]

### `impl Error for StripPrefixError`[src]

#### `fn description(&self) -> &str`[src]

### `impl Error for ParseBoolError`[src]

#### `fn description(&self) -> &str`[src]

### `impl Error for Utf8Error`[src]

#### `fn description(&self) -> &str`[src]

### `impl Error for FromUtf16Error`[src]

#### `fn description(&self) -> &str`[src]

### `impl Error for FromUtf8Error`[src]

#### `fn description(&self) -> &str`[src]

### `impl Error for RecvError`[src]

#### `fn description(&self) -> &str`[src]

### `impl Error for AccessError`[src]

### `impl Error for SystemTimeError`[src]

#### `fn description(&self) -> &str`[src]

### `impl Error for ParseError`[src]

#### `fn description(&self) -> &str`[src]

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

#### `fn description(&self) -> &str`[src]

#### `fn cause(&self) -> Option<&dyn Error>`[src]

Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

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

#### `fn description(&self) -> &str`[src]

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

#### `fn description(&self) -> &str`[src]

#### `fn cause(&self) -> Option<&dyn Error>`[src]

Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

#### `fn source(&self) -> Option<&(dyn Error + 'static)>`[src]

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

#### `fn description(&self) -> &str`[src]

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

#### `fn description(&self) -> &str`[src]

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

#### `fn description(&self) -> &str`[src]

Loading content...