Skip to main content

Module rans

Module rans 

Source
Available on crate feature entropy only.
Expand description

Static-model rANS entropy coding driven by schema metadata. Static-model rANS entropy coding driven by compile-time schema metadata.

This module is a from-scratch implementation of range Asymmetric Numeral Systems (rANS, Duda 2014) with a 64-bit state and 16-bit renormalization. It is the entropy-coding core behind the entropy feature and is deliberately not a wrapper around zstd, LZ4, or any external codec: there is no C dependency, no dictionary transmission, and the coder is fully no_std + alloc.

§Static models, no dictionary

The model is a frequency table over an exact symbol alphabet. Both sides of a link derive the same model deterministically:

  • crate::Model::from_uniform over the exact alphabet size (from #[bits = N] ranges, enum cardinality, or primitive alphabets);
  • crate::Model::from_weights with caller-supplied priors (still static, still transmitted implicitly — the decoder reconstructs the same table from the same weights).

crate::SchemaModel::from_reflect walks a Reflect shape and produces one static model per field. Because the schema is compiled into both sides, no frequency table crosses the wire. For long streams, the coding rate approaches the model rate, subject to quantized frequencies and frame overhead: an enum with 3 variants costs log2(3) ≈ 1.585 bits per symbol instead of rounding up to 2.

§Determinism and verification

Encoding is canonical: the same symbols and models always produce the same bytes, and decoding is its exact inverse. Verification is therefore hash-free: after decoding, the decoder re-encodes the decoded symbols with the same models and requires the result to match the frame’s stored payload and final state byte-for-byte. A frame is accepted only when it is the canonical encoding of the payload it decodes to.

This is a representation check, not authentication or a checksum. Replacing a codeword with another valid codeword can change the decoded data and pass replay. No accidental-corruption detection probability is claimed. Raw fallback has only framing/length checks; forcing coded frames does not establish an integrity boundary. Use a trusted digest, MAC or AEAD as needed.

Replay is enabled by default and adds an encoding pass. The option without_replay_verification disables only this canonicality check.

Structs§

EntropyConfig
rANS entropy profile wrapping a Config.
FieldModel
One per-field static model derived from a crate::Reflect shape.
Model
One static frequency model over an exact symbol alphabet.
RansDecoder
Reverse-order rANS decoder over a payload produced by RansEncoder.
RansEncoder
Forward rANS encoder. The emitted byte stream is reversed on finish.
SchemaModel
Schema-derived collection of per-field static models.

Constants§

RANS_M
Total frequency mass of every model.