feat(bitpacking): Add batched index unpacking (#190)

Add `unpack_indices` and `unchecked_unpack_indices` to extract selected
values without a complete 1,024-value unpack.

Use `unpack_indices` when the bit width and packed length are
compile-time constants. Use `unchecked_unpack_indices` when the bit
width is available only at runtime. It dispatches the runtime width once
per batch.

Both methods write into `MaybeUninit` output. Use `unpack_single` for
one selected value. Use full unpack above the recommended threshold.

One private `#[inline(always)]` helper implements single-value
extraction. Public `unpack_single` keeps an out-of-line boundary. The
runtime dispatcher and batch path inline the helper after width
dispatch. This keeps width-specific expansion inside library code.

## Performance

Native Apple M1 benchmarks use Rust 1.91.0 and `-C target-cpu=native`.

At 8 and 32 selected values, batch extraction is 2.0–3.4× faster than
repeated `unpack_single` calls.

The table gives a conservative dispatch policy across the sampled packed
widths.

| Physical type | Use batch when | Use full unpack when |
| --- | ---: | ---: |
| `u8` | `n <= 16` | `n > 16` |
| `u16` | `n <= 32` | `n > 32` |
| `u32` | `n <= 64` | `n > 64` |
| `u64` | `n <= 160` | `n > 160` |

The grid covers widths 1, 4, and 7 for `u8`. It covers widths 1, 3, 8,
and 15 for `u16`.

It covers widths 1, 8, 16, 24, and 31 for `u32`. It covers widths 1, 16,
32, 48, and 63 for `u64`.

The limiting measured crossovers were 18–19, 32–34, 68–72, and 176–184.
The rounded thresholds leave margin for other hardware.

Packed-width effects were non-monotonic, so the policy uses only the
physical type and selected-value count.

`cargo asm` confirms one runtime-width dispatch per batch. The generated
`u16` batch function contains no per-index `unpack_single` calls.

## Code size

The release rlib grows from 3,750,536 bytes on `develop` to 3,942,416
bytes, a 5.1% increase. Object text grows from 419,814 bytes to 447,917
bytes, a 6.7% increase.

## Verification

Tests cover every integer type and runtime width. They also cover empty,
duplicate, unordered, full-block, zero-width, and invalid inputs.

🤖 Generated with [Codex](https://openai.com/codex/)

---------

Signed-off-by: Will Manning <will@willmanning.io>

Author: lwwmanning

benches/bitpacking.rs

@@ -1,3 +1,4 @@
+use std::mem::MaybeUninit;
 use std::mem::size_of;
 
 use arrayref::{array_mut_ref, array_ref};
@@ -90,6 +91,145 @@ fn unpack_single_16_from_3(bencher: Bencher) {
     });
 }
 
