Struct Histogram 

pub struct Histogram {
    pub counts: Vec<i32>,
    pub total_count: usize,
    /* private fields */
}

A histogram counting symbol occurrences.

This is the encoder-side histogram structure, corresponding to libjxl’s Histogram class in enc_ans_params.h.

Fields

counts: Vec<i32>

Symbol counts (aligned to HISTOGRAM_ROUNDING). Uses i32 to match libjxl’s ANSHistBin type.

total_count: usize

Sum of all counts.

Implementations

impl Histogram

pub fn new() -> Self

Creates an empty histogram.

pub fn with_capacity(length: usize) -> Self

Creates a histogram with pre-allocated capacity for length symbols. The capacity is rounded up to HISTOGRAM_ROUNDING.

pub fn from_counts(counts: &[i32]) -> Self

Creates a histogram from a slice of counts.

pub fn flat(length: usize, total_count: usize) -> Self

Creates a flat (uniform) histogram.

pub fn clear(&mut self)

Clears all counts.

pub fn add(&mut self, symbol: usize)

Add one occurrence of a symbol.

pub fn ensure_capacity(&mut self, length: usize)

Ensures the histogram can hold at least length symbols.

pub fn fast_add(&mut self, symbol: usize)

Fast add (caller must ensure capacity first).

pub fn add_histogram(&mut self, other: &Histogram)

Add another histogram’s counts to this one.

pub fn condition(&mut self)

Trim trailing zeros and update total_count. Should be called after a sequence of fast_add calls.

pub fn shannon_entropy(&self) -> f32

Compute Shannon entropy: -sum(count * log2(count / total)). Result is in bits (not nats).

Formula: sum of -(count/total) * log2(count/total) * total = sum of -count * log2(count/total) = sum of -count * (log2(count) - log2(total)) = sum of -count * log2(count) + count * log2(total) = -sum(count * log2(count)) + total * log2(total)

libjxl uses: -count * log2(count / total), excluding when count == total.

pub fn cached_entropy(&self) -> f32

Get the cached entropy value. Call shannon_entropy() first to ensure it’s up-to-date.

pub fn set_cached_entropy(&self, entropy: f32)

Set the cached entropy value (used when loading from test data).

pub fn alphabet_size(&self) -> usize

Alphabet size (highest non-zero symbol + 1).

pub fn max_symbol(&self) -> usize

Returns the index of the maximum symbol with non-zero count.

pub fn is_empty(&self) -> bool

Check if histogram is empty (all zeros).

pub fn copy_from(&mut self, source: &Histogram)

Copy contents from another histogram, reusing this histogram’s allocation.

Unlike clone(), this avoids allocating a new Vec when self already has sufficient capacity.

Trait Implementations

impl Clone for Histogram

fn clone(&self) -> Histogram

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Histogram

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Histogram

fn default() -> Self

Returns the “default value” for a type.