Module rans 

Deterministic static rANS over a hybrid-integer alphabet.

Signed integers are zigzag-mapped to u, then split into a token that is entropy coded and extra bits that are stored raw:

• u < 16 → token u, no extra bits;
• otherwise with nb = ⌊log2 u⌋, the token carries nb and the two bits below the leading one (16 + 4(nb−4) + m), and the remaining nb − 2 low bits go to the raw stream.

This is the JPEG-XL “hybrid uint” idea: the coded token captures the shape of the distribution, and the raw bits are (nearly) uniform, so storing them verbatim costs little. Each block’s token frequencies are normalised to a 2^14 total and transmitted (varint per symbol), and the rANS state is the 32-bit / byte-renormalised variant (Giesen’s rans_byte). Integer arithmetic only: encode and decode are bit-exact on every platform.

Constants

SCALE_BITS

Probability resolution of the frequency tables, in bits.

Functions

decode_blocks

Inverse of encode_blocks.

empirical_bits

Zeroth-order empirical entropy of the token stream plus raw bits, in bits — the floor a static per-block coder can approach (ignores tables).

encode_blocks

Entropy-code a list of integer blocks whose lengths the decoder already knows. The encoder tries one shared table vs one table per block and keeps the smaller (1 flag byte). Empty blocks cost nothing.

split_uint

Map u to (token, extra_bits_value, extra_bit_count).