+const MAX_BENCHMARK_INDICES: usize = 128;
+
+#[derive(Clone, Copy)]
+enum IndexDistribution {
+    Uniform,
+    Clustered,
+    UnorderedWithDuplicates,
+}
+
+fn benchmark_indices(
+    distribution: IndexDistribution,
+    num_indices: usize,
+) -> [usize; MAX_BENCHMARK_INDICES] {
+    assert!(num_indices <= MAX_BENCHMARK_INDICES);
+    let mut indices = [0; MAX_BENCHMARK_INDICES];
+
+    match distribution {
+        IndexDistribution::Uniform => {
+            for (position, index) in indices[..num_indices].iter_mut().enumerate() {
+                *index = position * 1024 / num_indices;
+            }
+        }
+        IndexDistribution::Clustered => {
+            for (position, index) in indices[..num_indices].iter_mut().enumerate() {
+                *index = 448 + position;
+            }
+        }
+        IndexDistribution::UnorderedWithDuplicates => {
+            for position in 0..num_indices {
+                indices[position] = if position > 0 && position % 4 == 0 {
+                    indices[position - 1]
+                } else {
+                    (position * 541 + 17) % 1024
+                };
+            }
+        }
+    }
+
+    indices
+}
+
+macro_rules! unpack_indices_benchmarks {
+    ($module:ident, $type:ty, $width:expr, $distribution:expr) => {
+        mod $module {
+            use super::*;
+
+            const WIDTH: usize = $width;
+            const PACKED_LENGTH: usize = 1024 * WIDTH / <$type>::T;
+
+            fn fixture(
+                num_indices: usize,
+            ) -> ([$type; PACKED_LENGTH], [usize; MAX_BENCHMARK_INDICES]) {
+                let mask = ((1_u128 << WIDTH) - 1) as $type;
+                let values =
+                    std::array::from_fn(|index| ((index as $type).wrapping_mul(17)) & mask);
+                let mut packed = [0; PACKED_LENGTH];
+                BitPacking::pack::<WIDTH, PACKED_LENGTH>(&values, &mut packed);
+                let indices = benchmark_indices($distribution, num_indices);
+                (packed, indices)
+            }
+
+            #[divan::bench(args = [1, 8, 32, 128], sample_size = 10_000)]
+            fn batched(bencher: Bencher, num_indices: usize) {
+                let (packed, indices) = fixture(num_indices);
+                let mut output = [MaybeUninit::<$type>::uninit(); MAX_BENCHMARK_INDICES];
+
+                bencher.bench_local(|| {
+                    let packed = black_box(&packed);
+                    let indices = black_box(&indices[..num_indices]);
+                    let output = black_box(&mut output[..num_indices]);
+                    // SAFETY: `packed` contains exactly one packed FastLanes block.
+                    unsafe {
+                        BitPacking::unchecked_unpack_indices(WIDTH, packed, indices, output);
+                    }
+                    black_box(&*output);
+                });
+            }
+
+            #[divan::bench(args = [1, 8, 32, 128], sample_size = 10_000)]
+            fn repeated_single(bencher: Bencher, num_indices: usize) {
+                let (packed, indices) = fixture(num_indices);
+                let mut output = [MaybeUninit::<$type>::uninit(); MAX_BENCHMARK_INDICES];
+
+                bencher.bench_local(|| {
+                    let packed = black_box(&packed);
+                    let indices = black_box(&indices[..num_indices]);
+                    let output = black_box(&mut output[..num_indices]);
+                    for (&index, value) in indices.iter().zip(output.iter_mut()) {
+                        // SAFETY: `packed` contains exactly one packed FastLanes block.
+                        value.write(unsafe {
+                            BitPacking::unchecked_unpack_single(WIDTH, packed, index)
+                        });
+                    }
+                    black_box(&*output);
+                });
+            }
+
+            #[divan::bench(args = [1, 8, 32, 128], sample_size = 10_000)]
+            fn full_unpack_then_gather(bencher: Bencher, num_indices: usize) {
+                let (packed, indices) = fixture(num_indices);
+                let mut unpacked = [0; 1024];
+                let mut output = [MaybeUninit::<$type>::uninit(); MAX_BENCHMARK_INDICES];
+
+                bencher.bench_local(|| {
+                    let packed = black_box(&packed);
+                    let indices = black_box(&indices[..num_indices]);
+                    let unpacked = black_box(&mut unpacked);
+                    let output = black_box(&mut output[..num_indices]);
+                    // SAFETY: both buffers have the required lengths for `WIDTH`.
+                    unsafe { BitPacking::unchecked_unpack(WIDTH, packed, unpacked) };
+                    for (&index, value) in indices.iter().zip(output.iter_mut()) {
+                        value.write(unpacked[index]);
+                    }
+                    black_box(&*output);
+                });
+            }
+        }
+    };
+}
+
+unpack_indices_benchmarks!(
+    unpack_indices_u16_width3_uniform,
+    u16,
+    3,
+    IndexDistribution::Uniform
+);
+unpack_indices_benchmarks!(
+    unpack_indices_u32_width16_clustered,
+    u32,
+    16,
+    IndexDistribution::Clustered
+);
+unpack_indices_benchmarks!(
+    unpack_indices_u64_width63_unordered_duplicates,
+    u64,
+    63,
+    IndexDistribution::UnorderedWithDuplicates
+);
+
 #[divan::bench(sample_count = 10000)]
 fn throughput_compress(bencher: Bencher) {
     const WIDTH: usize = 3;