Enum TranscodeFailure 

#[non_exhaustive]
pub enum TranscodeFailure {
    InvalidInputIndex {
        index: usize,
        input_len: usize,
    },
    InvalidOutputIndex {
        index: usize,
        output_len: usize,
    },
    InvalidOutputRange {
        output_index: usize,
        range_len: usize,
        output_len: usize,
    },
    InsufficientOutput {
        output_index: usize,
        required: usize,
        available: usize,
    },
    OutputLengthOverflow,
    AllocationFailed,
    IncompleteInput {
        input_index: usize,
        required: usize,
        available: usize,
    },
    InvalidProgress {
        source: TranscodeContractError,
    },
    TrailingInput {
        consumed: usize,
        remaining: usize,
    },
    UnsupportedDecodeLifecycleOutput {
        reset_bound: usize,
        finish_bound: usize,
    },
    TranscodeAfterFinish,
    TranscodeBeforeReset,
    FinishAfterFinish,
    FinishBeforeReset,
    LifecyclePoisoned,
}

Framework-level failure reported by a transcode operation.

These failures are part of the safe public transcode API. They describe caller-supplied buffer ranges, capacity planning, complete-input shape, and stream lifecycle misuse that the transcode layer can detect without interpreting a concrete codec error.

Examples

use qubit_codec::TranscodeFailure;

let failure = TranscodeFailure::invalid_input_index(4, 3);
assert_eq!(failure.to_string(), "invalid input index 4 for input length 3");
assert_eq!(TranscodeFailure::ensure_input_index(3, 4), Err(failure));

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

InvalidInputIndex

The caller supplied an input index outside the input slice.

Fields

index: usize

Invalid input index supplied by the caller.

input_len: usize

Length of the input slice.

InvalidOutputIndex

The caller supplied an output index outside the output slice.

Fields

index: usize

Invalid output index supplied by the caller.

output_len: usize

Length of the output slice.

InvalidOutputRange

The caller supplied an output range extending beyond the output slice.

Fields

output_index: usize

Absolute output index where the range starts.

range_len: usize

Length of the caller-supplied output range.

output_len: usize

Length of the output slice.

InsufficientOutput

The output slice cannot hold all required output.

Fields

output_index: usize

Absolute output index where writing would start.

required: usize

Output units required from output_index.

available: usize

Output units available from output_index.

OutputLengthOverflow

Output length arithmetic overflowed.

AllocationFailed

The allocator could not reserve the requested output storage.

IncompleteInput

The complete input ended with an incomplete value.

Fields

input_index: usize

Absolute input index where the incomplete value starts.

required: usize

Current minimum total input units required from input_index before retrying. A later retry may raise this lower bound.

available: usize

Input units available from input_index.

InvalidProgress

A transcoder returned progress inconsistent with the supplied buffers.

Fields

source: TranscodeContractError

Contract error describing the invalid progress.

TrailingInput

The input contains exactly one decoded value plus trailing units.

Fields

consumed: usize

Units consumed by the decoded value.

remaining: usize

Extra units left after the decoded value.

UnsupportedDecodeLifecycleOutput

A strict single-value decoder cannot expose codec lifecycle output.

Fields

reset_bound: usize

Maximum values the codec may emit while resetting decode state.

finish_bound: usize

Maximum values the codec may emit while finishing decode state.

TranscodeAfterFinish

transcode was called after the logical stream was finished.

TranscodeBeforeReset

transcode was called before the first successful reset.

FinishAfterFinish

finish was called after the logical stream was already finished.

FinishBeforeReset

finish was called before the first successful reset.

LifecyclePoisoned

Reset or finish failed after codec, hook, or buffered state may have changed. Continuing could repeat side effects or observe inconsistent state; a successful reset is required before further use.

Implementations

impl TranscodeFailure

pub const fn invalid_input_index(index: usize, len: usize) -> Self

Creates an invalid-input-index error.

Parameters

• index: Absolute input index rejected by the caller boundary.
• len: Total number of input units.

Returns

Returns a failure retaining the supplied index and input length.

pub const fn invalid_output_index(index: usize, len: usize) -> Self

Creates an invalid-output-index error.

Parameters

• index: Absolute output index rejected by the caller boundary.
• len: Total number of writable output units.

Returns

Returns a failure retaining the supplied index and output length.

pub const fn invalid_output_range( output_index: usize, range_len: usize, output_len: usize, ) -> Self

Creates an invalid-output-range error.

Parameters

• output_index: Absolute start of the requested output range.
• range_len: Requested range length.
• output_len: Total output slice length.

Returns

Returns a failure describing the range that exceeds the output slice.

pub const fn insufficient_output( output_index: usize, required: usize, available: usize, ) -> Self

Creates an insufficient-output error.

Parameters

• output_index: Absolute start of the writable output.
• required: Units needed from that index.
• available: Units actually available from that index.

Returns

Returns a failure retaining the required and available capacities.

pub const fn output_length_overflow() -> Self

Creates an output-length-overflow error.

Returns

Returns the framework marker for unrepresentable output capacity.

pub const fn allocation_failed() -> Self

Creates an output-allocation failure.

Returns

Returns the framework marker for a failed output allocation.

pub const fn incomplete_input( input_index: usize, required: usize, available: usize, ) -> Self

Creates an incomplete-input error.

Parameters

• input_index: Absolute index where the incomplete value starts.
• required: Current minimum total units needed from that index.
• available: Units currently available from that index.

Returns

Returns a failure preserving the incomplete tail and retry requirement.

pub const fn invalid_progress(source: TranscodeContractError) -> Self

