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.

§Features

The default feature set is empty. Features are independent.

Feature	Capability
`io`	Synchronous and asynchronous buffered bridges for `qubit-io`.
`json`	Whole-value Serde JSON codecs for strings and bytes. Encoding requires `Serialize`; decoding requires `DeserializeOwned`.
`registry`	Static string-wire and bytes-wire codec registration, macros, and runtime lookup. Registrations cannot be added at runtime.
`json` + `registry`	Built-in registrations for `serde_json::Value` only. Custom DTOs require their own descriptor and unique registry ID.

See the English user guide or the Chinese user guide for setup, lifecycle handling, and registry examples.

§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_bytes_codec: Registers a default-constructible bidirectional bytes codec.
register_value_string_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.
JsonBytesValueCodec: Encodes and decodes one serializable value through JSON bytes.
JsonBytesValueDecoder: Decodes JSON bytes into one owned value via serde_json. Its stateless marker implements Clone, Copy, and Default without requiring those traits on T.
JsonBytesValueEncoder: Encodes one serializable value into UTF-8 JSON bytes via serde_json. Its stateless marker implements Clone, Copy, and Default without requiring those traits on T.
JsonStringValueCodec: Encodes and decodes one serializable value through UTF-8 JSON strings.
JsonStringValueDecoder: Decodes one JSON string into an owned value via serde_json. Its stateless marker implements Clone, Copy, and Default without requiring those traits on T.
JsonStringValueEncoder: Encodes one serializable value into a UTF-8 JSON string via serde_json. Its stateless marker implements Clone, Copy, and Default without requiring those traits on T.
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.
ValueBytesCodecDescriptor: An immutable, safely erased bidirectional bytes 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.
ValueStringCodecDescriptor: An immutable, safely erased bidirectional string codec for one value type.

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.

Constants§

JSON_BYTES_VALUE_CODEC_ID: Stable registry ID for JSON bytes value codecs.
JSON_STRING_VALUE_CODEC_ID: Stable registry ID for JSON string value codecs.

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.
ValueBytesCodecRegistration: A registration for a value codec that encodes to and decodes from bytes.
ValueBytesCodecRegistry: An immutable bytes-wire value-codec registry sorted by stable ID.
ValueStringCodecRegistration: A registration for a value codec that encodes to and decodes from strings.
ValueStringCodecRegistry: An immutable string-wire value-codec registry sorted by stable ID.