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.

Examples

use std::io::Cursor;

use qubit_codec::TranscodeEncodeOutput;

let output = TranscodeEncodeOutput::with_capacity(Cursor::new(Vec::<u8>::new()), 8);
assert!(output.spare_capacity() >= 8);

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, ) -> CoreResult<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.

Returns

A buffered adapter owning inner on success.

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.

Parameters

• count - Initialized units to commit from the spare window.

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.

Type Parameters

• C - Codec producing the wrapped output unit type.
• M - Mapper from codec errors into I/O errors.

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.

Type Parameters

• E - Transcoder producing the wrapped output unit type.
• M - Mapper from transcoder errors into I/O errors.
• Value - Source value type accepted by the transcoder.

Parameters

• encoder - Transcoder whose stream prefix is being collected.
• map_error - Mapper for reset failures.

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.

Type Parameters

• E - Encoder producing the wrapped output unit type.
• M - Mapper from encoder errors into I/O errors.
• Value - Source value type accepted by the 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 std::io::Error;
use std::io::sink;

use qubit_codec::CapacityError;
use qubit_codec::TranscodeEncodeError;
use qubit_codec::TranscodeEncodeOutput;
use qubit_codec::TranscodeProgress;
use qubit_codec::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(sink(), 1);
let mut transcoder = GenericTranscoder;
let mut map_error = |_| 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.

Type Parameters

• E - Transcoder producing the wrapped output unit type.
• M - Mapper from transcoder errors into I/O errors.
• Value - Source value type accepted by the transcoder.

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.

Panics

Panics when the encoder exceeds its declared finish-output bound.

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.

Type Parameters

• E - Transcoder producing the wrapped output unit type.
• M - Mapper from transcoder errors into I/O errors.
• Value - Source value type accepted by the transcoder.

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 the owned buffer and underlying output for diagnostics.

Parameters

• formatter - Destination and formatting options.

Errors

Returns a formatting error if the destination rejects output.

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.

Parameters

• position - Target position relative to the selected seek origin.

Returns

The new absolute byte position.

Errors

Propagates flush or seek errors from the wrapped 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 without encoding them.

Parameters

• input - Bytes to append to the buffered unit output.

Returns

The number of bytes accepted, which may be shorter than input.

Errors

Propagates wrapped-output errors when buffer delivery is needed.

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

Writes all raw bytes through the internal buffer without encoding them.

Parameters

• input - Bytes that must all be accepted before success.

Errors

Propagates output errors and returns WriteZero if output stops progressing.

Panics

Panics when the wrapped output reports more bytes than supplied.

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

Flushes buffered bytes to the wrapped output without finishing an encoder.

Errors

Propagates wrapped-output flush errors.

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.