Struct TranscodeDecodeEngine 

pub struct TranscodeDecodeEngine<C, H> { /* private fields */ }

Reusable buffered decoding engine for codec-backed decoders.

The engine owns the low-level codec and hook object. It keeps the common buffered decoding loop private: input-index validation, output-capacity checks, calls to Codec::decode, hook dispatch, and crate::TranscodeStatus reporting. Incomplete input tails are left in the caller-provided input slice; callers own input-buffer refill.

Use this type to build a streaming decoder over a one-value Codec. The engine decodes into a caller-provided output slice and returns TranscodeProgress instead of allocating. On success it writes decoded values directly to output. On codec errors it delegates to crate::TranscodeDecodeHooks, allowing a policy to request more input, skip invalid units, emit a replacement value, or fail.

The engine stops before reading an incomplete value when fewer than Codec::min_units_per_value units are available. For variable-width codecs, the codec may still return an incomplete decode error after that minimum is satisfied; hooks should convert that error into crate::DecodeAction::NeedInput when the stream may continue.

For strict decoding that wraps codec errors, use crate::CodecTranscodeDecoder. Use TranscodeDecodeEngine directly when invalid input should be repaired, skipped, counted, or otherwise handled by policy.

Example

use core::num::NonZeroUsize;
use qubit_codec::{
    Codec,
    CodecDecodeError,
    DecodeAction,
    DecodeContext,
    TranscodeStatus,
    TranscodeDecodeEngine,
    TranscodeDecodeHooks,
};

#[derive(Clone, Copy)]
struct ByteCodec;

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
enum ByteDecodeError {
    Malformed { consumed: NonZeroUsize },
}

unsafe impl Codec for ByteCodec {
    type Value = u8;
    type Unit = u8;
    type DecodeError = ByteDecodeError;
    type EncodeError = core::convert::Infallible;

    fn min_units_per_value(&self) -> NonZeroUsize {
        NonZeroUsize::MIN
    }

    fn max_units_per_value(&self) -> NonZeroUsize {
        NonZeroUsize::MIN
    }

    unsafe fn decode(
        &mut self,
        input: &[u8],
        index: usize,
    ) -> Result<(u8, NonZeroUsize), Self::DecodeError> {
        match input[index] {
            0xff => Err(ByteDecodeError::Malformed {
                consumed: NonZeroUsize::MIN,
            }),
            value => Ok((value, NonZeroUsize::MIN)),
        }
    }

    unsafe fn encode(
        &mut self,
        value: &u8,
        output: &mut [u8],
        index: usize,
    ) -> Result<NonZeroUsize, Self::EncodeError> {
        output[index] = *value;
        Ok(NonZeroUsize::MIN)
    }
}

struct ReplacementHooks;

impl TranscodeDecodeHooks<ByteCodec> for ReplacementHooks {
    type Error = CodecDecodeError<ByteDecodeError>;

    fn handle_decode_error(
        &mut self,
        _codec: &mut ByteCodec,
        error: ByteDecodeError,
        _context: DecodeContext,
    ) -> Result<DecodeAction<u8>, Self::Error> {
        match error {
            ByteDecodeError::Malformed { consumed } => {
                Ok(DecodeAction::Emit { value: b'?', consumed })
            }
        }
    }
}

let mut engine = TranscodeDecodeEngine::<_, _>::new(ByteCodec, ReplacementHooks);
let input = [b'a', 0xff, b'b'];
let mut output = [0_u8; 3];

let progress = engine.transcode(&input, 0, &mut output, 0)?;
match progress.status() {
    TranscodeStatus::Complete => assert_eq!(&output[..progress.written()], b"a?b"),
    TranscodeStatus::NeedInput { input_index, .. } => {
        // Keep `input[input_index..]`, append more source units, and resume.
    }
    TranscodeStatus::NeedOutput { output_index, .. } => {
        // Drain `output[..output_index]`, then resume with more output room.
    }
}

Type Parameters

• C: Low-level codec used by the engine.
• H: Policy hook object used by the engine.

Implementations

impl<C, H> TranscodeDecodeEngine<C, H>

where C: Codec, H: TranscodeDecodeHooks<C>,

pub fn new(codec: C, hooks: H) -> Self

Creates a buffered decoder engine.

Parameters

• codec: Low-level codec used for one-value decoding.
• hooks: Policy hooks used for decode failures.

Returns

Returns a buffered decoder engine.

Panics

Panics when the supplied codec violates the Codec::min_units_per_value / Codec::max_units_per_value ordering invariant.

pub fn max_output_len(&self, input_len: usize) -> Result<usize, CapacityError>

Returns an upper bound for decoded values produced from input_len units.

Parameters

• input_len: Number of source units the caller plans to decode.

Returns

Returns a conservative upper bound, or a capacity error on arithmetic overflow.

