Trait Codec 

pub unsafe trait Codec {
    type Value: Copy + Default;
    type Unit: Copy + Default;
    type DecodeError;
    type EncodeError;

    // Required methods
    fn min_units_per_value(&self) -> NonZeroUsize;
    fn max_units_per_value(&self) -> NonZeroUsize;
    unsafe fn encode(
        &mut self,
        value: &Self::Value,
        output: &mut [Self::Unit],
        index: usize,
    ) -> Result<NonZeroUsize, Self::EncodeError>;
    unsafe fn decode(
        &mut self,
        input: &[Self::Unit],
        index: usize,
    ) -> Result<(Self::Value, NonZeroUsize), Self::DecodeError>;

    // Provided methods
    fn can_encode_value(&self, _value: &Self::Value) -> bool { ... }
    fn encode_len(&self, _value: &Self::Value) -> NonZeroUsize { ... }
    fn max_encode_reset_units(&self) -> usize { ... }
    fn max_decode_flush_values(&self) -> usize { ... }
    unsafe fn encode_reset(
        &mut self,
        _output: &mut [Self::Unit],
        _index: usize,
    ) -> Result<usize, Self::EncodeError> { ... }
    unsafe fn decode_flush(
        &mut self,
        _output: &mut [Self::Value],
        _index: usize,
    ) -> Result<usize, Self::DecodeError> { ... }
}

Encodes and decodes one value or codec quantum against a unit buffer.

Codec is the lowest-level abstraction in the codec stack. It is intended for hot paths that have already validated buffer capacity and want to avoid constructing subslices for every value. Higher-level transcoders and convenience APIs are responsible for checked buffer management and owned output allocation.

min_units_per_value and max_units_per_value describe the representation width bounds for one value. The minimum is a lower-bound hint for checked layers: if fewer than this many units are available, no complete value can exist, so a streaming caller can request more input, report an incomplete EOF tail. For decoding, this minimum is the smallest safety precondition checked callers must satisfy before entering decode. The maximum is a value-independent upper bound callers can use for coarse capacity planning. For encoding a known value, checked callers should reserve the exact encode_len instead of pessimistically reserving the maximum width.

A codec may keep decode-side and encode-side stream state. That state is an implementation detail owned by the codec. Callers do not snapshot or restore it; implementations must keep their own state internally consistent across every public operation, including operations that return Err.

Associated Types

• Value: Logical value decoded from or encoded into the buffer. This may be a scalar such as u8, u16, u64, a char, or a fixed quantum such as [u8; 3]. The trait can model other small value objects, but it is intentionally aimed at copyable value-domain types rather than owned resource handles or heap-backed aggregates. Implementations must provide Copy and Default so checked adapters can pass values by copy and allocate flush scratch buffers.
• Unit: Buffer unit used by the encoded representation. Implementations are typically scalar storage units such as u8, u16, or char. Implementations must provide Copy and Default so checked adapters can allocate output unit buffers and initialize caller-owned scratch storage.

Safety

Implementors must uphold the safety contract documented by decode, encode, encode_reset, and decode_flush. In particular, unchecked implementations must not read or write outside the caller-provided ranges. Implementations should use debug_assert! to state the expected buffer bounds at the unchecked entry point.

Implementations must also guarantee that min_units_per_value is less than or equal to max_units_per_value. Both bounds are non-zero by type, and max_units_per_value must be a valid upper bound for one complete encoded value or codec quantum. Checked adapters assert this invariant before using codec-provided bounds.

Required Associated Types

type Value: Copy + Default

The type of logical values decoded from or encoded into the buffer.

type Unit: Copy + Default

The type of buffer units used by the encoded representation.

type DecodeError

The type of errors reported when decoding malformed units.

type EncodeError

The type of errors reported when encoding an unsupported value.

Required Methods

fn min_units_per_value(&self) -> NonZeroUsize

Returns the minimum possible unit count for one encoded value.

This is a lower bound used by checked callers for planning and fast impossibility checks. If a streaming decoder has fewer than this many readable units, no complete value can be present at the current position. If the stream has reached EOF, such a tail is necessarily incomplete; otherwise the caller should read more input. Similarly, an encoder or transcoder can avoid calling into the codec when the remaining output capacity is smaller than this lower bound.

This value does not prove that encoding will fit. For variable-width representations, a value may require more units, up to max_units_per_value. For decoding, this is the minimum safety precondition required by decode; if fewer units are available, a checked caller must request more input or report a closed incomplete tail without calling into the unchecked method.

Returns

Returns a non-zero lower bound for one complete value. Variable-width codecs such as LEB128 should return the shortest valid representation length. For example, a UTF-16 byte codec can return 2, while its maximum is 4 because a surrogate pair needs four bytes.

fn max_units_per_value(&self) -> NonZeroUsize

Returns the maximum non-zero unit count needed to encode or decode one value.

Returns

Returns an upper bound for one complete value or codec quantum.

