Struct EntropyModel

Source

pub struct EntropyModel {
    pub scale_bits: u8,
    pub frequencies: Vec<u32>,
}

Expand description

A normalized frequency table over the byte alphabet.

Fields§

§scale_bits: u8

Number of scale bits; the table sums to 1 << scale_bits.

§frequencies: Vec<u32>

Exactly ALPHABET entries; sum == 1 << scale_bits.

Implementations§

Source §

impl EntropyModel

Source

pub fn total(&self) -> u32

Total frequency (== 1 << scale_bits).

Source

pub fn from_counts(counts: &[u64; 256], scale_bits: u8) -> Result<EntropyModel>

Canonical normalization of observed symbol counts into a frequency table.

Requirements (all hold):

integer-only; no floating point anywhere;
deterministic: same input yields identical output bytes;
every symbol with count > 0 gets frequency >= 1;
symbols with count == 0 get frequency 0;
sum(frequencies) == 1 << scale_bits exactly;
if all counts are 0, return the canonical uniform model.

Algorithm: after granting each present symbol a guaranteed minimum of 1, the remaining budget is apportioned by the largest-remainder (Hare) method using u128 products, with ties broken by lower symbol index.

Source

pub fn uniform(scale_bits: u8) -> Result<EntropyModel>

Uniform model with every symbol getting an equal frequency.

Requires scale_bits >= 8, i.e. 1 << scale_bits >= ALPHABET; below that no integer table of 256 equal entries can sum to the target, so the request is rejected as ErrorClass::InvalidModel.

Source

pub fn encode(&self) -> Result<Vec<u8>>

Canonical wire encoding, version 2 (little-endian): [version u8 = 2][form u8][scale_bits u8] followed by the form payload.

form 0 (SPARSE): [present_count u16][symbol u8][freq u16] * n, with symbol strictly ascending and freq >= 1.
form 1 (DENSE): [count u16 = 256][freq u16] * 256.

The strictly smaller serialization is emitted; on a tie DENSE is chosen so the mapping from model to bytes stays deterministic. The model is validated before serialization so encode cannot emit a bad table.

Source

pub fn decode(bytes: &[u8]) -> Result<EntropyModel>

Parse and validate a canonical model; bytes must be exactly consumed.

Both legacy version 1 (dense) and version 2 (sparse or dense) are accepted. All failures are typed as ErrorClass::InvalidModel or ErrorClass::UnsupportedVersion.