Struct TranscodeDecodeInput 

pub struct TranscodeDecodeInput<I>
where
    I: Input,
    I::Item: Copy + Default,
{ /* private fields */ }

Decodes an Input unit stream into an Input value stream.

This type owns only the unit-level qubit_io::BufferedInput. Callers pass a streaming Transcoder and error mapper to each decode operation, which lets one buffered input drive different decoders without nesting buffers or storing decoder-specific state in the buffer owner.

Type Parameters

• I - Wrapped unit input.

Examples

use core::convert::Infallible;
use core::num::NonZeroUsize;
use std::io::Cursor;
use qubit_codec::Codec;
use qubit_codec::DecodeFailure;
use qubit_codec::TranscodeDecodeInput;

struct Identity;
impl Codec for Identity {
    type Value = u8;
    type Unit = u8;
    type DecodeError = Infallible;
    type EncodeError = Infallible;
    const MIN_UNITS_PER_VALUE: usize = 1;
    const MAX_DECODE_UNITS_PER_VALUE: usize = 1;
    const MAX_ENCODE_UNITS_PER_VALUE: usize = 1;
    unsafe fn decode(&mut self, input: &[u8], index: usize)
        -> Result<(u8, NonZeroUsize), DecodeFailure<Infallible>> {
        Ok((input[index], NonZeroUsize::MIN))
    }
    unsafe fn encode(&mut self, value: &u8, output: &mut [u8], index: usize)
        -> Result<usize, Infallible> {
        output[index] = *value;
        Ok(1)
    }
}

let mut input = TranscodeDecodeInput::with_capacity(Cursor::new(vec![42_u8]), 8);
assert!(input.fill_until(1).expect("refilling the cursor input should succeed"));
assert_eq!(input.unread(), &[42]);
let value = input.read_decoded_with(&mut Identity, |error| match error {})?;
assert_eq!(value, 42);

read_decoded_with reads one complete value and owns its strict single-value lifecycle; use the step methods when the caller needs to coordinate streaming input and output itself.

Implementations

impl<I> TranscodeDecodeInput<I>

where I: Input, I::Item: Copy + Default,

pub fn new(inner: I) -> Self

Creates a decoder input with the default unit buffer capacity.

Parameters

• inner - Unit input read by this adapter.

Returns

A new buffered decoder input.

Panics

Panics if I::Item::default() panics or the default buffer capacity exceeds the supported allocation size.

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

Creates a decoder input with a unit buffer of at least capacity.

Parameters

• inner - Unit input read by this adapter.
• capacity - Requested internal unit buffer capacity.

Returns

A new buffered decoder input.

Panics

Panics if I::Item::default() panics or the requested capacity exceeds the supported allocation size.

pub fn try_with_capacity( inner: I, capacity: usize, ) -> StdResult<Self, TryReserveError>

Creates a decoder input with a unit buffer of at least capacity.

Parameters

• inner - Unit input read by this adapter.
• capacity - Requested internal unit buffer capacity.

Returns

Returns a buffered adapter owning inner with at least the requested capacity.

Errors

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

Panics

Panics if I::Item::default() panics while initializing the buffer.

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

Returns a shared reference to the wrapped unit input.

The wrapped input can be physically positioned after units that remain unread in this adapter’s internal buffer.

Returns

A shared reference to the wrapped unit input.

pub fn unread_len(&self) -> usize

Returns the number of unread units currently buffered.

Returns

The number of unread units in the internal buffer.

pub fn unread(&self) -> &[I::Item]

Returns the currently buffered unread units.

Returns

Returns a shared slice over the unread portion of the internal unit buffer. The slice is valid until this adapter is mutated.

pub fn capacity(&self) -> usize

Returns the internal unit buffer capacity.

Returns

The maximum number of units retained in the internal buffer.

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

Refills the internal buffer until at least count unread units are available.

Parameters

• count - Minimum number of unread units required.

Returns

Returns true when at least count units are buffered; false if EOF prevents reaching that count. Buffered units remain available in either case.

Errors

Returns allocation errors mapped to ErrorKind::OutOfMemory, or I/O errors from the wrapped input while refilling.

pub fn transcode_step<D, M, Value>( &mut self, decoder: &mut D, map_error: &mut M, output: &mut [Value], output_index: usize, count: usize, ) -> Result<Option<TranscodeProgress>>

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

Performs one decode step and preserves the transcoder stop status.

None means that the wrapped input reached EOF with no buffered units. Consumed input is committed before this method returns. Callers can use the returned TranscodeProgress to distinguish NeedOutput from an incomplete input tail without guessing from the unread buffer alone.

Type Parameters

