Struct TranscodeEncodeOutput 

pub struct TranscodeEncodeOutput<O>
where
    O: Output,
    O::Item: Copy + Default,
{ /* private fields */ }

Encodes an Output value stream into an Output unit stream.

This type owns only the unit-level qubit_io::BufferedOutput. Callers pass a crate::Codec and error mapper to each encode operation, which lets one buffered output drive different encoders without nesting buffers or storing codec-specific state in the buffer owner.

Self::flush only drains already buffered units. State-aware streaming encoders can use Self::reset, Self::transcode, and Self::finish explicitly.

Type Parameters

• O - Wrapped unit output.

Implementations

impl<O> TranscodeEncodeOutput<O>

where O: Output, O::Item: Copy + Default,

pub fn new(inner: O) -> Self

Creates an encoder output with the default unit buffer capacity.

Parameters

• inner - Unit output written by this adapter.

Returns

A new buffered encoder output.

pub fn with_capacity(inner: O, capacity: usize) -> Self

Creates an encoder output with a unit buffer of at least capacity.

Parameters

• inner - Unit output written by this adapter.
• capacity - Requested internal unit buffer capacity.

Returns

A new buffered encoder output.

pub fn try_with_capacity( inner: O, capacity: usize, ) -> Result<Self, TryReserveError>

Creates an encoder output with a unit buffer of at least capacity.

Parameters

• inner - Unit output written by this adapter.
• capacity - Requested internal unit buffer capacity.

Errors

Returns an allocation error when the requested buffer cannot be allocated.

pub const fn inner(&self) -> &O

Returns a shared reference to the wrapped unit output.

Pending units remain in this adapter’s internal buffer and are not visible through the returned output until Self::flush succeeds.

Returns

A shared reference to the wrapped unit output.

pub fn spare_capacity(&self) -> usize

Returns the available capacity of the spare output buffer.

Returns

The number of output units that can still be appended without flushing.

pub fn spare_raw_parts_mut(&mut self) -> (&mut [O::Item], usize, usize)

Returns raw spare-buffer parts for the internal output buffer.

Returns

The full backing storage, the spare start index, and the spare unit count.

pub unsafe fn advance(&mut self, count: usize)

Marks count units from Self::spare_raw_parts_mut as written.

Safety

The caller must guarantee that count <= Self::spare_capacity() and that the corresponding units in the returned spare slice have been initialized.

pub fn ensure_spare_capacity(&mut self, count: usize) -> Result<()>

Ensures that at least count spare units are available.

Parameters

• count - Number of spare units required.

Errors

Returns allocation errors mapped to ErrorKind::OutOfMemory, or I/O errors from the wrapped output while flushing pending units.

pub fn into_parts(self) -> (O, Buffer<O::Item>)

Consumes this adapter without flushing the wrapped output.

This method does not call Self::flush and performs no I/O. Pending units remain in the returned buffer, which transfers their delivery responsibility to the caller.

Returns

The wrapped output and the buffer holding pending units.

pub fn flush(&mut self) -> Result<()>

Flushes buffered units without finishing any encoder stream.

Errors

Returns errors from the wrapped output while flushing pending units.

pub fn write_encoded_with<C, M>( &mut self, codec: &mut C, value: &C::Value, map_error: M, ) -> Result<()>

where C: Codec<Unit = O::Item>, M: FnMut(C::EncodeError) -> Error,

Encodes one codec value into this buffered unit output.

The method grows the persistent internal buffer when necessary, then writes the complete encoded value into its spare window.

Parameters

• codec - Codec used for this single-value encode.
• value - Value to encode.
• map_error - Mapper for codec-domain encode errors.

Errors

Returns I/O errors from the wrapped output, InvalidInput when the codec output bound overflows or the value is outside the codec domain, or the error returned by map_error for codec encode, reset, and finish failures.

Panics

Panics when the codec violates its declared reset, value-width, or finish bounds, or when encode writes a length different from encode_len in the same reset state.

pub fn reset<E, M, Value>( &mut self, encoder: &mut E, map_error: &mut M, ) -> Result<()>

where E: Transcoder<Input = Value, Output = O::Item>, M: FnMut(E::Error) -> Error,

Runs encoder reset and buffers any stream-prefix units.

This method reserves enough persistent buffer capacity for all reset output before calling encoder. It does not flush pending units.

Errors

Returns capacity errors, allocation errors, or reset errors mapped by map_error.

Panics

Panics when encoder writes more than its declared reset bound.

pub fn transcode<E, M, Value>( &mut self, encoder: &mut E, map_error: &mut M, input: &[Value], input_index: usize, count: usize, ) -> Result<usize>

where E: TranscodeEncoder<Input = Value, Output = O::Item>, M: FnMut(E::Error) -> Error,

Encodes values from an indexed input range using a streaming Transcoder.

