pub struct CodecTranscodeConverter<D, E>{ /* private fields */ }Expand description
Converts source units to target units through a decoded value by using codecs.
The converter decodes one source value with the decoder codec, then encodes
that value with the encoder codec. If the current output buffer cannot hold
the encoded value, the already decoded value is retained by the common
converter engine and must be drained before more source input is consumed.
Incomplete source tails are left in the caller-provided input slice while
the stream is open; callers own input-buffer refill. After upstream EOF,
call Transcoder::transcode_eof to let the source codec apply
Codec::decode_eof and the configured incomplete-input policy to the
remaining tail, then call Transcoder::finish to finalize the stream.
This supports EOF-aware maximal-munch decoding when the codec expresses it
through decode_eof. A custom transcoder or facade is needed only when the
source framing requires behavior outside that codec EOF contract.
§Type Parameters
D: Low-level codec used to decode source units.E: Low-level codec used to encode target units.
§Examples
A byte-preserving codec can be adapted to the buffered streaming interface.
use core::convert::Infallible;
use core::num::NonZeroUsize;
use qubit_codec::Codec;
use qubit_codec::CodecTranscodeConverter;
use qubit_codec::DecodeFailure;
let mut converter = CodecTranscodeConverter::new(ByteCodec, ByteCodec);
let mut output = [0_u8; 2];
converter.reset(&mut output, 0).unwrap();
converter.transcode(&[7, 9], 0, &mut output, 0).unwrap();
assert_eq!(output, [7, 9]);Implementations§
Source§impl<D, E> CodecTranscodeConverter<D, E>
impl<D, E> CodecTranscodeConverter<D, E>
Sourcepub fn source_codec(&self) -> &D
pub fn source_codec(&self) -> &D
Returns a shared reference to the source codec.
§Returns
Borrows the source codec without allocating or changing stream state.
Sourcepub fn source_codec_mut(&mut self) -> &mut D
pub fn source_codec_mut(&mut self) -> &mut D
Returns a mutable reference to the source codec.
Mutating a codec during an active stream can invalidate that stream’s assumptions; reset the adapter before continuing with the new codec configuration.
§Returns
Exclusively borrows the codec while the adapter remains borrowed.
Sourcepub fn target_codec(&self) -> &E
pub fn target_codec(&self) -> &E
Returns a shared reference to the target codec.
§Returns
Borrows the target codec without allocating or changing stream state.
Sourcepub fn target_codec_mut(&mut self) -> &mut E
pub fn target_codec_mut(&mut self) -> &mut E
Returns a mutable reference to the target codec.
Mutating a codec during an active stream can invalidate that stream’s assumptions; reset the adapter before continuing with the new codec configuration.
§Returns
Exclusively borrows the codec while the adapter remains borrowed.
Sourcepub fn into_codecs(self) -> (D, E)
pub fn into_codecs(self) -> (D, E)
Consumes the adapter and returns its source and target codecs.
Any buffered lifecycle state, pending value, and internal hooks are discarded.
§Returns
Returns the owned source codec followed by the owned target codec.
Sourcepub fn max_transcode_output_len(
&self,
input_len: usize,
) -> Result<usize, CapacityError>
pub fn max_transcode_output_len( &self, input_len: usize, ) -> Result<usize, CapacityError>
Returns an upper bound for target units produced from input_len units.
This concrete adapter method is available even when D::Value does not
implement Default.
§Parameters
input_len: Source units the caller plans to convert.
§Returns
Returns a conservative upper bound for produced target units.
§Errors
Returns CapacityError::OutputLengthOverflow when component-bound
arithmetic overflows.
Sourcepub fn max_finish_output_len(&self) -> Result<usize, CapacityError>
pub fn max_finish_output_len(&self) -> Result<usize, CapacityError>
Returns the global maximum target units emitted by finishing internal state.
§Returns
Returns a conservative upper bound valid for every reachable converter state.
§Errors
Returns CapacityError::OutputLengthOverflow when component-bound
arithmetic overflows.
Sourcepub fn max_reset_output_len(&self) -> Result<usize, CapacityError>
pub fn max_reset_output_len(&self) -> Result<usize, CapacityError>
Returns the maximum target units emitted when resetting stream state.
§Returns
Returns a conservative upper bound valid for every reachable converter state.
§Errors
Returns CapacityError::OutputLengthOverflow when component-bound
arithmetic overflows.
Sourcepub fn reset(
&mut self,
output: &mut [E::Unit],
output_index: usize,
) -> Result<usize, TranscodeConvertErrorOf<D, E>>
pub fn reset( &mut self, output: &mut [E::Unit], output_index: usize, ) -> Result<usize, TranscodeConvertErrorOf<D, E>>
Clears retained pending output, resets target state, and then encodes source-side reset values.
D::Value: Default is required so the engine can allocate scratch
storage for any stream-start values the source decoder emits through
Codec::decode_reset before they are
piped through the target encoder. Stateless decoders never reach the
allocating path; the bound is consulted only when
Codec::MAX_DECODE_RESET_VALUES
is non-zero.
§Parameters
output: Target unit slice for stream-start output.output_index: Absolute target output index where writing starts.
§Returns
Returns the number of target units written while resetting component state.
§Errors
Returns a converter error when the output range is invalid or too small, or when decoder or encoder reset processing fails.
Sourcepub fn transcode(
&mut self,
input: &[D::Unit],
input_index: usize,
output: &mut [E::Unit],
output_index: usize,
) -> Result<TranscodeProgress, TranscodeConvertErrorOf<D, E>>
pub fn transcode( &mut self, input: &[D::Unit], input_index: usize, output: &mut [E::Unit], output_index: usize, ) -> Result<TranscodeProgress, TranscodeConvertErrorOf<D, E>>
Converts source units into target units.
This method’s signature does not require D::Value: Default. Starting
and finishing a usable stream through the current reset/finish APIs
still requires that bound. Removing the lifecycle scratch bound is
deferred.
§Parameters
input: Source unit slice.input_index: Absolute source index where conversion starts.output: Target unit slice.output_index: Absolute target index where writing starts.
§Returns
Returns conversion progress for consumed/produced counters and stop reason.
§Errors
Returns converter error when source or target indices are invalid, or when decoding/encoding fails under current policy.
Sourcepub fn transcode_eof(
&mut self,
input: &[D::Unit],
input_index: usize,
output: &mut [E::Unit],
output_index: usize,
) -> Result<TranscodeProgress, TranscodeConvertErrorOf<D, E>>
pub fn transcode_eof( &mut self, input: &[D::Unit], input_index: usize, output: &mut [E::Unit], output_index: usize, ) -> Result<TranscodeProgress, TranscodeConvertErrorOf<D, E>>
Converts source units after the caller has established end of input.
§Parameters
input: Final source unit slice; the caller must not supply more input later.input_index: Absolute index at which unread source units begin.output: Target unit slice receiving converted values.output_index: Absolute index at which target output begins.
§Returns
Returns consumed and produced counts with the conversion stop reason.
§Errors
Returns a converter error for invalid indices, invalid or incomplete final source input, or a decoder/encoder failure under the current policy.
Sourcepub fn finish(
&mut self,
output: &mut [E::Unit],
output_index: usize,
) -> Result<usize, TranscodeConvertErrorOf<D, E>>
pub fn finish( &mut self, output: &mut [E::Unit], output_index: usize, ) -> Result<usize, TranscodeConvertErrorOf<D, E>>
Finishes internally retained output after EOF.
Finalization delegates to the reusable converter engine. It drains retained pending output, encodes source-side decode flush values, and then finishes target-side encode hook state.
§Parameters
output: Target unit slice for finalization output.output_index: Absolute target output index where writing starts.
§Returns
Returns the number of target units written by finalization.
§Errors
Returns a converter error for invalid output indices, insufficient output capacity, or failures while draining pending values or finishing either codec.
Trait Implementations§
Source§impl<D, E> Debug for CodecTranscodeConverter<D, E>where
D: Codec,
E: Codec<Value = D::Value>,
TranscodeConvertEngine<D, E, CodecTranscodeDecodeHooks, CodecTranscodeEncodeHooks>: Debug,
impl<D, E> Debug for CodecTranscodeConverter<D, E>where
D: Codec,
E: Codec<Value = D::Value>,
TranscodeConvertEngine<D, E, CodecTranscodeDecodeHooks, CodecTranscodeEncodeHooks>: Debug,
Source§impl<D, E> Default for CodecTranscodeConverter<D, E>where
D: Codec,
E: Codec<Value = D::Value>,
TranscodeConvertEngine<D, E, CodecTranscodeDecodeHooks, CodecTranscodeEncodeHooks>: Default,
impl<D, E> Default for CodecTranscodeConverter<D, E>where
D: Codec,
E: Codec<Value = D::Value>,
TranscodeConvertEngine<D, E, CodecTranscodeDecodeHooks, CodecTranscodeEncodeHooks>: Default,
Source§impl<D, E> TranscodeConverter for CodecTranscodeConverter<D, E>
impl<D, E> TranscodeConverter for CodecTranscodeConverter<D, E>
Source§type DecodeError = <D as Codec>::DecodeError
type DecodeError = <D as Codec>::DecodeError
Domain error reported by the source codec.
Source§type EncodeError = <E as Codec>::EncodeError
type EncodeError = <E as Codec>::EncodeError
Domain error reported by the target codec.
Source§impl<D, E> Transcoder for CodecTranscodeConverter<D, E>
impl<D, E> Transcoder for CodecTranscodeConverter<D, E>
Source§type Error = TranscodeConvertError<<D as Codec>::DecodeError, <E as Codec>::EncodeError, <D as Codec>::Value>
type Error = TranscodeConvertError<<D as Codec>::DecodeError, <E as Codec>::EncodeError, <D as Codec>::Value>
Conversion failures retaining decoder, encoder, and pending-value context.
Source§fn max_transcode_output_len(
&self,
input_len: usize,
) -> Result<usize, CapacityError>
fn max_transcode_output_len( &self, input_len: usize, ) -> Result<usize, CapacityError>
Returns an upper bound for target units produced from input_len units.
§Parameters
input_len: Source units the caller plans to convert.
§Returns
Returns a conservative upper bound for produced target units.
§Errors
Returns CapacityError::OutputLengthOverflow when component-bound
arithmetic overflows.
Source§fn max_finish_output_len(&self) -> Result<usize, CapacityError>
fn max_finish_output_len(&self) -> Result<usize, CapacityError>
Returns the maximum target units emitted by finishing internal state.
§Returns
Returns a conservative upper bound valid for every reachable converter state.
§Errors
Returns CapacityError::OutputLengthOverflow when component-bound
arithmetic overflows.
Source§fn max_reset_output_len(&self) -> Result<usize, CapacityError>
fn max_reset_output_len(&self) -> Result<usize, CapacityError>
Returns the maximum target units emitted when resetting stream state.
§Returns
Returns a conservative upper bound valid for every reachable converter state.
§Errors
Returns CapacityError::OutputLengthOverflow when component-bound
arithmetic overflows.
Source§fn reset(
&mut self,
output: &mut [E::Unit],
output_index: usize,
) -> Result<usize, TranscodeConvertErrorOf<D, E>>
fn reset( &mut self, output: &mut [E::Unit], output_index: usize, ) -> Result<usize, TranscodeConvertErrorOf<D, E>>
Clears retained pending output, resets component state, and emits stream-start encode output.
§Parameters
output: Target unit slice for stream-start output.output_index: Absolute target output index where writing starts.
§Returns
Returns the number of target units written while resetting component state.
§Errors
Returns a converter error when the output range is invalid or too small, or when decoder or encoder reset processing fails.
Source§fn transcode(
&mut self,
input: &[D::Unit],
input_index: usize,
output: &mut [E::Unit],
output_index: usize,
) -> Result<TranscodeProgress, TranscodeConvertErrorOf<D, E>>
fn transcode( &mut self, input: &[D::Unit], input_index: usize, output: &mut [E::Unit], output_index: usize, ) -> Result<TranscodeProgress, TranscodeConvertErrorOf<D, E>>
Converts source units into target units.
§Parameters
input: Source unit slice.input_index: Absolute source index where conversion starts.output: Target unit slice.output_index: Absolute target index where writing starts.
§Returns
Returns conversion progress for consumed/produced counters and stop reason.
§Errors
Returns converter error when source or target indices are invalid, or when decoding/encoding fails under current policy.
Source§fn transcode_eof(
&mut self,
input: &[D::Unit],
input_index: usize,
output: &mut [E::Unit],
output_index: usize,
) -> Result<TranscodeProgress, TranscodeConvertErrorOf<D, E>>
fn transcode_eof( &mut self, input: &[D::Unit], input_index: usize, output: &mut [E::Unit], output_index: usize, ) -> Result<TranscodeProgress, TranscodeConvertErrorOf<D, E>>
Transcodes an input segment while marking it as the end of the stream.
This forwarding implementation delegates to the converter’s EOF-aware operation so buffered decoder state can be finalized before encoding.
§Parameters
input: Final source unit slice; the caller must not supply more input later.input_index: Absolute index at which unread source units begin.output: Target unit slice receiving converted values.output_index: Absolute index at which target output begins.
§Returns
Returns consumed and produced counts with the conversion stop reason.
§Errors
Returns a converter error for invalid indices, invalid or incomplete final source input, or a decoder/encoder failure under the current policy.
Source§fn finish(
&mut self,
output: &mut [E::Unit],
output_index: usize,
) -> Result<usize, TranscodeConvertErrorOf<D, E>>
fn finish( &mut self, output: &mut [E::Unit], output_index: usize, ) -> Result<usize, TranscodeConvertErrorOf<D, E>>
Finishes internally retained output after EOF.
§Parameters
output: Target unit slice for finalization output.output_index: Absolute target output index where writing starts.
§Returns
Returns the number of target units written by finalization.
§Errors
Returns a converter error for invalid output indices, insufficient output capacity, or failures while draining pending values or finishing either codec.
Source§fn max_total_output_len(&self, input_len: usize) -> Result<usize, CapacityError>
fn max_total_output_len(&self, input_len: usize) -> Result<usize, CapacityError>
reset -> transcode_eof -> finish
stream. Read more