Struct Error 

pub struct Error<S = Stateless>(/* private fields */)
where
    S: State + ?Sized;

An error type that can carry optional state, source, context, and payload.

Implementations

impl Error

pub fn with_error<E>(err: E) -> Builder<E, Stateless, Immediate<Empty>, Blank>

Starts building an Error from a source error.

pub fn with_state<S>(state: S) -> Builder<Nae, S, Immediate<Empty>, Blank>

where S: State,

Starts building an Error with a typed state.

The state is inlined when no source or payload is attached.

pub fn with_payload<P>( payload: P, ) -> Builder<Nae, Stateless, Immediate<P>, Blank>

where P: Display + Send + Sync + 'static,

Starts building an Error with a payload.

pub fn with_payload_fn<F>(payload_fn: F) -> Builder<Nae, Stateless, F, Blank>

where F: PayloadFn,

Starts building an Error with a lazily evaluated payload.

The closure payload_fn is called only when the error is materialized.

pub fn with_context<L>(_ty: L) -> Builder<Nae, Stateless, Immediate<Empty>, L>

where L: Context,

Starts building an Error with a typed literal context.

For dynamic content, use with_payload instead.

pub fn with_context_ty<L>() -> Builder<Nae, Stateless, Immediate<Empty>, L>

Starts building an Error with a literal context type, inferred at the call site.

