Struct Exn 

pub struct Exn<E = Untyped>
where
    E: Error + Send + Sync + 'static,
{ /* 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> Exn<E>

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

pub fn new(error: E) -> Exn<E>

Available on crate feature mailmap only.

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) -> Exn<E>

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

Available on crate feature mailmap only.

Create a new exception with the given error and children.

pub fn raise<T>(self, err: T) -> Exn<T>

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

Available on crate feature mailmap only.

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

pub fn chain<T>(self, err: impl Into<Exn<T>>) -> Exn<E>

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

Available on crate feature mailmap only.

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 as IntoIterator>::Item: Into<Exn<T>>,

Available on crate feature mailmap only.

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

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

Available on crate feature mailmap only.

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

Available on crate feature mailmap only.

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

pub fn error(&self) -> &E

Available on crate feature mailmap only.

Return the current exception.

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

Available on crate feature mailmap only.

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

Available on crate feature mailmap only.

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

Available on crate feature mailmap only.

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

pub fn into_chain(self) -> ChainedError

Available on crate feature mailmap only.

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

Available on crate feature mailmap only.

Return the underlying exception frame.

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

Available on crate feature mailmap only.

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>(&self) -> Option<&T>

where T: Error + 'static,

Available on crate feature mailmap only.

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> Debug for Exn<E>

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

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

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) -> &<Exn<E> as Deref>::Target

Dereferences the value.

impl<E> Display for Exn<E>

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

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

Formats the value using the given formatter.

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

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

fn from(error: E) -> Exn<E>

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>) -> Box<Frame>

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>) -> Error

Converts to this type from the input type.

impl From<Exn<ValidationError>> for Error

fn from(source: Exn<ValidationError>) -> Error

Converts to this type from the input type.

impl From<Frame> for Exn

fn from(frame: Frame) -> Exn

Converts to this type from the input type.