Function unpack_bytes_less_than

src/pack.rs:210–348

Like `unpack_bytes` but all values are less than `N` so it can avoid encoding the packing. Bytes returned by this function are guaranteed less than `N`. If `HISTOGRAM` is set to `N` it also returns a histogram of the output bytes. This is because the histogram can be calculated much faster when operating on the packed bytes. If `HISTOGRAM` is set to `0` it only checks variants < `N` and doesn't

(
    input: &mut &'a [u8],
    length: usize,
    out: &mut CowSlice<'a, u8>,
)

///
/// If `HISTOGRAM` is set to `0` it only checks variants < `N` and doesn't calculate a histogram.
pub fn unpack_bytes_less_than<'a, const N: usize, const HISTOGRAM: usize>(
    input: &mut &'a [u8],
    length: usize,
    out: &mut CowSlice<'a, u8>,
) -> Result<[usize; HISTOGRAM]> {
    assert!(HISTOGRAM == N || HISTOGRAM == 0);

    /// Checks that `unpacked` bytes are less than `N`. All of `unpacked` is assumed to be < `FACTOR`.
    /// `HISTOGRAM` must be 0.
    fn check_less_than<const N: usize, const HISTOGRAM: usize, const FACTOR: usize>(
        unpacked: &[u8],
    ) -> Result<[usize; HISTOGRAM]> {
        assert!(FACTOR >= N);
        debug_assert!(unpacked.iter().all(|&v| (v as usize) < FACTOR));
        if FACTOR > N && unpacked.iter().copied().max().unwrap_or(0) as usize >= N {
            return invalid_packing();
        }
        Ok(std::array::from_fn(|_| unreachable!("HISTOGRAM not 0")))
    }

    /// Returns `Ok(histogram)` if buckets after `OUT` are 0.
    fn check_histogram<const IN: usize, const OUT: usize>(
        histogram: [usize; IN],
    ) -> Result<[usize; OUT]> {
        let (histogram, remaining) = histogram.split_at(OUT);
        if remaining.iter().copied().sum::<usize>() != 0 {
            return invalid_packing();
        }
        Ok(*<&[usize; OUT]>::try_from(histogram).unwrap())
    }

    let p = Packing::new(N.saturating_sub(1) as u8);
    if p == Packing::_256 {
        let bytes = consume_bytes(input, length)?;
        out.set_borrowed(bytes);
        return if HISTOGRAM == 0 {
            check_less_than::<N, HISTOGRAM, 256>(bytes)
        } else {
            check_histogram(crate::histogram::histogram(bytes))
        };
    }

    /// `FACTOR_POW_DIVISOR == (FACTOR as usize).pow(factor_to_divisor::<FACTOR>() as u32)` but as a constant.
    fn unpack_arithmetic_less_than<
        const N: usize,
        const HISTOGRAM: usize,
        const FACTOR: usize,
        const FACTOR_POW_DIVISOR: usize,
    >(
        input: &mut &[u8],
        length: usize,
        out: &mut Vec<u8>,
    ) -> Result<[usize; HISTOGRAM]> {
        assert!(HISTOGRAM == N || HISTOGRAM == 0);
        assert!(FACTOR >= 2 && FACTOR >= N);
        let divisor = factor_to_divisor::<FACTOR>();
        assert_eq!(FACTOR.pow(divisor as u32), FACTOR_POW_DIVISOR);