• D: Streaming decoder accepting the source unit type.
• M: Mapper from decoder errors to I/O errors.
• Value: Decoded destination value type.

Parameters

• decoder: Decoder for the current logical stream.
• map_error: Mapper invoked for decoder errors.
• output: Destination value storage.
• output_index: Start of the writable range.
• count: Maximum number of destination values available.

Returns

Returns Some validated progress after a decode step, or None at EOF with no buffered units. A zero count returns Some zero progress.

Errors

Returns invalid output-range or progress errors, input/refill errors, or decoder errors translated by map_error. A successful validated progress commits its read() count. If decoding or progress validation fails, this call does not consume the unread range. The decoder and destination may already have changed; neither is rolled back, and no complete progress report is available. A refill performed before the failure is not rolled back at the wrapped input. Do not replay the original input unless the decoder defines an explicit recovery protocol.

pub fn transcode_eof_step<D, M, Value>( &mut self, decoder: &mut D, map_error: &mut M, output: &mut [Value], output_index: usize, count: usize, ) -> Result<TranscodeProgress>

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

Performs one decode step after the caller has established EOF.

This method does not read from the wrapped input. It passes the current unread buffer to Transcoder::transcode_eof, validates the returned progress, and commits consumed source units before returning.

Type Parameters

• D: Streaming decoder accepting the source unit type.
• M: Mapper from decoder errors to I/O errors.
• Value: Decoded destination value type.

Parameters

• decoder: Decoder for the current logical stream.
• map_error: Mapper invoked for decoder errors.
• output: Destination value storage.
• output_index: Start of the writable range.
• count: Maximum number of destination values available.

Returns

Returns validated EOF progress. A zero output count returns zero progress without calling the decoder; an empty input is still passed to transcode_eof so decoders can handle EOF with retained state.

Errors

Returns invalid output-range errors, decoder errors mapped by map_error, or InvalidData if the decoder requests more input after EOF. Invalid progress does not commit source consumption, but decoder state and caller-owned output are not rolled back.

pub fn consume(&mut self, count: usize)

Consumes unread units from the current buffer window.

Parameters

• count - Number of unread units to discard.

Panics

Panics when count exceeds Self::unread_len.

pub unsafe fn copy_unread_to( &self, output: &mut [I::Item], output_index: usize, count: usize, )

Copies unread units into an indexed output range without consuming them.

Parameters

• output - Destination storage that receives a copy of unread units.
• output_index - Start index inside output.
• count - Number of unread units to copy.

Safety

The caller must guarantee that output_index..output_index + count is a valid range inside output, that the addition does not overflow, that count <= self.unread_len(), and that the destination range does not overlap with the unread units stored inside this buffer.

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

Consumes this adapter and returns its parts.

Returns

The wrapped input and the buffer holding unread units.

pub unsafe fn read_unchecked( &mut self, output: &mut [I::Item], output_index: usize, count: usize, ) -> Result<usize>

Reads buffered units into an indexed output range.

Parameters

• output - Destination unit storage.
• output_index - Start index inside output.
• count - Maximum number of units to read.

Returns

The number of units copied into output.

Errors

Returns input or buffer validation errors from the wrapped qubit_io::BufferedInput.

Panics

Debug builds panic if the destination range violates the safety contract.

Safety

The caller must guarantee that output_index..output_index + count is a valid range inside output and that the addition does not overflow.

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

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

Decodes one codec value from the buffered unit input.

This strict convenience method supports codecs whose decode reset and finish phases do not emit values. Use Self::read_decoded_lifecycle_with when those phases have output.

Type Parameters

• C: Codec accepting the wrapped input’s unit type.
• M: Mapper from codec decode errors to I/O errors.

Parameters

• codec - Codec used for this single-value decode.
• map_error - Mapper for codec-domain invalid-input errors.

Returns

Returns one decoded codec value.

Errors

Returns ErrorKind::Unsupported before invoking the codec or reading input when reset or finish may emit values. Otherwise, returns I/O errors from the wrapped input, UnexpectedEof when EOF occurs before a complete value is available, InvalidData when the codec reports an impossible incomplete state, or a mapped codec-domain error for reset, invalid input, or finish failures. Each mapped error owns a TranscodeDomainError identifying the phase; main decode errors use index 0, the start of this single-value input window. The mapper’s error remains the wrapper source, preserving its kind and payload.

This operation is not transactional. A successful main decode consumes its source units before codec finalization. If finalization fails, the decoded value is not returned and the consumed input is not restored. A later read must not be treated as a retry of that value. Truncated input at EOF is consumed before reporting the error. Invalid-input consumption follows the codec’s validated consumption hint. Codec state is not rolled back. The Unsupported preflight error above is returned before invoking the codec or reading input.

