Struct DynError

pub struct DynError { /* private fields */ }

Untyped counterpart to Error.

This struct functions mostly identical to Error though its contained error code can be of any ErrorCategory and does not depend on a type parameter. To enable this, this struct in addition to an ErrorData value also contains an ErrorCodeFormatter function pointer belonging to the ErrorCategory of the most recent error.

All the limitation to error chaining outlined in Error’s documentation also apply to DynError. But because the error category type of this error is not known, whether or not it is possible to chain a DynError using chain() or chain_err() with an different error_code cannot be checked at compile time. So instead of a compile error it will cause a panic if unlinked error categories are chained.

#[derive(Clone, Copy, ErrorCategory)]
#[repr(u8)]
enum FooError {
    Err
}

#[derive(Clone, Copy, ErrorCategory)]
#[error_category(links(FooError))]
#[repr(u8)]
enum BarError {
    Err
}

fn cause_dyn_error() -> DynError {
    (FooError::Err).into()
}

// Chain example
fn do_chain() -> DynError {
    cause_dyn_error().chain(BarError::Err).into()
}

This will panic:

#[derive(Clone, Copy, ErrorCategory)]
#[repr(u8)]
enum FooError {
    Err
}

#[derive(Clone, Copy, ErrorCategory)]
#[repr(u8)]
enum BarError {
    Err
}

fn cause_dyn_error() -> DynError {
    (FooError::Err).into()
}

fn do_chain() -> DynError {
    cause_dyn_error().chain(BarError::Err).into()
}

Note also the .into() after chaining. This is required because chaining results in an Error<BarError> value being returned. This is also true for chain_err().

fn cause_dyn_error_result() -> Result<(), DynError> {
    Err((FooError::Err).into())
}

fn do_chain() -> Result<(), DynError> {
    cause_dyn_error_result().chain_err(BarError::Err)?;
    Ok(())
}

Here we use the property of the ? operator that automatically converts the Error<BarError> to a DynError using .into(). This works because DynError implements the From trait for any Error<T>.

The following would not work and won’t compile:

fn do_chain() -> Result<(), DynError> {
    cause_dyn_error_result().chain_err(BarError::Err)
}

Implementations

impl DynError

pub fn new<C: ErrorCategory>(error_code: C) -> DynError

Create a DynError from an error_code belonging to error category C.

pub fn from_raw_parts( error_data: ErrorData, category_formatter: ErrorCodeFormatter, ) -> DynError

Create a DynError from its raw parts.

pub fn into_raw_parts(self) -> (ErrorData, ErrorCodeFormatter)

Turn this dynamic error into its raw parts.

pub fn code(&self) -> ErrorCode

Get the error code of the most recent error.

pub fn chain_len(&self) -> usize

Get the length of the error chain.

pub const fn chain_capacity(&self) -> usize

Get the capacity of the error chain.

Always returns ERROR_CHAIN_LEN.

pub fn category_handle(&self) -> ErrorCategoryHandle

Get the ErrorCategoryHandle of the most recent error.

pub fn formatter(&self) -> ErrorCodeFormatter

Get the ErrorCodeFormatter function of the most recent error.

pub fn is<C: ErrorCategory>(&self) -> bool

Return true if the most recent error code belongs to the error category C.

pub fn try_into<C: ErrorCategory>(self) -> Result<Error<C>, Self>

Try to convert this untyped dynamic error into a statically typed error.

Succeeds and returns the equivalent Error of this DynError if self.is::<C>() returns true, otherwise returns an Err containing the original DynError.

pub fn caused_by<T: ErrorCategory>(&self, error_code: T) -> bool

Query if this error was caused by error_code which belongs to the error category T.

pub fn code_of_category<T: ErrorCategory>(&self) -> Option<T>

Query the error code contained in this error that belongs to the (error category)ErrorCategory T. Return None if this error was not caused by the specified error category.

pub fn iter(&self) -> ErrorIter

Create an iterator that iterates over all error codes that caused this error.

pub fn try_chain<C: ErrorCategory>( self, error_code: C, ) -> Result<Error<C>, Self>

Try to chain this dynamically typed DynError with error_code of error category C.

A call to this function only succeeds if the slice of ErrorCodeFormatters returned by C::chainable_category_formatters() contains self.formatter().

Note that this function has time complexity O(n) where n is the length of the slice returned by C::chainable_category_formatters().

Trait Implementations

impl<O: ErrorCategory> ChainError<O, DynError> for DynError

fn chain(self, error_code: O) -> Error<O>

Chain a DynError with any error code of a linked ErrorCategory.

Note that this function has complexity O(n) where n is the length of the slice returned by O::chainable_category_formatters().

Panics

A call to this function panics if the slice of ErrorCodeFormatters returned by O::chainable_category_formatters() does not contain self.formatter().

impl Clone for DynError

fn clone(&self) -> DynError

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DynError

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

Debug format this error and its chain.

Error message example:

ControlTaskError(0): init failed
- ICM20689Error(0): init failed
- SpiError(0): bus error

impl<C: ErrorCategory> From<C> for DynError

fn from(error: C) -> Self

Converts to this type from the input type.

impl<C: ErrorCategory> From<Error<C>> for DynError

fn from(error: Error<C>) -> Self

Converts to this type from the input type.

impl PartialEq for DynError

fn eq(&self, other: &DynError) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for DynError