Struct TranscodeEncodeEngine 

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

Reusable buffered encoding engine for codec-backed encoders.

The engine owns the low-level codec and hook object. It keeps the common buffered encoding loop private: input-index validation, output-capacity checks, input consumption, output progress, and crate::TranscodeStatus reporting.

Use this type to build a streaming encoder over a one-value Codec. The engine does not allocate output. It encodes values accepted by Codec::can_encode_value directly through the codec. When a value is outside the codec’s encodable domain, the engine asks hooks whether to reject, skip, or replace it. If the current output buffer is too small for the selected value, the engine returns crate::TranscodeStatus::NeedOutput without consuming that input; the caller can provide a larger or fresh output buffer and resume with the returned input index.

For the common strict policy that simply wraps codec errors, use crate::CodecTranscodeEncoder. Use TranscodeEncodeEngine directly when the encode policy needs custom planning, replacement, skipped values, or finish-time output.

Examples

use core::{
    convert::Infallible,
    num::NonZeroUsize,
};
use qubit_codec::{
    Codec,
    TranscodeEncodeErrorOf,
    DecodeFailure,
    TranscodeStatus,
};
use qubit_codec::engine::{
    EncodeContext,
    EncodeUnencodableAction,
    TranscodeEncodeEngine,
    TranscodeEncodeHooks,
};

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

impl Codec for ByteCodec {
    type Value = u8;
    type Unit = u8;
    type DecodeError = Infallible;
    type EncodeError = Infallible;

    const MIN_UNITS_PER_VALUE: usize = 1;
    const MAX_ENCODE_UNITS_PER_VALUE: usize = 1;
    const MAX_DECODE_UNITS_PER_VALUE: usize = 1;

