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_uniformover the exact alphabet size (from#[bits = N]ranges, enum cardinality, or primitive alphabets);crate::Model::from_weightswith 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§
- Entropy
Config - rANS entropy profile wrapping a
Config. - Field
Model - One per-field static model derived from a
crate::Reflectshape. - Model
- One static frequency model over an exact symbol alphabet.
- Rans
Decoder - Reverse-order rANS decoder over a payload produced by
RansEncoder. - Rans
Encoder - Forward rANS encoder. The emitted byte stream is reversed on
finish. - Schema
Model - Schema-derived collection of per-field static models.
Constants§
- RANS_M
- Total frequency mass of every model.