refactor: one codec type per block size for u32 and u64

Consolidate the separate FastPForWide128/256 types into the existing
FastPFor128/FastPFor256: each now implements AnyLenCodec (u32) and
BlockCodec64 (u64), mirroring the C++ codecs that expose both widths from
one type. The u64 engine is retained as a private field, so buffer reuse is
preserved and the public API drops the extra FastPForWide* names.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: CommanderStorm

README.md

@@ -60,14 +60,14 @@ assert_eq!(decoded, input);
 
 ### 64-bit integers (`u64`)
 
-`FastPForWide128` / `FastPForWide256` compress `u64` values via the `BlockCodec64`
-trait. The wire format is byte-compatible with the C++ `CppFastPFor128` /
-`CppFastPFor256` `encode64` / `decode64` paths.
+The same `FastPFor128` / `FastPFor256` codecs also compress `u64` values via the
+`BlockCodec64` trait (`encode64` / `decode64`). The wire format is byte-compatible
+with the C++ `CppFastPFor128` / `CppFastPFor256` 64-bit paths.
 
 ```rust
-use fastpfor::{BlockCodec64, FastPForWide256};
+use fastpfor::{BlockCodec64, FastPFor256};
 
-let mut codec = FastPForWide256::default();
+let mut codec = FastPFor256::default();
 let input: Vec<u64> = (0..600).map(|i| i * 1_000_000_000).collect();
 
 let mut encoded = Vec::new();

fuzz/fuzz_targets/fastpfor_u64.rs

@@ -2,12 +2,12 @@
 
 //! Differential fuzz of the 64-bit FastPFOR codec.
 //!
-//! For any `u64` input, `FastPForWide` and the C++ codec must produce identical compressed bytes.
+//! For any `u64` input, the Rust and C++ codecs must produce identical compressed bytes.
 //! Every decoder must reproduce the original input.
 //! Each side must also decode the other's output.
 
 use fastpfor::cpp::{CppFastPFor128, CppFastPFor256};
-use fastpfor::{BlockCodec64, FastPForWide128, FastPForWide256};
+use fastpfor::{BlockCodec64, FastPFor128, FastPFor256};
 use libfuzzer_sys::fuzz_target;
 
 #[derive(arbitrary::Arbitrary, Debug)]
@@ -44,17 +44,17 @@ fn check(rust: &mut impl BlockCodec64, cpp: &mut impl BlockCodec64, data: &[u64]
 fuzz_target!(|input: Input| {
     if input.use_256 {
         check(
-            &mut FastPForWide256::default(),
+            &mut FastPFor256::default(),
             &mut CppFastPFor256::default(),
             &input.data,
-            "FastPForWide256",
+            "FastPFor256",
         );
     } else {
         check(
-            &mut FastPForWide128::default(),
+            &mut FastPFor128::default(),
             &mut CppFastPFor128::default(),
             &input.data,
-            "FastPForWide128",
+            "FastPFor128",
         );
     }
 });

src/codec.rs

@@ -93,7 +93,7 @@ pub trait BlockCodec: Default {
 
 /// Codec that supports compressing 64-bit integers into a 32-bit word stream.
 ///
-/// Implemented by the pure-Rust [`FastPForWide`](crate::FastPForWide) codecs.
+/// Implemented by the pure-Rust [`FastPFor128`](crate::FastPFor128) and [`FastPFor256`](crate::FastPFor256) codecs.
 /// With the `cpp` feature, `CppFastPFor128`, `CppFastPFor256`, and `CppVarInt` also implement it.
 /// For simple use, call `encode64` / `decode64` directly on the struct.
 ///

src/lib.rs

@@ -30,7 +30,7 @@ pub use bytemuck::Pod;
 #[cfg(feature = "rust")]
 pub use rust::{
     CompositeCodec, FastPFor, FastPFor128, FastPFor256, FastPForBlock128, FastPForBlock256,
-    FastPForWide, FastPForWide128, FastPForWide256, JustCopy, VariableByte,
+    JustCopy, VariableByte,
 };
 
 // `src/test_utils.rs` uses `fastpfor::...`; alias this crate for unit tests only.

src/rust/composite.rs

@@ -40,6 +40,7 @@ use crate::helpers::AsUsize;
 /// codec.decode(&encoded, &mut decoded, None).unwrap();
 /// assert_eq!(decoded, data);
 /// ```
