1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
//! The [`BitPacker`] trait — the single definition of codec behavior, implemented by
//! [`Scalar`](crate::Scalar) and [`Wasm128`](crate::Wasm128).
/// A fixed-block-size integer bit-packing codec.
///
/// Packs `u32` values into a tightly-bit-packed byte buffer at a caller-chosen bit width,
/// and unpacks them back out. Every implementation operates on exactly
/// [`BLOCK_LEN`](Self::BLOCK_LEN) values at a time — arbitrary-length input is handled by
/// the [`pack`](crate::pack)/[`unpack`](crate::unpack) wrapper, not by this trait directly.
///
/// This trait is sealed: it can only be implemented by types defined in this crate, so
/// adding a new required method here is never a breaking change for downstream users.
///
/// # Examples
///
/// ```
/// use wasm_bitpack::{BitPacker, Scalar};
///
/// let values = vec![7u32; Scalar::BLOCK_LEN];
/// let num_bits = Scalar::num_bits(&values);
///
/// let mut compressed = vec![0u8; Scalar::BLOCK_LEN * num_bits as usize / 8];
/// let written = Scalar::compress(&values, &mut compressed, num_bits);
///
/// let mut decompressed = vec![0u32; Scalar::BLOCK_LEN];
/// let read = Scalar::decompress(&compressed[..written], &mut decompressed, num_bits);
/// assert_eq!(read, written);
/// assert_eq!(decompressed, values);
/// ```