pub fn max_finish_output_len(&self) -> Result<usize, CapacityError>

Returns the maximum values emitted by flushing codec state and finishing hook-owned state.

Returns

Returns the sum of Codec::max_decode_flush_values and the hook-provided final-output bound. The codec flush portion covers values written by Codec::decode_flush; hook implementations must not include that portion in TranscodeDecodeHooks::max_finish_output_len.

pub fn max_reset_output_len(&self) -> usize

Returns the maximum values emitted when resetting stream state.

Decoders do not emit reset output; this bound is always 0.

pub fn reset( &mut self, output: &mut [C::Value], output_index: usize, ) -> Result<usize, TranscodeError<H::Error>>

Resets codec decode state and hook-owned state.

Parameters

• output: Complete output value slice visible to the decoder.
• output_index: Absolute output value index where writing would start.

Returns

Returns 0 because decoders do not emit stream-start output on reset.

Errors

Returns hook errors when output_index is invalid or reset fails.

pub fn transcode( &mut self, input: &[C::Unit], input_index: usize, output: &mut [C::Value], output_index: usize, ) -> Result<TranscodeProgress, TranscodeError<H::Error>>

Decodes source units into caller-provided output values.

Parameters

• input: Complete input unit slice visible to the decoder.
• input_index: Absolute input unit index where decoding starts.
• output: Complete output value slice visible to the decoder.
• output_index: Absolute output value index where writing starts.

Returns

Returns progress describing input units consumed, output values written, and why decoding stopped.

Errors

Returns hook errors when input_index is outside input, when output_index is outside output, or when a concrete policy hook rejects a value.

pub fn finish( &mut self, output: &mut [C::Value], output_index: usize, ) -> Result<usize, TranscodeError<H::Error>>

Finishes codec and hook-owned output after EOF.

Finalization first flushes decode-side codec state through Codec::decode_flush, then lets hook implementations finish their own retained state. The caller must provide enough output capacity for TranscodeDecodeEngine::max_finish_output_len, which includes both the codec flush bound and the hook-owned finish bound.

Parameters

• output: Complete output value slice visible to the decoder.
• output_index: Absolute output value index where writing starts.

Returns

Returns the number of values written by finalization.

Errors

Returns hook errors when the caller provides invalid or insufficient output capacity, when codec flush errors are mapped by the hooks, or when hook finalization fails.

Panics

Panics when the codec flush writes beyond Codec::max_decode_flush_values or when the combined codec and hook finalization writes beyond TranscodeDecodeEngine::max_finish_output_len.

Trait Implementations

impl<C: Clone, H: Clone> Clone for TranscodeDecodeEngine<C, H>

fn clone(&self) -> TranscodeDecodeEngine<C, H>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<C: Debug, H: Debug> Debug for TranscodeDecodeEngine<C, H>

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

Formats the value using the given formatter.

impl<C: Default, H: Default> Default for TranscodeDecodeEngine<C, H>

fn default() -> TranscodeDecodeEngine<C, H>

Returns the “default value” for a type.

impl<C: Eq, H: Eq> Eq for TranscodeDecodeEngine<C, H>

impl<C: Hash, H: Hash> Hash for TranscodeDecodeEngine<C, H>

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<C: PartialEq, H: PartialEq> PartialEq for TranscodeDecodeEngine<C, H>

fn eq(&self, other: &TranscodeDecodeEngine<C, H>) -> 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<C: PartialEq, H: PartialEq> StructuralPartialEq for TranscodeDecodeEngine<C, H>

impl<C, H> Transcoder<<C as Codec>::Unit, <C as Codec>::Value> for TranscodeDecodeEngine<C, H>

where C: Codec, H: TranscodeDecodeHooks<C>,

fn max_output_len(&self, input_len: usize) -> Result<usize, CapacityError>

Returns an upper bound for decoded values produced from input_len units.

fn max_finish_output_len(&self) -> Result<usize, CapacityError>

Returns an upper bound for values produced by finishing codec and hook state.

fn max_reset_output_len(&self) -> Result<usize, CapacityError>

Returns an upper bound for values emitted when resetting stream state.

fn reset( &mut self, output: &mut [C::Value], output_index: usize, ) -> Result<usize, TranscodeError<Self::Error>>

Resets codec decode state and hook-owned state.

fn transcode( &mut self, input: &[C::Unit], input_index: usize, output: &mut [C::Value], output_index: usize, ) -> Result<TranscodeProgress, TranscodeError<Self::Error>>

Decodes source units into logical values.

fn finish( &mut self, output: &mut [C::Value], output_index: usize, ) -> Result<usize, TranscodeError<Self::Error>>

Finishes internally retained output after EOF.

type Error = <H as TranscodeDecodeHooks<C>>::Error

Domain error reported by semantic conversion failures.