qubit_codec/transcode/
transcode_encoder.rs

1// =============================================================================
2//    Copyright (c) 2026 Haixing Hu.
3//
4//    SPDX-License-Identifier: Apache-2.0
5//
6//    Licensed under the Apache License, Version 2.0.
7// =============================================================================
8//! Semantic marker trait for buffered encoders.
9
10use super::TranscodeEncodeError;
11use super::Transcoder;
12
13/// Encodes logical values into encoded units over caller-provided buffers.
14///
15/// `TranscodeEncoder` refines [`Transcoder`] for implementations whose
16/// input is the logical value stream and whose output is the encoded unit
17/// stream. The trait adds no methods; it exists to make generic bounds
18/// distinguish encoding direction from decoding and unit-to-unit conversion.
19///
20/// The word "buffered" describes the caller-managed buffer and progress model.
21/// It does not require the implementor to own an internal buffer. An encoder
22/// may retain consumed input internally, but [`Transcoder::transcode`] must
23/// consume every visible input value before returning
24/// [`crate::TranscodeStatus::Complete`] and must never return
25/// [`crate::TranscodeStatus::NeedInput`]. It returns
26/// [`crate::TranscodeStatus::NeedOutput`] when more output capacity is needed;
27/// [`Transcoder::finish`] emits any retained output after the caller has
28/// supplied the complete logical input stream.
29///
30/// # Examples
31///
32/// ```
33/// use core::convert::Infallible;
34/// use core::num::NonZeroUsize;
35///
36/// use qubit_codec::Codec;
37/// use qubit_codec::CodecTranscodeEncoder;
38/// use qubit_codec::DecodeFailure;
39/// use qubit_codec::TranscodeEncoder;
40/// use qubit_codec::Transcoder;
41///
42/// struct ByteCodec;
43/// impl Codec for ByteCodec {
44///     type Value = u8;
45///     type Unit = u8;
46///     type DecodeError = Infallible;
47///     type EncodeError = Infallible;
48///     const MIN_UNITS_PER_VALUE: usize = 1;
49///     const MAX_ENCODE_UNITS_PER_VALUE: usize = 1;
50///     const MAX_DECODE_UNITS_PER_VALUE: usize = 1;
51///
52///     unsafe fn decode(&mut self, input: &[u8], index: usize)
53///         -> Result<(u8, NonZeroUsize), DecodeFailure<Infallible>>
54///     {
55///         Ok((input[index], NonZeroUsize::MIN))
56///     }
57///
58///     unsafe fn encode(&mut self, value: &u8, output: &mut [u8], index: usize)
59///         -> Result<usize, Infallible>
60///     {
61///         output[index] = *value;
62///         Ok(1)
63///     }
64/// }
65///
66/// fn accepts_encoder<E: TranscodeEncoder>(_: &E) {}
67/// let mut encoder = CodecTranscodeEncoder::new(ByteCodec);
68/// accepts_encoder(&encoder);
69/// let mut output = [0; 2];
70/// let written = encoder.transcode_complete_into(&[1, 2], &mut output).unwrap();
71/// assert_eq!(written, 2);
72/// assert_eq!(output, [1, 2]);
73/// ```
74pub trait TranscodeEncoder:
75    Transcoder<Error = TranscodeEncodeError<Self::EncodeError, <Self as Transcoder>::Input>>
76{
77    /// Error type produced by the encoding implementation for a logical
78    /// input value.
79    ///
80    /// The transcoder's [`Transcoder::Error`] carries this type inside
81    /// [`TranscodeEncodeError::Domain`]; framework failures and unencodable
82    /// values are represented by separate variants.
83    type EncodeError;
84}
qubit_codec/transcode/transcode_encoder.rs

qubit_codec/transcode/
transcode_encoder.rs
