Struct embedded_error_chain::ErrorData

#[repr(transparent)]pub struct ErrorData { /* fields omitted */ }

The entire data of the error and its error code chain.

This is a wrapper over a bit-packed u32 value that contains five 4-bit wide ErrorCodes and four 3-bit wide ErrorCodeFormatter indices.

The bit layout of the underlying u32 value is a follows:

• Bits b0..b20 contain 5 error codes, each error code is 4 bits.
  • b0..b4: the error code of the current error (returned by code())
  • b4..b8: chained error code 0
  • b8..b12: chained error code 1
  • b12..b16: chained error code 2
  • b16..b20: chained error code 3
• Bits b20..b32 contain 4 formatter indices, each index has 3 bits.
  • b20..b23: formatter index + 1 of chained error 0 (0 means not present) (returned by first_formatter_index())
  • b23..b26: formatter index + 1 of chained error 1 (0 means not present)
  • b26..b29: formatter index + 1 of chained error 2 (0 means not present)
  • b29..b32: formatter index + 1 of chained error 3 (0 means not present)

The first error code represents the most recent or current error. The next four error codes with the formatter indices represent the error chain which can be empty. The error chain (as described in the documentation of Error) is a singly linked list. As much of the data used for error reporting is constant or static, so that no dynamic allocation is needed, to make runtime memory usage as small as possible and to make it cheap to copy an error value around. This is also the case with the error chain.

Every ErrorCode value belongs to a type that implements the trait ErrorCategory. Using this trait it is possible to print a custom name and additional information for every ErrorCode value. Only the ErrorCategory of the most recent error code has to be known, all other error categories can then be retrieved by iterating over the linked list. The ErrorCategory is also needed for the linked list to be possible.

Every formatter index in the chain represents the ErrorCodeFormatter function of the error category and error code. A formatter function is retrieved by calling the formatter function of the previous error code, and passing it the index of the next formatter function. The called formatter function gets the next formatter function from from the slice returned by ErrorCategory::chainable_category_formatters() using the next formatter index. This is only possible if the ErrorCategory associated with the called formatter function is linked to the ErrorCategory of the next error code in the chain.

An error category A is linked to an error category B if at least one of the A::L1 to A::L5 associated types is B and the nth element (where n is the digit of the A::Ln associated type used) of the slice returned by A::chainable_category_formatters() is the ErrorCodeFormatter function for B.

Implementations

impl ErrorData

pub const fn new(error_code: ErrorCode) -> ErrorData

Create new ErrorData that contains the supplied error_code and has an empty chain.

pub fn set_code(&mut self, code: ErrorCode) -> ErrorCode

Replace the error code with code and return the old one.

Note: That the categories of the new error code and the old must be the same.

pub fn code(&self) -> ErrorCode

Get the most recent error code of the error.

pub fn first_formatter_index(&self) -> Option<u8>

Get the first formatter index in the chain if available.

pub fn chain_len(&self) -> usize

Get the number of chained error codes.

pub fn chain_full(&self) -> bool

Whether the error chain is full.

pub fn push_front(
    &mut self,
    error_code: ErrorCode,
    category_index: u8
) -> Option<(ErrorCode, u8)>

Prepend the current error code to the front of the error chain and set the current error code to error_code.

Returns the back of the error chain before modification if it gets overwritten by this operation (when the chain overflows).

Note: error_code is masked to the first 4 bits and category_index is masked to the first 3 bits.

pub fn chain(&mut self, error_code: ErrorCode, category_index: u8)

Chain this error with a new error specified by error_code.

• error_code: The new error code that is set as the current one.
• category_index: The index of the ErrorCodeFormatter in the slice returned by T::chainable_category_formatters() where T is the error category that the most recent error code before this operation belongs to.

This prepends the current error code to the front of the error chain and sets error_code as the new current error code.

Panics

If the feature panic-on-overflow is enabled and the error chain is already full before this operation, this function will panic. If the feature is not enabled and the error chain is already full, the last error in the chain will be lost.

Trait Implementations

impl Clone for ErrorData

pub fn clone(&self) -> ErrorData

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Copy for ErrorData

impl Eq for ErrorData

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

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

Performs the conversion.

impl PartialEq<ErrorData> for ErrorData

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl StructuralEq for ErrorData

impl StructuralPartialEq for ErrorData