pub enum DecodeFailure<E> {
#[non_exhaustive] Incomplete {
source: Option<E>,
required_total: NonZeroUsize,
},
#[non_exhaustive] Invalid {
source: E,
consumed: Option<NonZeroUsize>,
},
}Expand description
Failure reported by crate::Codec::decode.
This type separates stream-control failures from codec-domain failures.
Incomplete tells buffered adapters to preserve the
current input tail and request more units. Invalid
carries the codec-specific malformed, non-canonical, or otherwise invalid
input error with a known non-zero consumption length, or with unknown
consumption when set to None.
§Type Parameters
E: Codec-specific invalid-input error type.
§Examples
use core::num::NonZeroUsize;
use qubit_codec::DecodeFailure;
let failure = DecodeFailure::<()>::incomplete(NonZeroUsize::MIN);
assert_eq!(failure.required_total(), Some(NonZeroUsize::MIN));
assert_eq!(failure.invalid_source(), None);Variants§
#[non_exhaustive]Incomplete
The visible input is a valid prefix but not enough to decode a value.
Fields
This variant is marked as non-exhaustive
source: Option<E>Codec-specific context for the incomplete prefix, when available.
Stream drivers may ignore this field while retrying input. Once the stream reaches EOF, adapters can use it to preserve detailed diagnostics instead of reconstructing an error from the length bound alone.
required_total: NonZeroUsizeCurrent non-zero minimum total units required before retrying from the value start.
A later retry may raise this lower bound after the codec sees a longer prefix.
When returned by Codec::decode or Codec::decode_eof, this must
be greater than the number of units currently available from the
value start and no greater than
Codec::MAX_DECODE_UNITS_PER_VALUE. It is a minimum total length
from that start, not an additional-unit count; for example, with
two units available and at least one more needed, report three.
#[non_exhaustive]Invalid
The input is invalid for the codec.
Fields
This variant is marked as non-exhaustive
source: ECodec-specific invalid-input error.
consumed: Option<NonZeroUsize>Invalid units that may be consumed by a non-strict policy, when known.
Implementations§
Source§impl<E> DecodeFailure<E>
impl<E> DecodeFailure<E>
Sourcepub const fn incomplete(required_total: NonZeroUsize) -> Self
pub const fn incomplete(required_total: NonZeroUsize) -> Self
Creates an incomplete-input decode failure.
§Parameters
required_total: Current non-zero minimum total units required before retrying from the value start. A later retry may raise this lower bound. When returned byCodec::decodeorCodec::decode_eof, it must be greater than the units currently available from that start and no greater thanCodec::MAX_DECODE_UNITS_PER_VALUE. It counts total units from the value start, not additional units to append. This constructor has no input or Codec context and cannot validate those conditions; the Codec implementation is responsible for them when returning the failure.
§Returns
Returns an incomplete decode failure.
Sourcepub const fn incomplete_with_source(
source: E,
required_total: NonZeroUsize,
) -> Self
pub const fn incomplete_with_source( source: E, required_total: NonZeroUsize, ) -> Self
Creates an incomplete-input decode failure with codec-specific context.
§Parameters
source: Codec-specific error describing the visible incomplete prefix.required_total: Current non-zero minimum units required before retrying from the value start. When returned byCodec::decodeorCodec::decode_eof, it must be greater than the units currently available from that start and no greater thanCodec::MAX_DECODE_UNITS_PER_VALUE. It counts total units from the value start, not additional units to append. This constructor has no input or Codec context and cannot validate those conditions; the Codec implementation is responsible for them when returning the failure.
§Returns
Returns an incomplete decode failure retaining source for adapters
that need detailed EOF diagnostics.
Sourcepub const fn invalid(source: E, consumed: NonZeroUsize) -> Self
pub const fn invalid(source: E, consumed: NonZeroUsize) -> Self
Sourcepub const fn invalid_unknown(source: E) -> Self
pub const fn invalid_unknown(source: E) -> Self
Sourcepub const fn required_total(&self) -> Option<NonZeroUsize>
pub const fn required_total(&self) -> Option<NonZeroUsize>
Returns the current minimum input length required before retrying an incomplete prefix.
§Returns
Returns Some(required_total) for incomplete failures, where the value
is a lower bound that a later retry may raise, or None for
invalid-input failures.
Sourcepub const fn incomplete_source(&self) -> Option<&E>
pub const fn incomplete_source(&self) -> Option<&E>
Borrows the codec-specific error retained for an incomplete prefix.
§Returns
Returns Some(source) when the codec supplied incomplete-input context,
or None when the failure only carries the retry bound or is invalid.
Sourcepub const fn invalid_source(&self) -> Option<&E>
pub const fn invalid_source(&self) -> Option<&E>
Borrows the codec-specific invalid-input error.
§Returns
Returns Some(source) for invalid-input failures, or None for
incomplete failures.