Crate qubit_codec

Expand description

§qubit-codec

Domain-neutral codec traits and buffer conversion primitives.

qubit-codec is the foundation shared by the Qubit binary, text, misc, and I/O codec crates. It defines the small contracts that concrete format crates build on, without shipping concrete binary or text formats itself.

§Overview

The crate provides:

Codec for low-level single-value codecs over caller-managed buffers.
CodecValueEncoder and CodecValueDecoder for owned one-value convenience APIs.
CodecTranscodeEncoder, CodecTranscodeDecoder, and CodecTranscodeConverter for strict streaming adapters around a Codec.
engine::TranscodeEncodeEngine, engine::TranscodeDecodeEngine, and engine::TranscodeConvertEngine for policy-aware buffered loops.
engine::TranscodeEncodeHooks and engine::TranscodeDecodeHooks for replacement, skip, report, finish, and reset policy decisions.
Transcoder, TranscodeProgress, and TranscodeStatus for caller-managed streaming conversion.
ValueEncoder and ValueDecoder for whole-value convenience APIs.
ByteOrder, ByteOrderSpec, BigEndian, LittleEndian, and NativeEndian for shared byte-order metadata.
qubit_utils::nonzero() for checked NonZeroUsize construction shared by codec implementations.

Concrete codecs live in sibling crates such as qubit-codec-binary, qubit-codec-text, and qubit-codec-misc.

§Choosing an Abstraction

Pick the smallest layer that matches the shape of the problem:

What are you writing?

+-- A codec for one logical value
|   (UTF-8 char, LEB128 integer, fixed-width scalar, ...)
|       -> implement Codec
|
+-- A whole-value codec where a single-value quantum is not useful
|   (Base64 text, percent encoding, escaped strings, ...)
|       -> implement ValueEncoder<Input> / ValueDecoder<Input>
|
+-- A strict streaming wrapper around an existing Codec
|       -> use CodecTranscodeDecoder<C> / CodecTranscodeEncoder<C>
|          / CodecTranscodeConverter<D, E>
|
+-- An owned-output wrapper around an existing Codec
|       -> use CodecValueEncoder<C> / CodecValueDecoder<C>
|
+-- A streaming codec with policy decisions
    (skip, replace, count, report, finish output, ...)
        -> implement engine::TranscodeDecodeHooks<C>
           / engine::TranscodeEncodeHooks<C>
           and use engine::TranscodeDecodeEngine<C, H>
           / engine::TranscodeEncodeEngine<C, H>

Unit-to-unit conversions, such as UTF-8 bytes to UTF-16 units, compose a decode side and an encode side. Use CodecTranscodeConverter for a strict pipeline and engine::TranscodeConvertEngine when either side needs policy hooks.

§Layer Overview

concrete I/O crates
  |
TranscodeDecodeInput / TranscodeEncodeOutput  [feature = "io"]
  |
Transcode*Engine + Transcode*Hooks
CodecTranscodeDecoder / Encoder / Converter
  |
Transcoder + TranscodeProgress + TranscodeStatus
ValueEncoder / ValueDecoder
  |
Codec

Implementing further up the stack does not require rewriting the lower layers. The adapter types turn any suitable Codec into owned-value or streaming APIs. Drop down to the engine and hook layer when the codec needs continuous-stream semantics or policy decisions.

Modules§

engine: Policy-aware transcode engines, hooks, contexts, and policy actions.

Macros§

register_value_codec: Registers a default-constructible bidirectional string codec.

Structs§

AsyncTranscodeDecodeInput: Decodes an asynchronous unit stream into values.
AsyncTranscodeEncodeOutput: Buffers asynchronous transcoder output while preserving pending units.
BigEndian: Type-level marker for big-endian byte order.
CodecTranscodeConverter: Converts source units to target units through a decoded value by using codecs.
CodecTranscodeDecoder: Decodes encoded units into caller-provided value buffers by using a Codec.
CodecTranscodeEncoder: Encodes values into caller-provided output units by using a Codec.
CodecValueDecoder: Decodes one encoded unit slice into one owned value by using a Codec.
CodecValueEncoder: Encodes one borrowed value into owned units by using a Codec.
DecodeLifecycleOutput: Values produced by decode reset, the main decode, and decode finish.
DecodeLifecycleProgress: Main decoded value and lifecycle output lengths written to caller storage.
LittleEndian: Type-level marker for little-endian byte order.
NativeEndian: Type-level marker for native-endian byte order.
TranscodeDecodeInput: Decodes an Input unit stream into an Input value stream.
TranscodeEncodeOutput: Encodes an Output value stream into an Output unit stream.
TranscodeProgress: Counts how much work a crate::Transcoder completed before returning.
ValueCodecDescriptor: An immutable, safely erased bidirectional string codec for one value type.
ValueCodecId: A validated, process-independent value-codec identifier.
ValueCodecRegistration: One statically linked value-codec implementation.
ValueCodecRegistrationSource: Source location for one linked value-codec registration.
ValueCodecRegistry: An immutable value-codec registry sorted by stable ID.

Enums§

AsyncTranscodeDecodeStep: Result of one cancellation-safe asynchronous decode operation.
ByteOrder: Runtime byte order selector.
CapacityError: Error reported by output-capacity planning APIs.
DecodeFailure: Failure reported by crate::Codec::decode.
TranscodeContractError: Error reported when a transcoder returns inconsistent progress.
TranscodeConvertError: Error reported by a unit-to-unit transcode conversion.
TranscodeDecodeError: Error reported by a decode-oriented transcode operation.
TranscodeDomainError: Domain-specific codec, charset, or policy error with transcode context.
TranscodeEncodeError: Error reported by an encode-oriented transcode operation.
TranscodeFailure: Framework-level failure reported by a transcode operation.
TranscodeStatus: Reports why a crate::Transcoder stopped converting input.
ValueCodecExecutionError: Failure produced by a type-erased value-codec invocation.
ValueCodecIdError: A stable value-codec ID protocol violation.
ValueCodecRegistryError: Failure while freezing a value-codec registry.

Traits§

ByteOrderSpec: Describes a type-level byte order.
Codec: Encodes and decodes one value or codec quantum against a unit buffer.
TranscodeConverter: Converts encoded units of one representation into encoded units of another.
TranscodeDecoder: Decodes encoded units into logical values over caller-provided buffers.
TranscodeEncoder: Encodes logical values into encoded units over caller-provided buffers.
Transcoder: Converts one logical stream of input units into one logical stream of output units.
ValueDecoder: Decodes a borrowed input value into an owned representation.
ValueEncoder: Encodes a borrowed input value into an owned representation.

Type Aliases§

TranscodeConvertErrorOf: Convert transcode error for a codec-backed converter.
TranscodeDecodeErrorOf: Decode transcode error for a codec-backed decoder.
TranscodeEncodeErrorOf: Encode transcode error for a codec-backed encoder.