Struct Exn 

pub struct Exn<E: Error + Send + Sync + 'static = Untyped> { /* private fields */ }

An exception type that can hold an error tree and the call site.

While an error chain, a list, is automatically created when raise and friends are invoked, one can also use Exn::raise_all to create an error that has multiple causes.

Warning: source() information is stringified and type-erased

All source() values are turned into frames, but lose their type information completely. This is because they are only seen as reference and thus can’t be stored.

Exn == Exn<Untyped>

Exn act’s like Box<dyn std::error::Error + Send + Sync + 'static>, but with the capability to store a tree of errors along with their call sites.

Visualisation

Linearized trees during display make a list of 3 children indistinguishable from 3 errors where each is the child of the other.

Debug

• locations: ✔️
• error display: Display
• tree mode: linearized

Debug + Alternate

• locations: ❌
• error display: Display
• tree mode: linearized

Display

• locations: ❌
• error display: Debug
• tree mode: None

Display + Alternate

• locations: ❌
• error display: Debug
• tree mode: verbatim

Implementations

impl<E: Error + Send + Sync + 'static> Exn<E>

pub fn new(error: E) -> Self

Create a new exception with the given error.

This will automatically walk the source chain of the error and add them as children frames.

See also ErrorExt::raise for a fluent way to convert an error into an Exn instance.

Note that sources of error are degenerated to their string representation and all type information is erased.

pub fn raise_all<T, I>(children: I, err: E) -> Self

where T: Error + Send + Sync + 'static, I: IntoIterator, I::Item: Into<Exn<T>>,

Create a new exception with the given error and children.

pub fn raise<T: Error + Send + Sync + 'static>(self, err: T) -> Exn<T>

Raise a new exception; this will make the current exception a child of the new one.

pub fn chain<T: Error + Send + Sync + 'static>( self, err: impl Into<Exn<T>>, ) -> Exn<E>

Use the current exception as the head of a chain, adding err to its children.

pub fn chain_all<T, I>(self, errors: I) -> Exn<E>

where T: Error + Send + Sync + 'static, I: IntoIterator, I::Item: Into<Exn<T>>,

Use the current exception the head of a chain, adding errors to its children.

pub fn drain_children(&mut self) -> impl Iterator<Item = Exn> + '_

Drain all sources of this error as untyped Exn.

This is useful if one wants to re-organise errors, and the error layout is well known.

pub fn erased(self) -> Exn

Erase the type of this instance and turn it into a bare Exn.

pub fn error(&self) -> &E

Return the current exception.

pub fn into_box(self) -> Box<E>

Discard all error context and return the underlying error in a Box.

This is useful to retain the allocation, as internally it’s also stored in a box, when comparing it to Self::into_inner().

pub fn into_inner(self) -> E

Discard all error context and return the underlying error.

This may be needed to obtain something that once again implements Error. Note that this destroys the internal Box and moves the value back onto the stack.

pub fn into_error(self) -> Error

Turn ourselves into a top-level Error that implements std::error::Error.

pub fn into_chain(self) -> ChainedError

Convert this error tree into a chain of errors, breadth first, which flattens the tree but retains all type dynamic type information.

This is useful for inter-op with anyhow.

pub fn frame(&self) -> &Frame

Return the underlying exception frame.

pub fn iter(&self) -> impl Iterator<Item = &Frame>

Iterate over all frames in breadth-first order. The first frame is this instance, followed by all of its children.

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

Iterate over all frames and find one that downcasts into error of type T. Note that the search includes this instance as well.

Trait Implementations

impl<E: Error + Send + Sync + 'static> Debug for Exn<E>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<E> Deref for Exn<E>

where E: Error + Send + Sync + 'static,

type Target = E

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<E: Error + Send + Sync + 'static> Display for Exn<E>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<E: Error + Send + Sync + 'static> From<E> for Exn<E>

fn from(error: E) -> Self

Converts to this type from the input type.

impl<E> From<Exn<E>> for Box<Frame>

where E: Error + Send + Sync + 'static,

fn from(err: Exn<E>) -> Self

Converts to this type from the input type.

impl<E> From<Exn<E>> for ChainedError

where E: Error + Send + Sync + 'static,

fn from(err: Exn<E>) -> Self

Converts to this type from the input type.

impl<E> From<Exn<E>> for Error

where E: Error + Send + Sync + 'static,

Available on crate feature anyhow only.

fn from(err: Exn<E>) -> Self

Converts to this type from the input type.

impl<E> From<Exn<E>> for Error

where E: Error + Send + Sync + 'static,

fn from(err: Exn<E>) -> Self

Converts to this type from the input type.

impl<E> From<Exn<E>> for Frame

where E: Error + Send + Sync + 'static,

fn from(err: Exn<E>) -> Self

Converts to this type from the input type.

impl From<Frame> for Exn

fn from(frame: Frame) -> Self

Converts to this type from the input type.