    unsafe fn decode(
        &mut self,
        input: &[u8],
        index: usize,
    ) -> Result<(u8, NonZeroUsize), DecodeFailure<Self::DecodeError>> {
        Ok((input[index], NonZeroUsize::MIN))
    }

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

struct StrictHooks;

impl TranscodeEncodeHooks<ByteCodec> for StrictHooks {
    fn handle_unencodable_encode(
        &mut self,
        _codec: &mut ByteCodec,
        _context: &EncodeContext<'_, u8>,
    ) -> Result<EncodeUnencodableAction<u8>, TranscodeEncodeErrorOf<ByteCodec>> {
        unreachable!("ByteCodec accepts every u8")
    }
}

let mut engine = TranscodeEncodeEngine::new(ByteCodec, StrictHooks);
let input = [1_u8, 2, 3];
let mut output = [0_u8; 2];
let mut reset_output = [];
engine.reset(&mut reset_output, 0)?;

let progress = engine.transcode(&input, 0, &mut output, 0)?;
match progress.status() {
    TranscodeStatus::Complete => unreachable!("output is intentionally short"),
    TranscodeStatus::NeedOutput { .. } => {
        assert_eq!(2, progress.written());
        assert_eq!([1, 2], output);
        // Write out `output[..progress.written()]`, then resume at
        // `progress.read()` with fresh output capacity.
    }
    TranscodeStatus::NeedInput { .. } => unreachable!("encoders do not read encoded input"),
}

Type Parameters

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

Implementations

impl<C, H> TranscodeEncodeEngine<C, H>

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

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

Creates a buffered encoder engine.

Parameters

• codec: Low-level codec used for one-value encoding.
• hooks: Policy hooks used for planning and writing values.

Returns

Returns a buffered encoder engine.

Compile-Time Checks

Fails to compile when the supplied codec declares a zero decode unit bound or when Codec::MIN_UNITS_PER_VALUE exceeds Codec::MAX_DECODE_UNITS_PER_VALUE. The encode bound may be zero for a fully buffered codec.

pub const fn codec(&self) -> &C

Returns the wrapped low-level codec.

Returns

Returns a shared reference to the codec owned by this engine.

pub fn codec_mut(&mut self) -> &mut C

Returns the wrapped low-level codec mutably.

Returns

Returns a mutable reference to the codec owned by this engine.

pub const fn hooks(&self) -> &H

Returns the encode hooks used by this engine.

Returns

Returns a shared reference to the hook object owned by this engine.

pub fn hooks_mut(&mut self) -> &mut H

Returns the encode hooks mutably.

Returns

Returns a mutable reference to the hook object owned by this engine.

pub fn into_parts(self) -> (C, H)

Consumes the engine and returns its codec and hooks.

Any lifecycle state owned by the engine is discarded.

Returns

Returns the wrapped codec followed by the encode hooks.

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

Gets a conservative upper bound for output units needed for input_len values.

This bound covers only the streaming encode phase. It is delegated to TranscodeEncodeHooks::max_transcode_output_len, so it includes hook policy and is valid for every reachable transient codec and hook state. Downstream encoders must use this engine-level API for capacity planning instead of recomputing the bound from Codec constants.

Parameters

• input_len: Number of input values the caller plans to encode.

Returns

a conservative upper bound for output units, or a capacity error on arithmetic overflow.

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

Gets the global maximum output units emitted by stream reset.

Returns

the codec’s reset-output upper bound.

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

Gets the global maximum output units emitted by finishing codec and hook state.

Returns the sum of Codec::MAX_ENCODE_FINISH_UNITS and the hook-provided final-output bound. The codec finish portion covers units written by Codec::encode_finish; hook implementations must not include that portion in TranscodeEncodeHooks::max_finish_output_len. Both component bounds cover every reachable transient state.

Returns

the combined codec-finish and hook-finish output bound.

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

Gets the maximum output units needed by a complete one-shot encode stream.

The returned bound covers reset output, the streaming encode phase for input_len values, and finish output. Its components are global across transient state. Higher-level complete encode helpers should use this engine-level bound instead of recomputing capacity from Codec constants, because hook policy may change streaming or finish output.

Parameters

• input_len: Number of input values in the complete stream.

Returns

Returns the complete-stream output bound, or a capacity error on arithmetic overflow.

pub fn reset( &mut self, output: &mut [C::Unit], output_index: usize, ) -> Result<usize, TranscodeEncodeErrorOf<C>>

Resets codec encode state, hook-owned state, and stream-start output.

Parameters

• output: Complete output unit slice visible to the encoder.
• output_index: Absolute output unit index where writing starts.

Returns

Returns the number of reset units written.

Errors

Returns framework errors when the caller provides invalid or insufficient output capacity. Returns domain errors when codec reset or hook reset handling fails. Capacity and index failures occur before any reset state is changed. Once reset execution starts, an error poisons the engine until a later reset succeeds.

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

Encodes values into a caller-provided output buffer.

The engine stops before consuming the next input value when the current output buffer does not satisfy that value’s planned capacity bound.

Parameters

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

Returns

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

Errors

Returns hook errors when input_index is outside input, when output_index is outside output, or when hook planning or writing rejects a value. Returns TranscodeFailure::TranscodeBeforeReset when the engine has not completed its first reset. Returns TranscodeFailure::TranscodeAfterFinish when the logical stream was already finished and has not been reset, or TranscodeFailure::LifecyclePoisoned when an earlier reset or finish failed after execution started.

pub fn finish( &mut self, output: &mut [C::Unit], output_index: usize, ) -> Result<usize, TranscodeEncodeErrorOf<C>>

Finishes codec and hook-owned output after EOF.

Finalization first finishes encode-side codec state through Codec::encode_finish, then lets hook implementations finish their own retained state. The caller must provide enough output capacity for TranscodeEncodeEngine::max_finish_output_len, which includes both the codec finish bound and the hook-owned finish bound.

Parameters

• output: Complete output unit slice visible to the encoder.
• output_index: Absolute output unit index where writing starts.

Returns

Returns the number of units written by finalization.

Errors

Returns framework errors when the caller provides invalid or insufficient output capacity. Returns domain errors when codec finish or hook finalization fails. Returns TranscodeFailure::FinishBeforeReset when the engine has not completed its first reset. Returns TranscodeFailure::FinishAfterFinish when the logical stream was already finished and has not been reset, or TranscodeFailure::LifecyclePoisoned when an earlier reset or finish failed after execution started. Capacity and index failures occur before finish execution and remain retryable; later failures poison the engine until reset succeeds.

Panics

Panics when the codec finish writes beyond Codec::MAX_ENCODE_FINISH_UNITS or when the combined codec and hook finalization writes beyond TranscodeEncodeEngine::max_finish_output_len.

pub fn transcode_complete_into( &mut self, input: &[C::Value], output: &mut [C::Unit], ) -> Result<usize, TranscodeEncodeErrorOf<C>>

Runs a complete one-shot reset -> transcode -> finish encode stream.

The complete input is supplied as input, and output starts at index 0 in output. Callers that need subranges should slice their buffers before calling this method. Downstream one-shot encoder helpers should call this engine method instead of reproducing the reset, transcode, and finish sequence themselves.

Parameters

• input: Complete input values.
• output: Output unit slice for the whole encoded stream.

Returns

Returns the number of output units written.

Errors

Returns framework errors for insufficient output or capacity overflow, and domain errors from reset, encode, or finish.

Trait Implementations

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

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

Formats the value using the given formatter.

impl<C, H> Default for TranscodeEncodeEngine<C, H>

where C: Codec + Default, H: TranscodeEncodeHooks<C> + Default,

fn default() -> Self

Creates a default buffered encoder engine.

Returns

Returns an engine with default codec and hooks.

impl<C, H> TranscodeEncoder for TranscodeEncodeEngine<C, H>

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

type EncodeError = <C as Codec>::EncodeError

Domain error type produced by encode internals.

impl<C, H> Transcoder for TranscodeEncodeEngine<C, H>

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

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

Returns an upper bound for units produced from input_len values.

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

Returns the maximum units emitted when resetting stream state.

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

Returns the maximum units emitted by finishing internal state.

fn reset( &mut self, output: &mut [C::Unit], output_index: usize, ) -> Result<usize, TranscodeEncodeErrorOf<C>>

Resets codec encode state, hook-owned state, and stream-start output.

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

Encodes input values into caller-provided output units.

fn finish( &mut self, output: &mut [C::Unit], output_index: usize, ) -> Result<usize, TranscodeEncodeErrorOf<C>>

Finishes hook-owned encoder state.

type Input = <C as Codec>::Value

Input unit type accepted by this transcoder.

type Output = <C as Codec>::Unit

Output unit type produced by this transcoder.

type Error = TranscodeEncodeError<<C as Codec>::EncodeError, <C as Codec>::Value>

Complete error type produced by this transcoder.

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

Returns an upper bound for a complete reset -> transcode -> finish stream.

fn transcode_eof( &mut self, input: &[Self::Input], input_index: usize, output: &mut [Self::Output], output_index: usize, ) -> Result<TranscodeProgress, Self::Error>

Converts source units after the caller has established end of input.

fn transcode_complete_into( &mut self, input: &[Self::Input], output: &mut [Self::Output], ) -> Result<usize, Self::Error>

Runs a complete one-shot reset -> transcode -> finish stream.