+#[derive(Debug)]
 pub struct CompositeCodec<Blocks: BlockCodec, Tail: AnyLenCodec> {
     block: Blocks,
     tail: Tail,

src/rust/fastpfor_codec.rs

@@ -0,0 +1,86 @@
+//! Public any-length `FastPFOR` codecs supporting both 32- and 64-bit integers.
+//!
+//! [`FastPFor128`] and [`FastPFor256`] are the primary entry points.
+//! Each implements [`AnyLenCodec`] for `u32` and [`BlockCodec64`] for `u64`.
+//! Aligned blocks are coded with `FastPFOR` and the sub-block remainder with variable-byte coding.
+
+use crate::codec::{AnyLenCodec, BlockCodec64};
+use crate::rust::VariableByte;
+use crate::rust::composite::CompositeCodec;
+use crate::rust::integer_compression::fastpfor::{FastPForBlock128, FastPForBlock256};
+use crate::rust::integer_compression::fastpfor64::FastPForWide;
+use crate::FastPForResult;
+
+macro_rules! define_fastpfor {
+    ($(#[$meta:meta])* $name:ident, $block:ty, $n:literal) => {
+        $(#[$meta])*
+        #[derive(Debug, Default)]
+        pub struct $name {
+            narrow: CompositeCodec<$block, VariableByte>,
+            wide: FastPForWide<$n>,
+        }
+
+        impl AnyLenCodec for $name {
+            fn encode(&mut self, input: &[u32], out: &mut Vec<u32>) -> FastPForResult<()> {
+                self.narrow.encode(input, out)
+            }
+
+            fn decode(
+                &mut self,
+                input: &[u32],
+                out: &mut Vec<u32>,
+                expected_len: Option<u32>,
+            ) -> FastPForResult<()> {
+                self.narrow.decode(input, out, expected_len)
+            }
+        }
+
+        impl BlockCodec64 for $name {
+            fn encode64(&mut self, input: &[u64], out: &mut Vec<u32>) -> FastPForResult<()> {
+                self.wide.encode64(input, out)
+            }
+
+            fn decode64(&mut self, input: &[u32], out: &mut Vec<u64>) -> FastPForResult<()> {
+                self.wide.decode64(input, out)
+            }
+        }
+    };
+}
+
+define_fastpfor! {
+    /// Any-length `FastPFOR` codec with 128-value blocks.
+    ///
+    /// Compresses `u32` via [`AnyLenCodec`] and `u64` via [`BlockCodec64`].
+    FastPFor128, FastPForBlock128, 128
+}
+
+define_fastpfor! {
+    /// Any-length `FastPFOR` codec with 256-value blocks.
+    ///
+    /// Compresses `u32` via [`AnyLenCodec`] and `u64` via [`BlockCodec64`].
+    FastPFor256, FastPForBlock256, 256
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn one_codec_handles_both_widths() {
+        let mut codec = FastPFor256::default();
+
+        let data32: Vec<u32> = (0..600).collect();
+        let mut enc32 = Vec::new();
+        codec.encode(&data32, &mut enc32).unwrap();
+        let mut dec32 = Vec::new();
+        codec.decode(&enc32, &mut dec32, None).unwrap();
+        assert_eq!(dec32, data32);
+
+        let data64: Vec<u64> = (0..600).map(|i| i * 1_000_000_000).collect();
+        let mut enc64 = Vec::new();
+        codec.encode64(&data64, &mut enc64).unwrap();
+        let mut dec64 = Vec::new();
+        codec.decode64(&enc64, &mut dec64).unwrap();
+        assert_eq!(dec64, data64);
+    }
+}

src/rust/integer_compression/fastpfor64.rs

@@ -1,12 +1,12 @@
-//! 64-bit ([`u64`]) `FastPFOR` codec.
+//! 64-bit ([`u64`]) `FastPFOR` engine.
 //!
 //! This is the widened counterpart of the 32-bit [`FastPFor`](super::fastpfor::FastPFor).
 //! Values, exceptions, and the exception bitmap are 64 bits wide instead of 32.
 //! The output is byte-compatible with the C++ `CppFastPFor128` / `CppFastPFor256` 64-bit paths.
 //!
-//! `FastPFOR` only handles complete blocks.
-//! A [`VariableByte`] tail encodes the sub-block remainder.
-//! [`FastPForWide`] bundles both and implements [`BlockCodec64`].
+//! [`FastPForWide`] is the 64-bit half of the public [`FastPFor128`](crate::FastPFor128) /
+//! [`FastPFor256`](crate::FastPFor256) codecs and is not exported on its own.
+//! It handles complete blocks, then a [`VariableByte`] tail encodes the sub-block remainder.
 
 use std::cmp::min;
 use std::io::Cursor;
@@ -29,20 +29,14 @@ const DEFAULT_PAGE_SIZE: u32 = 65536;
 /// Number of frequency/exception buckets: one per possible bit width `0..=64`.
 const WIDTHS: usize = 65;
 
-/// [`FastPForWide`] with 128-value blocks.
-pub type FastPForWide128 = FastPForWide<128>;
-
-/// [`FastPForWide`] with 256-value blocks.
-pub type FastPForWide256 = FastPForWide<256>;
-
 fn bits64(value: u64) -> usize {
     64 - value.leading_zeros().as_usize()
 }
 
-/// 64-bit `FastPFOR` codec: `FastPFOR`-packed blocks plus a variable-byte tail.
+/// 64-bit `FastPFOR` engine: `FastPFOR`-packed blocks plus a variable-byte tail.
 ///
 /// `N` is the block size (128 or 256 values).
-/// Use [`FastPForWide128`] or [`FastPForWide256`], or call [`encode64`](BlockCodec64::encode64) / [`decode64`](BlockCodec64::decode64).
+/// This is the internal `u64` engine behind [`FastPFor128`](crate::FastPFor128) and [`FastPFor256`](crate::FastPFor256).
 #[derive(Debug)]
 pub struct FastPForWide<const N: usize> {
     exception_buffers: [Vec<u64>; WIDTHS],

src/rust/mod.rs

@@ -1,19 +1,14 @@
 mod composite;
 mod cursor;
+mod fastpfor_codec;
 mod integer_compression;
 
 pub use composite::CompositeCodec;
+/// Any-length `FastPFOR` codecs supporting both `u32` and `u64`.
+pub use fastpfor_codec::{FastPFor128, FastPFor256};
 /// Type-safe block codec with block size encoded in the type.
 pub use integer_compression::fastpfor::{FastPFor, FastPForBlock128, FastPForBlock256};
-/// 64-bit ([`u64`]) `FastPFOR` codec implementing [`BlockCodec64`](crate::BlockCodec64).
-pub use integer_compression::fastpfor64::{FastPForWide, FastPForWide128, FastPForWide256};
 /// Pass-through codec — implements [`AnyLenCodec`](crate::codec::AnyLenCodec).
 pub use integer_compression::just_copy::JustCopy;
 /// Variable-byte codec — implements [`AnyLenCodec`](crate::codec::AnyLenCodec).
 pub use integer_compression::variable_byte::VariableByte;
-
-/// `FastPForBlock256` blocks + `VariableByte` remainder — the most common composite.
-pub type FastPFor256 = CompositeCodec<FastPForBlock256, VariableByte>;
-
-/// `FastPForBlock128` blocks + `VariableByte` remainder.
-pub type FastPFor128 = CompositeCodec<FastPForBlock128, VariableByte>;