Struct CodecError 

pub struct CodecError {
    pub kind: CodecErrorKind,
    /* private fields */
}

An error produced while reading or writing protocol data.

The error records the originating CodecKind, the CodecOperation, the progress within that codec, and optional enclosing codec contexts. I/O and parser errors are retained as an error source.

Error enums are non-exhaustive, so downstream matches must include a wildcard arm.

Example

use mcproto_codec::{
    error::{CodecErrorKind, CodecKind, CodecOperation},
    varint::VarIntRead,
};

let mut input = [0x80].as_slice();
let error = input
    .read_varint()
    .unwrap_err()
    .with_context(CodecKind::String);

assert_eq!(error.codec(), CodecKind::VarInt);
assert_eq!(error.operation(), CodecOperation::Read);
assert_eq!(error.bytes_processed(), 1);
assert_eq!(error.contexts(), &[CodecKind::String]);

match error.kind() {
    CodecErrorKind::UnexpectedEof => {}
    _ => panic!("unexpected error: {error}"),
}

Fields

kind: CodecErrorKind

The error classification.

This field and kind expose the same value. The accessor is convenient when working through a shared reference.

Implementations

impl CodecError

pub const fn kind(&self) -> CodecErrorKind

Returns the error classification.

pub const fn codec(&self) -> CodecKind

Returns the codec that originally reported the error.

pub fn context(&self) -> Option<CodecKind>

Returns the outermost enclosing codec context, if one was added.

This is the last element of contexts, not the originating codec returned by codec.

pub fn contexts(&self) -> &[CodecKind]

Returns all enclosing codec contexts, ordered from nearest to outermost.

The originating codec is not included. Each call to with_context appends one element.

pub const fn operation(&self) -> CodecOperation

Returns the operation being performed when the error occurred.

pub const fn bytes_processed(&self) -> usize

Returns the byte progress reported by the originating codec.

Built-in codecs count bytes from the start of their encoded value. Bytes successfully read or written before an I/O failure are included. A byte that was read and then found to be invalid is also included. For a length-prefixed value, the originating codec determines whether its prefix is part of the count.

Adding an outer context does not translate this value into an offset within the enclosing codec.

pub fn io_error(&self) -> Option<&Error>

Returns the underlying io::Error, if the source is an I/O error.

Invalid NBT or JSON errors may have a non-I/O source; access those through Error::source instead.

pub fn with_context(self, context: CodecKind) -> Self

Adds an enclosing codec to the error’s context chain.

Contexts should be added as the error propagates outward. Repeated calls therefore order contexts from nearest to outermost, and context returns the most recently added context.

pub fn from_read_error( codec: CodecKind, bytes_processed: usize, source: Error, ) -> Self

Creates an error from an I/O failure that occurred while reading.

io::ErrorKind::UnexpectedEof maps to CodecErrorKind::UnexpectedEof; every other error kind maps to CodecErrorKind::Io. The source error is retained.

bytes_processed is the number of bytes read before source occurred.

pub fn from_write_error( codec: CodecKind, bytes_processed: usize, source: Error, ) -> Self

Creates an error from an I/O failure that occurred while writing.

All write errors map to CodecErrorKind::Io, and the source error is retained. bytes_processed is the number of bytes written before source occurred.

pub const fn invalid_encoding( codec: CodecKind, bytes_processed: usize, reason: InvalidEncodingReason, ) -> Self

Creates an invalid encoding error for a read operation.

Use invalid_encoding_for_operation when the operation is not necessarily CodecOperation::Read.

pub const fn invalid_encoding_for_operation( codec: CodecKind, operation: CodecOperation, bytes_processed: usize, reason: InvalidEncodingReason, ) -> Self

Creates an invalid encoding error for the specified operation.

Unlike invalid_encoding, this constructor does not assume that the error occurred while reading.

pub fn invalid_encoding_for_operation_with_source( codec: CodecKind, operation: CodecOperation, bytes_processed: usize, reason: InvalidEncodingReason, source: impl Error + Send + Sync + 'static, ) -> Self

Creates an invalid encoding error with an underlying source error.

operation may be either reading or writing. The supplied error is available through Error::source; if it is an io::Error, it is also available through io_error.

Trait Implementations

impl Debug for CodecError

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

Formats the value using the given formatter.

impl Display for CodecError

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

Formats the value using the given formatter.

impl Error for CodecError

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

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.