pub fn into_parts<P, E>(self) -> (Option<&'static str>, Option<P>, Option<E>)

where E: 'static, P: 'static,

Extracts the context, payload, and source error.

Returns None when the corresponding requested type does not match.

pub fn stateless(self) -> Self

Helper for type inference when the state is not needed.

impl<S> Error<S>

where S: State + ?Sized,

pub fn erase(self) -> impl Error + Send + Sync + 'static

Returns an opaque Error.

pub fn erase_ref(&self) -> &(impl Error + Send + Sync + 'static)

Returns a reference to an opaque Error.

pub fn from_error<E>(err: E) -> Self

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

Creates an Error from any Error.

pub fn from_context<L>(_ty: L) -> Self

where L: Literal,

Creates an Error from a typed literal value.

pub fn from_context_ty<L>() -> Self

where L: Literal,

Creates an Error from a typed literal, inferred at the call site.

pub fn from_payload<P>(payload: P) -> Self

where P: Display + Send + Sync + 'static,

Creates an Error from a payload.

pub fn from_boxed(value: Box<dyn Error + Send + Sync + 'static>) -> Self

Creates an Error from a boxed error.

pub fn has_state(&self) -> bool

Returns true if there is a state stored inside the error.

pub fn try_into_stateless(self) -> Result<Error, Self>

Converts to a stateless error. Returns Err when no extra details remain after dropping the state.

pub fn context(&self) -> Option<&(dyn Display + Send + Sync + 'static)>

Returns a reference to the context, if present.

pub fn payload(&self) -> Option<&(dyn Display + Send + Sync + 'static)>

Returns a reference to the payload, if present.

pub fn has_source_of<E>(&self) -> bool

where E: Error + 'static,

Returns true if the wrapped source error is of type E.

pub fn source(&self) -> Option<&(dyn Error + 'static)>

Returns a reference to the source error, if any.

pub fn downcast_source_ref<E>(&self) -> Option<&E>

where E: Error + 'static,

Attempts to downcast the wrapped source error to E by shared reference.

pub fn downcast_source_mut<E>(&mut self) -> Option<&mut E>

where E: Error + 'static,

Attempts to downcast the wrapped source error to E by mutable reference.

pub fn has_payload_of<P>(&self) -> bool

where P: 'static,

Returns true if the attached payload is of type P.

pub fn downcast_payload_ref<P>(&self) -> Option<&P>

where P: 'static,

Attempts to downcast the payload to P by shared reference.

pub fn downcast_payload_mut<P>(&mut self) -> Option<&mut P>

where P: 'static,

Attempts to downcast the payload to P by mutable reference.

pub fn into_source(self) -> Option<Box<dyn Error + Send + Sync + 'static>>

Consumes self and returns the boxed source error, if any.

pub fn chain(&self) -> impl Iterator<Item = &(dyn Error + 'static)>

Iterates over the source error chain, starting from the immediate source.

pub fn with_phantom_state<S2>(self) -> Error<S2>

where S2: State + ?Sized,

Converts to an error of another state without providing the state value.

pub fn backtrace(&self) -> Option<&Backtrace>

Available on crate feature backtrace only.

Returns the backtrace, if any.

impl<S> Error<S>

where S: State,

pub fn from_state(state: S) -> Self

Creates an Error from a state value.

pub fn state(&self) -> Option<&S>

Returns a reference to the attached state.

pub fn into_parts<P, E>( self, ) -> (Option<S>, Option<&'static str>, Option<P>, Option<E>)

where E: 'static, P: 'static,

Consumes self and returns the state, context, payload, and error.

Returns None when the requested types do not match.

pub fn extract_state(self) -> Result<(S, Vacant<S>), Error>

Attempts to extract the state.

pub fn map_state<F, S2>(self, f: F) -> Error<S2>

where F: FnOnce(S) -> S2, S2: State,

pub fn lift_state<S2>(self) -> Error<S2>

where S2: From<S> + State,

Trait Implementations

impl<S> Debug for Error<S>

where S: State + ?Sized,

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

Formats the value using the given formatter.

impl<S> Deref for Error<S>

where S: State + ?Sized,

type Target = dyn Error + Sync + Send

The resulting type after dereferencing.

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

Dereferences the value.

impl<S> Display for Error<S>

where S: State + ?Sized,

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

Formats the value using the given formatter.

impl<S> ErrorExt for Error<S>

where S: State + ?Sized,

type Result<E> = E

type S = S

fn build_error(self) -> Self::Result<Error<Self::S>>

Materializes the final Error<Self::S>.

fn erase_error(self) -> Self::Result<impl Error + Send + Sync + 'static>

Materializes and then erases the state, returning an opaque impl Error.

impl<E, S, F, L> From<Builder<E, S, F, L>> for Error<S>

where F: PayloadFn, E: Error + Send + Sync + 'static, S: State + ?Sized, L: Context + ?Sized,

fn from(value: Builder<E, S, F, L>) -> Self

Converts to this type from the input type.

impl<E, S, F, L> From<Builder<E, Stateless, F, L>> for Error<S>

where F: PayloadFn, E: Error + Send + Sync + 'static, S: State, L: Context + ?Sized,

fn from(value: Builder<E, Stateless, F, L>) -> Self

Converts to this type from the input type.

impl<S1, S, F, L> From<Builder<Error<S1>, S, F, L>> for Error<S>

where S1: State + ?Sized, F: PayloadFn, S: State + ?Sized, L: Context + ?Sized,

fn from(value: Builder<Error<S1>, S, F, L>) -> Self

Converts to this type from the input type.

impl<S1, S, F, L> From<Builder<Error<S1>, Stateless, F, L>> for Error<S>

where S1: State + ?Sized, F: PayloadFn, S: State, L: Context + ?Sized,

fn from(value: Builder<Error<S1>, Stateless, F, L>) -> Self

Converts to this type from the input type.

impl<E, S> From<E> for Error<S>

where E: Error + Send + Sync + 'static, S: State + ?Sized,

fn from(err: E) -> Self

Converts to this type from the input type.

impl<S> From<Error<S>> for Box<dyn Error + 'static>

where S: State + ?Sized,

fn from(value: Error<S>) -> Self

Converts to this type from the input type.

impl<S> From<Error<S>> for Box<dyn Error + Send + 'static>

where S: State + ?Sized,

fn from(value: Error<S>) -> Self

Converts to this type from the input type.

impl<S> From<Error<S>> for Box<dyn Error + Send + Sync + 'static>

where S: State + ?Sized,

fn from(value: Error<S>) -> Self

Converts to this type from the input type.

impl<S> From<Error<S>> for Box<dyn Error + Sync + 'static>

where S: State + ?Sized,

fn from(value: Error<S>) -> Self

Converts to this type from the input type.

impl<S> From<Error> for Error<S>

where S: State,

fn from(value: Error) -> Self

Converts to this type from the input type.

impl<S1> StateExt for Error<S1>

where S1: State,

type T = ()

type S = S1

type Result<T, E> = E

fn extract_state( self, ) -> Result<Self::Result<Self::T, (Self::S, Vacant<Self::S>)>, Error>

where Self::S: Sized,

Extracts the state if it has been set.

fn map_state<F, S>(self, f: F) -> Self::Result<Self::T, Error<S>>

where F: FnOnce(Self::S) -> S, S: State,

fn lift_state<S>(self) -> Self::Result<Self::T, Error<S>>

where S: State + From<Self::S>, Self: Sized,