Panics

Panics when the codec reports more reset or finish values than its declared bounds.

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

where C: Codec<Unit = I::Item>, C::Value: Default, M: FnMut(C::DecodeError) -> Error,

Decodes one complete codec lifecycle and preserves every output phase.

The method allocates independent storage for values emitted by decode_reset and decode_finish, so neither phase can overwrite the other.

Type Parameters

• C: Codec accepting the wrapped input’s unit type.
• M: Mapper from codec decode errors to I/O errors.

Parameters

• codec: Codec used to decode one complete lifecycle.
• map_error: Maps codec decode errors to I/O errors.

Returns

Returns reset output, the main decoded value, and finish output.

Errors

Returns I/O errors from the wrapped input, UnexpectedEof when EOF occurs before a complete value is available, InvalidData when the codec reports an impossible incomplete state, or a mapped codec-domain error for reset, invalid input, or finish failures. Each mapped error owns a TranscodeDomainError identifying the phase; main decode errors use index 0, the start of this input window. The mapper’s error remains the wrapper source, preserving its kind and payload. Returns OutOfMemory when lifecycle output storage cannot be reserved.

This operation is not transactional. A successful main decode consumes its source units before codec finalization. If finalization fails, the decoded value is not returned and the consumed input is not restored. A later read must not be treated as a retry of that value. Truncated input at EOF is consumed before reporting the error. Invalid-input consumption follows the codec’s validated consumption hint. Codec state is not rolled back.

Panics

Panics when the codec reports more reset or finish values than its declared bounds.

pub fn read_decoded_lifecycle_with_scratch<C, M>( &mut self, codec: &mut C, reset_output: &mut [C::Value], finish_output: &mut [C::Value], map_error: M, ) -> Result<DecodeLifecycleProgress<C::Value>>

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

Decodes one complete codec lifecycle into separate caller storage.

Type Parameters

• C: Codec accepting the wrapped input’s unit type.
• M: Mapper from codec decode errors to I/O errors.

Parameters

• codec: Codec used to decode one complete lifecycle.
• reset_output: Reusable storage for values emitted by Codec::decode_reset.
• finish_output: Reusable storage for values emitted by Codec::decode_finish.
• map_error: Maps codec decode errors to I/O errors.

Returns

Returns the main decoded value and the initialized lengths of both lifecycle output buffers.

Errors

Returns ErrorKind::InvalidInput when either output buffer is shorter than the corresponding codec bound. Returns I/O errors from the wrapped input, UnexpectedEof when EOF occurs before a complete value is available, InvalidData when the codec reports an impossible incomplete state, or a mapped codec-domain error for reset, invalid input, or finish failures. Each mapped error owns a TranscodeDomainError identifying the phase; main decode errors use index 0, the start of this input window. The mapper’s error remains the wrapper source, preserving its kind and payload.

This operation is not transactional. A successful main decode consumes its source units before codec finalization. If finalization fails, the decoded value is not returned and the consumed input is not restored. A later read must not be treated as a retry of that value. Truncated input at EOF is consumed before reporting the error. Invalid-input consumption follows the codec’s validated consumption hint. Codec state is not rolled back. A short scratch buffer is rejected before invoking the codec or reading input. Reset and finish output buffers may already have changed when an error is returned; the error carries no valid output lengths, so their full contents must not be treated as this operation’s successful output. Recovery of codec state after an error is codec-specific, and consumed input is never restored.

Panics

Panics when the codec reports more reset or finish values than its declared bounds.

pub fn reset<D, M, Value>( &self, decoder: &mut D, map_error: &mut M, output: &mut [Value], output_index: usize, count: usize, ) -> Result<usize>

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

Runs decoder reset into an indexed output range.

This method does not read or consume buffered input units.

Type Parameters

• D: Streaming decoder accepting the source unit type.
• M: Mapper from decoder errors to I/O errors.
• Value: Decoded destination value type.

Parameters

• decoder: Decoder for the current logical stream.
• map_error: Mapper invoked for decoder errors.
• output: Destination value storage.
• output_index: Start of the writable range.
• count: Maximum number of destination values available.

Returns

Returns the number of reset values initialized in the requested range.

Errors

Returns invalid output ranges, insufficient declared output capacity, capacity errors, or reset errors mapped by map_error.

Panics

Panics when the decoder reports writing more values than its declared reset bound.

pub fn transcode<D, M, Value>( &mut self, decoder: &mut D, map_error: &mut M, output: &mut [Value], output_index: usize, count: usize, ) -> Result<usize>

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