Creates an invalid-progress error.

Parameters

• source: Contract violation detected in a transcoder report.

Returns

Returns a framework failure that retains the contract error as its source.

pub const fn trailing_input(consumed: usize, remaining: usize) -> Self

Creates a trailing-input error.

Parameters

• consumed: Units used by the decoded value.
• remaining: Extra units after that value.

Returns

Returns a failure describing the otherwise successful single-value decode.

pub const fn unsupported_decode_lifecycle_output( reset_bound: usize, finish_bound: usize, ) -> Self

Creates an unsupported decode-lifecycle-output error.

Parameters

• reset_bound: Maximum values produced by decode reset.
• finish_bound: Maximum values produced by decode finish.

Returns

Returns a failure retaining the lifecycle output bounds rejected by strict decoding.

pub fn ensure_input_index( input_len: usize, input_index: usize, ) -> Result<(), Self>

Validates that input_index is within an input slice.

Parameters

• input_len: Total input slice length.
• input_index: Absolute start index, including the end boundary.

Returns

Returns Ok(()) when the index is at most the input length.

Errors

Returns Self::InvalidInputIndex when the index exceeds the length.

pub fn ensure_min_input( input_len: usize, input_index: usize, min_required: usize, ) -> Result<(), Self>

Validates that enough input units are available from input_index.

Parameters

• input_len: Total input slice length.
• input_index: Absolute start of the input region.
• min_required: Minimum readable units required from that start.

Returns

Returns Ok(()) when the start index and minimum readable capacity are valid.

Errors

Returns Self::InvalidInputIndex for an invalid start, or Self::IncompleteInput when fewer than min_required units remain.

pub fn ensure_no_trailing_input( consumed: usize, input_len: usize, ) -> Result<(), Self>

Validates a consumed input count and rejects trailing input.

Parameters

• consumed: Number of input units consumed by the decoded value.
• input_len: Total number of input units supplied.

Returns

Returns Ok(()) when consumed == input_len.

Errors

Returns TranscodeFailure::InvalidInputIndex when consumed exceeds input_len, or TranscodeFailure::TrailingInput when unconsumed input remains.

pub fn ensure_output_index( output_len: usize, output_index: usize, ) -> Result<(), Self>

Validates that output_index is within an output slice.

Parameters

• output_len: Total output slice length.
• output_index: Absolute start index, including the end boundary.

Returns

Returns Ok(()) when the index is at most the output length.

Errors

Returns Self::InvalidOutputIndex when the index exceeds the length.

pub fn ensure_transcode_indices( input_len: usize, input_index: usize, output_len: usize, output_index: usize, ) -> Result<(), Self>

Validates input and output start indices for a transcode call.

Parameters

• input_len: Total input slice length.
• input_index: Absolute starting input index.
• output_len: Total output slice length.
• output_index: Absolute starting output index.

Returns

Returns Ok(()) when both indices lie within their slices or at their ends.

Errors

Returns Self::InvalidInputIndex first for invalid input, otherwise Self::InvalidOutputIndex for invalid output.

pub fn ensure_output_capacity( output_len: usize, output_index: usize, required: usize, ) -> Result<(), Self>

Validates that an output slice can hold one-shot finalization output.

Parameters

• output_len: Total output slice length.
• output_index: Absolute start of the writable region.
• required: Minimum output units needed from that start.

Returns

Returns Ok(()) when the output region has at least required units.

Errors

Returns Self::InvalidOutputIndex for an invalid start, or Self::InsufficientOutput when the remaining capacity is too small.

pub fn ensure_output_range( output_len: usize, output_index: usize, range_len: usize, required: usize, ) -> Result<(), Self>

Validates an indexed output range and its minimum writable capacity.

Parameters

• output_len: Total output slice length.
• output_index: Absolute start of the writable range.
• range_len: Length of the caller-selected writable range.
• required: Minimum capacity required within the selected range.

Returns

Returns Ok(()) when the selected range fits and has enough capacity.

Errors

Returns Self::InvalidOutputIndex for an invalid start, Self::InvalidOutputRange when the range exceeds the slice, or Self::InsufficientOutput when the selected range is too short.

Trait Implementations

impl Clone for TranscodeFailure

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for TranscodeFailure

impl Debug for TranscodeFailure

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

Formats the value using the given formatter.

impl Display for TranscodeFailure

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

Formats the value using the given formatter.

impl Eq for TranscodeFailure

impl Error for TranscodeFailure

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.

impl From<CapacityError> for TranscodeFailure

fn from(error: CapacityError) -> Self

Converts capacity planning errors into transcode framework failures.

Parameters

• error: Capacity-planning failure to translate.

Returns

Returns the corresponding framework output-length-overflow failure.

impl From<TranscodeContractError> for TranscodeFailure

fn from(error: TranscodeContractError) -> Self

Converts a broken transcoder progress report into a framework failure.

Parameters

• error: Progress-contract violation to retain as the error source.

Returns

Returns Self::InvalidProgress carrying the original violation.

impl<DE, EE, V> From<TranscodeFailure> for TranscodeConvertError<DE, EE, V>

fn from(source: TranscodeFailure) -> Self

Converts to this type from the input type.

impl<E> From<TranscodeFailure> for TranscodeDecodeError<E>

fn from(source: TranscodeFailure) -> Self

Converts to this type from the input type.

impl<E, V> From<TranscodeFailure> for TranscodeEncodeError<E, V>

fn from(source: TranscodeFailure) -> Self

Converts to this type from the input type.

impl Hash for TranscodeFailure

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for TranscodeFailure

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

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for TranscodeFailure