Trait ErrorExt

pub trait ErrorExt: Sealed + Sized {
    // Required methods
    fn context<M: Display>(self, msg: M) -> Context<M, Self>;
    fn chain(&self) -> Chain<'_> 
       where Self: 'static;

    // Provided methods
    fn find_source<T: Error + 'static>(&self) -> Option<&T>
       where Self: 'static { ... }
    fn display<S: Display>(&self, separator: S) -> DisplayChain<'_, S>
       where Self: 'static { ... }
}

Extension trait for the Error trait.

This adds additional methods to all the Error types. See the crate documentation for examples and general principles.

Note that usually this trait is not imported directly, but through the prelude.

Required Methods

fn context<M: Display>(self, msg: M) -> Context<M, Self>

Wraps the error into another layer of context.

The produced error will have one more layer. The outer layer will have the provided message as its Display implementation.

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

where Self: 'static,

Iterates over all the layers of the error.

The first entry will be the outer layer (self), the last one the lowest-level/innermost source. Therefore this iterator is never empty. It iterates by reference.

Provided Methods

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

where Self: 'static,

Looks for an outermost error of the given type.

This is combination of iteration and downcasting of the errors. The returned value is reference to the outermost error layer that matches given type, as the given type.

The type of the context layers is often very uninteresting, but the code might want to find some specific error in there. This allows skipping the unknown number of human-readable „comments“ and get to the facts. Note that it doesn’t have to be the lowest-level one ‒ even properly typed errors can have their sources.

fn display<S: Display>(&self, separator: S) -> DisplayChain<'_, S>

where Self: 'static,

Returns a Display representation of the whole chain of errors.

This can be used to output the whole chain (as opposed to just outputting the error directly). The layers are separated by the provided separator.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<E: Error> ErrorExt for E