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.

Native error sources

Values reached through std::error::Error::source() remain owned by their original errors and are traversed by reference, preserving their concrete types. They aren’t exception frames and therefore have no captured call site of their own.

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.

Its source chain is retained by error and traversed lazily for formatting, downcasting, and conversion. Native sources are not copied into owned Frame values and keep their concrete types.

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

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 explicitly added child frames of this error as untyped Exn.

Native Error::source() values remain owned by their error and aren’t drainable frames. This is useful if one wants to re-organise explicitly raised 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 explicitly created frames in breadth-first order. The first frame is this instance, followed by all explicitly raised children. Native Error::source() values are not frames.

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

Find the first stored error or native source that downcasts to T in breadth-first order.

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 Box<dyn Error + Send + Sync + 'static>

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 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,

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.