unsafe fn encode( &mut self, value: &Self::Value, output: &mut [Self::Unit], index: usize, ) -> Result<NonZeroUsize, Self::EncodeError>

Encodes one borrowed value into output starting at index.

Parameters

• value: Value to encode.
• output: Destination unit buffer.
• index: Start index in output.

Returns

Returns the non-zero number of written units. A successful encode always emits at least one unit; stateful encoders that need to defer output should report that intent through a custom encode error instead of returning a zero count.

Errors

Returns Self::EncodeError for encode-side state or representation failures other than a value being outside the codec’s encodable domain. Checked callers reject values for which can_encode_value returns false before entering this unsafe method. Implementations must leave their internal state consistent when returning an error.

Safety

The caller must guarantee that can_encode_value returned true for value, and that the implementation can write at least encode_len units for the same value and codec state starting at index. On success, implementations must return that exact written unit count, and the count must be no larger than max_units_per_value.

unsafe fn decode( &mut self, input: &[Self::Unit], index: usize, ) -> Result<(Self::Value, NonZeroUsize), Self::DecodeError>

Decodes one value from input starting at index.

Parameters

• input: Source unit buffer.
• index: Start index in input.

Returns

Returns the decoded value and the non-zero number of consumed units.

Errors

Returns Self::DecodeError when the units are malformed, non-canonical, incomplete, or otherwise invalid for this codec. The concrete error type carries the codec-specific reason and context. Implementations must leave their internal state consistent when returning an error.

Safety

The caller must guarantee that index is a valid boundary in input and that at least min_units_per_value units are readable from index. Implementations must not read beyond the currently available units under that precondition. They may return Self::DecodeError when those units are a valid but incomplete prefix.

On success, implementations must return a consumed unit count no larger than the available input. The return type guarantees that successful decoding always consumes at least one unit. Implementations should use debug_assert! to state these unchecked entry-point assumptions.

Provided Methods

fn can_encode_value(&self, _value: &Self::Value) -> bool

Returns whether value is in this codec’s encodable value domain.

The default implementation returns true, which is correct for codecs whose Value type contains only values they can encode. Codecs whose logical value type is broader than their representation domain, such as an ASCII codec with Value = char, must override this method.

Checked encoder adapters call this method before querying encode_len or entering the unsafe encode method. Direct unsafe callers must do the same.

Parameters

• value: Value whose encodability is queried.

Returns

Returns true when value may be passed to encode_len and encode.

fn encode_len(&self, _value: &Self::Value) -> NonZeroUsize

Returns the exact non-zero unit count this codec will write when encoding value.

The default implementation returns max_units_per_value, which is the conservative bound callers can use when no specific value is available. Fixed-width codecs do not need to override this method.

Variable-width codecs (LEB128, UTF-8, GB18030, …) should override this to report the true encoded length for encodable values. Doing so lets buffered adapters and stream writers reserve only what is actually needed and enables capacity probing without performing the encode. Default codec-backed encoders use this exact value for per-value output capacity. The contract requires callers to use this method only when can_encode_value returned true for the same value. Under that precondition, the returned length must equal the unit count encode writes for the same value under the same codec state, and must never exceed max_units_per_value.

Parameters

• value: Value whose encoded length is queried.

Returns

Returns the non-zero unit count encode will write for an encodable value.

fn max_encode_reset_units(&self) -> usize

Returns the maximum unit count emitted when resetting encode state.

Stateful encoders may need a stream-start sequence, such as a byte order mark, before the first encoded value. Buffered encoders use this bound to reserve output capacity before calling encode_reset.

Returns

Returns the finite reset-output upper bound. Stateless codecs should use the default 0.

fn max_decode_flush_values(&self) -> usize

Returns the maximum value count emitted when flushing decode state.

Stateful decoders may need to produce final values at EOF from retained state. Buffered decoders use this bound to reserve output capacity before calling decode_flush.

Returns

Returns the finite flush-output upper bound. Stateless codecs should use the default 0.

unsafe fn encode_reset( &mut self, _output: &mut [Self::Unit], _index: usize, ) -> Result<usize, Self::EncodeError>

Emits stream-start output and resets encode-side state.

Parameters

• output: Destination unit buffer.
• index: Start index in output.

Returns

Returns the number of reset units written.

Errors

Returns Self::EncodeError when reset output cannot be emitted. Implementations must leave their internal state consistent when returning an error.

Safety

The caller must guarantee that the implementation can write up to max_encode_reset_units units starting at index.

unsafe fn decode_flush( &mut self, _output: &mut [Self::Value], _index: usize, ) -> Result<usize, Self::DecodeError>

Flushes decode-side EOF state into output.

Parameters

• output: Destination value buffer.
• index: Start index in output.

Returns

Returns the number of flushed values written.

Errors

Returns Self::DecodeError when retained decode state is invalid at EOF. Implementations must leave their internal state consistent when returning an error.

Safety

The caller must guarantee that the implementation can write up to max_decode_flush_values values starting at index.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors