Module codec 

Codec contracts and built-in codecs.

Codec contracts and built-ins

A codec owns one field’s exact wire representation. Layout generation owns physical order, represented extent, framing, bounded ranges, and caller storage; consumers own domain policy such as magic values, reserved ranges, checksums, and cross-field rules.

Choose a contract

• Implement FixedCodec when every value has one compile-time, nonzero width. Decode every exact-width bit pattern; do not make application semantics a required structural-validation step. Declare such a codec directly with name: path::Codec;.
• Implement PrefixCodec when bounded structural validation must discover the nonzero encoded width from available input. validate_prefix receives the remaining bytes and decoding then receives exactly the accepted span. Declare it with name: variable(path);.
• Implement EncodePlan as the result of fallible plan. Its encoded_len and write_into must describe the same representation, and writing into its exact-sized destination must be infallible.

A self-delimiting view retains its accepted extent. Its raw getter returns those original bytes, including a legal noncanonical encoding; it does not reconstruct them from the decoded value. A self-delimiting plan may choose a canonical encoding for a value.

Builder boundary

Generated setters and builders use plans to preserve atomic caller-buffer updates. Before a builder writes, it completes all fallible planning, plan-length checks, derivations, endpoint calculations, arithmetic, and capacity checks. A returned build error therefore leaves the complete supplied output slice unchanged.

Generated code defensively verifies claims that affect safe slicing and atomicity, but a custom codec that violates its trait laws is still broken. In particular:

• FixedCodec::WIDTH is nonzero, and every successful fixed plan is exactly that width.
• PrefixCodec::validate_prefix returns a nonzero extent within its supplied input.
• Every successful self-delimiting plan is nonempty.
• A successful plan encodes the semantic value it planned.

Keep framing between fields, range-source algebra, derived endpoints, and protocol validation outside a codec. A self-delimiting codec discovers its own field width; it is not a source for a later dynamic byte range.

Built-ins

This module provides U8 and I8, big- and little-endian unsigned 16/24/32/64/128-bit codecs, big- and little-endian signed 16/32/64/128-bit codecs, and Bytes<N> for an opaque exact-width borrowed span.

Unsigned 24-bit codecs use u32 semantic values and reject values greater than 0x00ff_ffff while planning. Bytes<N> requires N > 0; building checks that an input has exactly N bytes before mutation.

Structs

BeI16

Big-endian i16 codec.

BeI32

Big-endian i32 codec.

BeI64

Big-endian i64 codec.

BeI128

Big-endian i128 codec.

BeU16

Big-endian u16 codec.

BeU24

Big-endian unsigned 24-bit integer codec over u32.

BeU32

Big-endian u32 codec.

BeU64

Big-endian u64 codec.

BeU128

Big-endian u128 codec.

Bytes

A borrowed fixed-width span of wire bytes with no content interpretation.

ExactWidthError

Error returned when an exact-width byte value has the wrong length.

I8

One-byte signed integer codec.

LeI16

Little-endian i16 codec.

LeI32

Little-endian i32 codec.

LeI64

Little-endian i64 codec.

LeI128

Little-endian i128 codec.

LeU16

Little-endian u16 codec.

LeU24

Little-endian unsigned 24-bit integer codec over u32.

LeU32

Little-endian u32 codec.

LeU64

Little-endian u64 codec.

LeU128

Little-endian u128 codec.

PrefixExtent

The nonzero extent occupied by a validated encoded prefix.

U8

One-byte unsigned integer codec.

U24RangeError

Error returned when a u32 does not fit in an unsigned 24-bit integer.

Traits

EncodePlan

A completed, infallible encoding operation.

FixedCodec

A codec whose encoded representation always has one fixed width.

PrefixCodec

A codec whose encoded representation occupies a variable-length prefix.