Struct RangeDecoder 

pub struct RangeDecoder<'a> { /* private fields */ }

Bit-exact CELT/SILK range decoder state per RFC 6716 §4.1.

The decoder splits the input buffer into two halves. The range coder consumes bytes from the front (MSB-first into the range state) and the raw-bit reader consumes bytes from the back (LSB-first). RFC 6716 §4.1.4 explicitly permits the two readers to overlap; the decoder MUST allow it.

Implementations

impl<'a> RangeDecoder<'a>

pub fn new(buf: &'a [u8]) -> Self

Initialize the range decoder over buf per RFC 6716 §4.1.1.

The spec defines b0 as “the first input byte (or zero if there are no bytes in this Opus frame)”. The decoder sets rng = 128, val = 127 - (b0 >> 1), buffers the leftover bit (b0 & 1), then immediately invokes renormalization so the invariant rng > 2**23 holds before any symbol is decoded.

pub fn has_error(&self) -> bool

Whether this decoder has latched a frame corrupt error somewhere in its history. Higher-level decoders use this to abort the current frame and apply packet-loss concealment.

pub fn tell(&self) -> u32

Current whole-bit budget consumed by the range coder plus the raw-bit reader, per RFC 6716 §4.1.6.1.

ec_tell is defined as nbits_total - ilog(rng). Raw bits are added separately because §4.1.6 specifies that raw bits also count against the total.

pub fn tell_frac(&self) -> u32

Current 1/8th-bit-precision budget consumed by the range coder plus the raw-bit reader, per RFC 6716 §4.1.6.2.

Follows §4.1.6.2 directly: from lg = ilog(rng), extract r_Q15 = rng >> (lg - 16) as a Q15 value in [2^15, 2^16). Three iterations of r_Q15 = (r_Q15*r_Q15) >> 15; lg = 2*lg + (r_Q15 >> 16) extend lg to 1/8th-bit precision. Raw bits add 8*nbits_raw (whole bits scaled into eighths). By construction, ec_tell() == ceil(ec_tell_frac() / 8.0).

pub fn dec_bit_logp(&mut self, logp: u32) -> u32

Decode a single binary symbol with probability 2^-logp of being a “1”, per RFC 6716 §4.1.3.2.

Mathematically equivalent to ec_decode(ft = 1<<logp) followed by ec_dec_update(0, ft-1, ft) (for a “0”) or ec_dec_update(ft-1, ft, ft) (for a “1”). The implementation is multiply-and-divide-free: r >> logp replaces rng/ft, and the discriminator collapses to a comparison.

pub fn dec_bits(&mut self, bits: u32) -> u32

Decode bits raw bits per RFC 6716 §4.1.4.

Raw bits are packed at the END of the frame: the least significant bit of the first value is the LSB of the last byte; reads proceed toward the front. The function returns the raw bits in the order written — the LSB of the result holds the bit the encoder emitted first.

Returns 0 on errors (bits > 32); also returns zero-extended bits past the end of the frame, matching §4.1.4’s “the decoder MUST continue to use zero for any further input bytes required”.

pub fn dec_uint(&mut self, ft: u32) -> Result<u32, Error>

Decode one of ft equiprobable values in 0..ft, per RFC 6716 §4.1.5.

Values of ft <= 1 degenerate to the constant 0. ft may be as large as 2^32 - 1. The §4.1.5 procedure splits the value: the top 8 bits go through the range coder, the remainder through raw bits. If the reconstructed value is >= ft, the frame is corrupt — the decoder latches the error flag and saturates to ft - 1 per §4.1.5’s concealment recommendation.

pub fn decode_bin(&mut self, ftb: u32) -> u32

Decode fs for a power-of-two ft = 1<<ftb per RFC 6716 §4.1.3.1 (ec_decode_bin).

Mathematically equivalent to Self::decode with ft = 1<<ftb but avoids the division: rng / ft == rng >> ftb. The caller is expected to follow with Self::dec_update (or use Self::dec_icdf which fuses the two steps).

Returns fs in the range [0, 1<<ftb).

pub fn dec_icdf(&mut self, icdf: &[u8], ftb: u32) -> u32

Decode a symbol via an inverse-CDF table, per RFC 6716 §4.1.3.3 (ec_dec_icdf).

icdf[k] stores (1<<ftb) - fh[k], terminated by a 0 entry (the implicit fh[K_last] == ft). fl[0] is implicitly 0; the table values are strictly monotonically decreasing.

Fuses the search step (find the smallest k such that fs < ft - icdf[k]) with the range/value update, eliminating the division. The renormalization loop runs before returning.

Returns the decoded symbol index k in 0..icdf.len()-1. On a malformed table (no terminating zero), the decoder latches its sticky error flag and returns 0.

pub fn ec_decode(&mut self, ft: u32) -> u32

ec_decode(ft) per RFC 6716 §4.1.2 — the first of the two symbol-decode steps.

Computes the 16-bit symbol proxy fs = ft - min(val / (rng / ft) + 1, ft), which “lies within the range of some symbol in the current context”. The caller then identifies the symbol k whose three-tuple (fl[k], fh[k], ft) satisfies fl[k] <= fs < fh[k] and feeds that tuple to Self::ec_dec_update.

This split form is needed when the frequency model is computed at run time and cannot be pre-baked into a static inverse-CDF table (RFC 6716 §4.3.2.1 coarse-energy Laplace decode, §4.3.3 allocation search). For fixed PDFs prefer Self::dec_icdf, which fuses both steps and avoids a division.

ft must be in 1..=2**16 for the §4.1.2 derivation to hold (the renormalization invariant keeps rng > 2**23, so rng / ft >= 1). ft == 0 would divide by zero; the decoder latches its sticky error flag and returns 0 instead. The returned fs lies in [0, ft).

pub fn ec_dec_update(&mut self, fl: u32, fh: u32, ft: u32)

ec_dec_update(fl, fh, ft) per RFC 6716 §4.1.2 — the second of the two symbol-decode steps.

Narrows the range to the chosen symbol’s [fl, fh) sub-interval of [0, ft) per the §4.1.2 update equations, then renormalizes to restore rng > 2**23. Pair this with the index returned by the caller’s search over the value from Self::ec_decode.

The three-tuple MUST satisfy 0 <= fl < fh <= ft and 1 <= ft <= 2**16. A malformed tuple (ft == 0, fh > ft, or fl >= fh) cannot come from a well-formed search; the decoder latches its sticky error flag and leaves its state unchanged rather than underflowing val or zeroing rng.

Trait Implementations

impl<'a> Debug for RangeDecoder<'a>

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

Formats the value using the given formatter.