Decodes values into an indexed output range using a streaming Transcoder.

Type Parameters

• D: Streaming decoder accepting the source unit type.
• M: Mapper from decoder errors to I/O errors.
• Value: Decoded destination value type.

Parameters

• decoder - Streaming decoder used for this operation.
• map_error - Function mapping transcode errors into I/O errors.
• output - Destination value storage.
• output_index - Start index inside output.
• count - Maximum number of values to write.

Returns

The number of values written. When this method is driven through EOF with output capacity remaining, it passes the retained tail—or an empty input when no tail remains—to Transcoder::transcode_eof before returning. A short return, including zero, may mean the decoder requires a larger contiguous output range. It does not prove conversion is complete. Use Self::transcode_step and Self::transcode_eof_step when the stop reason and required capacity must remain observable.

Errors

Returns input errors, invalid output ranges, capacity errors from the internal buffer, or transcode errors mapped by map_error. This operation is not transactional. An error may be returned after source units have been consumed and values have been written to output. Progress is not rolled back, and the error does not report the accumulated output length. Use transcode_step and commit each successful progress result when previously decoded values must remain observable after a later failure. The method does not refill for later values once the requested output range is full; the underlying input may still prefetch units beyond that range during an earlier read. If EOF processing stops with NeedOutput, the next batch call resumes EOF processing directly; a short return, including zero, does not mean conversion is complete. Use the step methods when the exact stop reason is needed. Explicitly refilling new units, seeking, or switching to raw/single-value reads changes the input context; callers remain responsible for the decoder lifecycle when continuing after such a switch.

pub fn finish<D, M, Value>( &self, decoder: &mut D, map_error: &mut M, output: &mut [Value], output_index: usize, count: usize, ) -> Result<usize>

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

Finishes a streaming decoder into an indexed output range.

Type Parameters

• D: Streaming decoder accepting the source unit type.
• M: Mapper from decoder errors to I/O errors.
• Value: Decoded destination value type.

Parameters

• decoder - Streaming decoder whose final output is being collected.
• map_error - Function mapping transcode errors into I/O errors.
• output - Destination value storage.
• output_index - Start index inside output.
• count - Maximum number of finish values to write.

Returns

The number of values written by the decoder finish operation.

Errors

Returns invalid output ranges, capacity errors, or transcode finalization errors mapped to I/O errors.

Panics

Panics when the decoder reports writing more values than its Transcoder::max_finish_output_len bound.

impl<I> TranscodeDecodeInput<I>

where I: SeekableByteInput,

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

Seeks the wrapped byte input and discards buffered bytes after success.

Parameters

• position - Target seek position.

Returns

The new stream position reported by the wrapped input.

Errors

Returns seek errors from the wrapped input.

Trait Implementations

impl<I> Debug for TranscodeDecodeInput<I>

where I: Input, I::Item: Copy + Default, BufferedInput<I>: Debug,

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

Formats this buffered decode input for debugging.

Parameters

• formatter: Formatting sink receiving the struct and owned input.

Returns

Returns success after writing the debug representation.

Errors

Propagates a formatting error from the sink or wrapped input.

impl<I> Read for TranscodeDecodeInput<I>

where I: ByteInput,

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

Reads raw bytes through the internal buffer.

Parameters

• output: Destination for raw buffered bytes.

Returns

Returns the number of bytes read; zero indicates EOF or an empty destination.

Errors

Propagates wrapped input or buffer errors.

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

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

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

Determines if this Reader has an efficient read_vectored implementation.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Reads all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Reads all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Reads the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: BorrowedCursor<'_, u8>) -> Result<(), Error>

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

Pull some bytes from this source into the specified buffer.

fn read_buf_exact( &mut self, cursor: BorrowedCursor<'_, u8>, ) -> Result<(), Error>

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

Reads the exact number of bytes required to fill cursor.

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

where Self: Sized,

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

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.

fn read_array<const N: usize>(&mut self) -> Result<[u8; N], Error>

where Self: Sized,

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

Read and return a fixed array of bytes from this source.

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

where T: FromEndianBytes, Self: Sized,

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

Read and return a type (e.g. an integer) in little-endian order.

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

where T: FromEndianBytes, Self: Sized,

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

Read and return a type (e.g. an integer) in big-endian order.

impl<I> Seek for TranscodeDecodeInput<I>

where I: SeekableByteInput,

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

Seeks the wrapped byte input and discards buffered bytes after success.

Parameters

• position: Target byte-stream position.

Returns

Returns the new byte offset after clearing buffered data.

Errors

Propagates wrapped seek errors, preserving the buffer when seeking fails.

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.