This streaming path writes directly into the internal spare buffer and grows it for any larger NeedOutput.required value reported by encoder.

Parameters

• encoder - Streaming encoder used for this operation.
• map_error - Function mapping transcode errors into I/O errors.
• input - Source values.
• input_index - Start index inside input.
• count - Maximum number of values to encode.

Returns

The number of source values consumed.

Errors

Returns invalid input ranges, capacity, transcode, or output errors.

Examples

A value that only implements Transcoder is not an encoder and cannot be passed to this method.

use qubit_codec::{
    CapacityError, TranscodeEncodeError, TranscodeEncodeOutput,
    TranscodeProgress, Transcoder,
};

struct GenericTranscoder;

impl Transcoder for GenericTranscoder {
    type Input = u8;
    type Output = u8;
    type Error = TranscodeEncodeError<(), u8>;

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

    fn reset(
        &mut self,
        _output: &mut [u8],
        _output_index: usize,
    ) -> Result<usize, Self::Error> {
        Ok(0)
    }

    fn transcode(
        &mut self,
        input: &[u8],
        input_index: usize,
        _output: &mut [u8],
        _output_index: usize,
    ) -> Result<TranscodeProgress, Self::Error> {
        Ok(TranscodeProgress::complete(input.len() - input_index, 0))
    }

    fn finish(
        &mut self,
        _output: &mut [u8],
        _output_index: usize,
    ) -> Result<usize, Self::Error> {
        Ok(0)
    }
}

let mut output = TranscodeEncodeOutput::with_capacity(std::io::sink(), 1);
let mut transcoder = GenericTranscoder;
let mut map_error = |_| std::io::Error::other("transcode error");
let _ = output.transcode(
    &mut transcoder,
    &mut map_error,
    &[0_u8],
    0,
    1,
);

pub fn finish<E, M, Value>( &mut self, encoder: &mut E, map_error: &mut M, ) -> Result<()>

where E: Transcoder<Input = Value, Output = O::Item>, M: FnMut(E::Error) -> Error,

Finishes the encoder and flushes the wrapped unit output.

This method writes final units directly into the internal spare buffer, growing it when Transcoder::max_finish_output_len exceeds the current capacity.

Parameters

• encoder - Encoder whose final units are being collected.
• map_error - Function mapping transcode errors into I/O errors.

Errors

Returns capacity, transcode finalization, or wrapped output flush errors.

pub fn finish_to_buffer<E, M, Value>( &mut self, encoder: &mut E, map_error: &mut M, ) -> Result<()>

where E: Transcoder<Input = Value, Output = O::Item>, M: FnMut(E::Error) -> Error,

Finishes the encoder while retaining final units in the output buffer.

This method separates encoder finalization from output delivery. It is useful when a caller must record successful finalization before a later flush can fail. Call Self::flush to deliver the retained units.

Parameters

• encoder - Encoder whose final units are being collected.
• map_error - Function mapping transcode errors into I/O errors.

Errors

Returns capacity planning, allocation, or transcoder finalization errors. It does not perform output I/O.

Panics

Panics when encoder writes more units than its declared finish bound.

impl<O> TranscodeEncodeOutput<O>

where O: Output<Item = u8> + Seekable<Unit = u8>,

pub fn seek(&mut self, position: SeekFrom) -> Result<u64>

Flushes pending bytes, then seeks the wrapped byte output.

Parameters

• position - Target seek position.

Returns

The new stream position reported by the wrapped output.

Errors

Returns flush or seek errors from the wrapped output.

Trait Implementations

impl<O> Debug for TranscodeEncodeOutput<O>

where O: Output, O::Item: Copy + Default, BufferedOutput<O>: Debug,

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

Formats this buffered encode output for debugging.

impl<O> Seek for TranscodeEncodeOutput<O>

where O: Output<Item = u8> + Seekable<Unit = u8>,

fn seek(&mut self, position: SeekFrom) -> Result<u64>

Flushes pending bytes, then seeks the wrapped byte output.

fn rewind(&mut self) -> Result<(), Error>

Rewind to the beginning of a stream.

fn stream_len(&mut self) -> Result<u64, Error>

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

Returns the length of this stream (in bytes).

fn stream_position(&mut self) -> Result<u64, Error>

Returns the current seek position from the start of the stream.

fn seek_relative(&mut self, offset: i64) -> Result<(), Error>

Seeks relative to the current position.

impl<O> Write for TranscodeEncodeOutput<O>

where O: Output<Item = u8>,

fn write(&mut self, input: &[u8]) -> Result<usize>

Writes raw bytes through the internal buffer.

fn write_all(&mut self, input: &[u8]) -> Result<()>

Writes all raw bytes through the internal buffer.

fn flush(&mut self) -> Result<()>

Flushes buffered bytes to the wrapped output.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

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

Determines if this Writer has an efficient write_vectored implementation.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

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

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.