docs: Update README and module documentation for clarity and consistency

refactor: Simplify iterator implementations and improve type annotations
fix: Correct type parameters in IntVec and related structures for better type safety

Author: lukefleed

README.md

@@ -409,4 +409,9 @@ python3 python/plot.py --random-access
 The resulting SVGs file will be saved in the `images` directory.
 
 [`sux::BitFieldVec`]: https://docs.rs/sux/latest/sux/bits/bit_field_vec/index.htmll
-[`succinct::IntVector`]: https://docs.rs/succinct/latest/succinct/int_vec/trait.IntVec.html
+[`succinct::IntVector`]: https://docs.rs/succinct/latest/succinct/int_vec/trait.IntVec.html
+
+# TODO
+
+* [ ] Add support for [`epsilon-serde`](https://crates.io/crates/epserde)
+* [ ] Add SIMD feature

src/fixed/atomic/mod.rs

@@ -1275,7 +1275,7 @@ where
     current_index: usize,
 }
 
-impl<'a, T> Iterator for AtomicFixedVecIter<'a, T>
+impl<T> Iterator for AtomicFixedVecIter<'_, T>
 where
     T: Storable<u64> + Copy + ToPrimitive,
 {

src/fixed/builder.rs

@@ -1,4 +1,4 @@
-//! # `FixedVec` Builders
+//! # [`FixedVec`] Builders
 //!
 //! This module provides builders for constructing an owned [`FixedVec`].
 //!

src/fixed/iter.rs

@@ -1,15 +1,22 @@
-//! # `FixedVec` Iterators
+//! # [`FixedVec`] Iterators
 //!
 //! This module provides iterators for sequential access to the elements of a
 //! [`FixedVec`]. The iterators decode values on the fly without allocating an
 //! intermediate buffer, making them efficient for processing large datasets.
 //!
+//! The core iterators ([`FixedVecIter`], [`FixedVecSliceIter`]) are stateful and
+//! employ a bit-windowing technique. They decode values on the fly without
+//! allocating an intermediate buffer. They support both forward and reverse
+//! iteration.
+//!
 //! # Provided Iterators
 //!
-//! - [`FixedVecIter`]: A bidirectional iterator over the elements of a `FixedVec`.
-//! - [`FixedVecIntoIter`]: A consuming iterator that takes ownership of a `FixedVec`.
-//! - [`Chunks`]: An iterator that yields non-overlapping, immutable slices.
-//! - [`Windows`]: An iterator that yields overlapping, immutable slices.
+//! - [`FixedVecIter`]: A stateful, bidirectional iterator over the elements of a borrowed [`FixedVec`].
+//! - [`FixedVecIntoIter`]: A consuming, bidirectional iterator that takes ownership of a [`FixedVec`].
+//! - [`FixedVecSliceIter`]: A stateful, bidirectional iterator over the elements of a [`FixedVecSlice`].
+//! - [`Chunks`]: An iterator that yields non-overlapping, immutable slices ([`FixedVecSlice`]).
+//! - [`Windows`]: An iterator that yields overlapping, immutable slices ([`FixedVecSlice`]).
+//! - [`FixedVecUncheckedIter`]: An `unsafe` bidirectional iterator that omits bounds checks for maximum performance.
 //!
 //! # Examples
 //!
@@ -28,6 +35,50 @@
 //!
 //! assert_eq!(sum, 200);
 //! ```
+//!
+//! ## Bidirectional Iteration
+//!
+//! The main iterators implement [`DoubleEndedIterator`], allowing for
+//! traversal from both ends of the sequence.
+//!
+//! ```rust
+//! use compressed_intvec::fixed::{FixedVec, UFixedVec};
+//!
+//! let vec: UFixedVec<u8> = (0..=5u8).collect();
+//! let mut iter = vec.iter();
+//!
+//! assert_eq!(iter.next(), Some(0));
+//! assert_eq!(iter.next_back(), Some(5));
+//! assert_eq!(iter.next(), Some(1));
+//! assert_eq!(iter.next_back(), Some(4));
+//!
+//! // The iterator correctly tracks its remaining length.
+//! assert_eq!(iter.len(), 2);
+//!
+//! assert_eq!(iter.next(), Some(2));
+//! assert_eq!(iter.next(), Some(3));
+//! assert_eq!(iter.next(), None);
+//! ```
+//!
+//! ## Iterating over a Slice
+//!
+//! You can also create an iterator over a zero-copy slice of a vector.
+//!
+//! ```rust
+//! use compressed_intvec::fixed::{FixedVec, UFixedVec};
+//!
+//! let vec: UFixedVec<u32> = (0..100u32).collect();
+//!
+//! // Create a slice containing elements from index 20 to 29.
+//! let slice = vec.slice(20, 10).unwrap();
+//! assert_eq!(slice.len(), 10);
+//!
+//! // The slice iterator will yield the elements from the slice.
+//! let collected: Vec<u32> = slice.iter().collect();
+//! let expected: Vec<u32> = (20..30).collect();
+//!
+//! assert_eq!(collected, expected);
+//! ```
 
 use crate::fixed::{
     slice::FixedVecSlice,
@@ -119,7 +170,7 @@ where
     E: Endianness,
     B: AsRef<[W]>,
 {
-    /// Creates a new stateful, bidirectional iterator for a given `FixedVec`.
+    /// Creates a new stateful, bidirectional iterator for a given [`FixedVec`].
     pub(super) fn new(vec: &'a FixedVec<T, W, E, B>) -> Self {
         if vec.is_empty() {
             return Self {
@@ -137,7 +188,7 @@ where
         }
 
         let limbs = vec.as_limbs();
-        let bits_per_word = <W as Word>::BITS;
+        let bits_per_word: usize = <W as Word>::BITS;
 
         // --- Setup forward state ---
         let front_word_index = 1;
@@ -257,7 +308,7 @@ where
         }
 
         let bit_width = self.vec.bit_width();
-        let bits_per_word = <W as Word>::BITS;
+        let bits_per_word: usize = <W as Word>::BITS;
 
         if self.back_bits_in_window >= bit_width {
             self.back_bits_in_window -= bit_width;
@@ -354,6 +405,19 @@ where
     }
 }
 
+impl<T, W, E, B> DoubleEndedIterator for FixedVecIntoIter<'_, T, W, E, B>
+where
+    T: Storable<W>,
+    W: Word,
+    E: Endianness,
+    B: AsRef<[W]>,
+{
+    #[inline]
+    fn next_back(&mut self) -> Option<Self::Item> {
+        self.iter.next_back()
+    }
+}
+
 impl<T, W, E, B> ExactSizeIterator for FixedVecIntoIter<'_, T, W, E, B>
 where
     T: Storable<W>,
@@ -369,7 +433,8 @@ where
 /// An iterator over the elements of a [`FixedVecSlice`].
 ///
 /// This struct is created by the [`iter`](super::slice::FixedVecSlice::iter)
-/// method on [`FixedVecSlice`].
+/// method on [`FixedVecSlice`]. It is a stateful bitstream reader that decodes
+/// values on the fly for both forward and reverse iteration.
 pub struct FixedVecSliceIter<'s, T, W, E, B, V>
 where
     T: Storable<W>,
@@ -379,7 +444,19 @@ where
     V: Deref<Target = FixedVec<T, W, E, B>>,
 {
     slice: &'s FixedVecSlice<V>,
-    current_index: usize,
+    front_index: usize, // index relative to slice start
+    back_index: usize,  // index relative to slice start
+
+    // State for forward iteration.
+    front_window: W,
+    front_bits_in_window: usize,
+    front_word_index: usize,
+
+    // State for backward iteration.
+    back_window: W,
+    back_bits_in_window: usize,
+    back_word_index: usize,
+
     _phantom: PhantomData<(T, W, E, B)>,
 }
 
@@ -391,11 +468,62 @@ where
     B: AsRef<[W]>,
     V: Deref<Target = FixedVec<T, W, E, B>>,
 {
-    /// Creates a new iterator for a given `FixedVecSlice`.
+    /// Creates a new stateful, bidirectional iterator for a given `FixedVecSlice`.
     pub(super) fn new(slice: &'s FixedVecSlice<V>) -> Self {
+        let parent_vec = &slice.parent;
+        if slice.is_empty() {
+            return Self {
+                slice,
+                front_index: 0,
+                back_index: 0,
+                front_window: W::ZERO,
+                front_bits_in_window: 0,
+                front_word_index: 0,
+                back_window: W::ZERO,
+                back_bits_in_window: 0,
+                back_word_index: 0,
+                _phantom: PhantomData,
+            };
+        }
+
+        let bits_per_word: usize = <W as Word>::BITS;
+        let bit_width: usize = parent_vec.bit_width();
+        let limbs: &[W] = parent_vec.as_limbs();
+        let slice_start_abs: usize = slice.range.start;
+        let slice_end_abs: usize = slice.range.end;
+
+        // --- Setup forward state ---
+        let start_bit_pos: usize = slice_start_abs * bit_width;
+        let start_word_index: usize = start_bit_pos / bits_per_word;
+        let start_bit_offset: usize = start_bit_pos % bits_per_word;
+
+        let front_window_raw: W = unsafe { *limbs.get_unchecked(start_word_index) };
+        let front_window: W = front_window_raw >> start_bit_offset;
+        let front_bits_in_window: usize = bits_per_word - start_bit_offset;
+        let front_word_index: usize = start_word_index + 1;
+
+        // --- Setup backward state ---
+        let end_bit_pos: usize = slice_end_abs * bit_width;
+        let back_word_index: usize = (end_bit_pos.saturating_sub(1)) / bits_per_word;
+        let back_window: W = unsafe { *limbs.get_unchecked(back_word_index) };
+
+        let back_bits_in_window = end_bit_pos % bits_per_word;
+        let back_bits_in_window = if back_bits_in_window == 0 && end_bit_pos > 0 {
+            bits_per_word
+        } else {
+            back_bits_in_window
+        };
+
         Self {
             slice,
-            current_index: 0,
+            front_index: 0,
+            back_index: slice.len(),
+            front_window,
+            front_bits_in_window,
+            front_word_index,
+            back_window,
+            back_bits_in_window,
+            back_word_index,
             _phantom: PhantomData,
         }
     }
@@ -413,21 +541,107 @@ where
 
     #[inline]
     fn next(&mut self) -> Option<Self::Item> {
-        if self.current_index >= self.slice.len() {
+        if self.front_index >= self.back_index {
             return None;
         }
-        // SAFETY: The iterator's logic guarantees the index is in bounds.
-        let value = unsafe { self.slice.get_unchecked(self.current_index) };
-        self.current_index += 1;
-        Some(value)
+
+        let parent_vec = &self.slice.parent;
+        let bit_width = parent_vec.bit_width();
+        let mask = parent_vec.mask;
+
+        let abs_index = self.slice.range.start + self.front_index;
+        self.front_index += 1;
+
+        if bit_width == <W as Word>::BITS {
+            let val = unsafe { *parent_vec.as_limbs().get_unchecked(abs_index) };
+            let final_val = if E::IS_BIG { W::from_be(val) } else { val };
+            return Some(<T as Storable<W>>::from_word(final_val));
+        }
+
+        if E::IS_BIG {
+            return Some(unsafe { parent_vec.get_unchecked(abs_index) });
+        }
+
+        if self.front_bits_in_window >= bit_width {
+            let value = self.front_window & mask;
+            self.front_window >>= bit_width;
+            self.front_bits_in_window -= bit_width;
+            return Some(<T as Storable<W>>::from_word(value));
+        }
+
+        unsafe {
+            let limbs = parent_vec.as_limbs();
+            let bits_from_old = self.front_bits_in_window;
+            let mut result = self.front_window;
+
+            self.front_window = *limbs.get_unchecked(self.front_word_index);
+            self.front_word_index += 1;
+            result |= self.front_window << bits_from_old;
+            let value = result & mask;
+
+            let bits_from_new = bit_width - bits_from_old;
+            self.front_window >>= bits_from_new;
+            self.front_bits_in_window = <W as Word>::BITS - bits_from_new;
+
+            Some(<T as Storable<W>>::from_word(value))
+        }
     }
 
     fn size_hint(&self) -> (usize, Option<usize>) {
-        let remaining = self.slice.len().saturating_sub(self.current_index);
+        let remaining = self.back_index.saturating_sub(self.front_index);
         (remaining, Some(remaining))
     }
 }
 
+impl<T, W, E, B, V> DoubleEndedIterator for FixedVecSliceIter<'_, T, W, E, B, V>
+where
+    T: Storable<W>,
+    W: Word,
+    E: Endianness,
+    B: AsRef<[W]>,
+    V: Deref<Target = FixedVec<T, W, E, B>>,
+{
+    #[inline]
+    fn next_back(&mut self) -> Option<Self::Item> {
+        if self.front_index >= self.back_index {
+            return None;
+        }
+        self.back_index -= 1;
+        let abs_index = self.slice.range.start + self.back_index;
+        let parent_vec = &self.slice.parent;
+
+        if E::IS_BIG || parent_vec.bit_width() == <W as Word>::BITS {
+            return Some(unsafe { parent_vec.get_unchecked(abs_index) });
+        }
+
+        let bit_width = parent_vec.bit_width();
+        let bits_per_word: usize = <W as Word>::BITS;
+
+        if self.back_bits_in_window >= bit_width {
+            self.back_bits_in_window -= bit_width;
+            let value = (self.back_window >> self.back_bits_in_window) & parent_vec.mask;
+            return Some(<T as Storable<W>>::from_word(value));
+        }
+
+        unsafe {
+            let limbs = parent_vec.as_limbs();
+            let bits_from_old = self.back_bits_in_window;
+            let mut result = self.back_window;
+
+            self.back_word_index -= 1;
+            self.back_window = *limbs.get_unchecked(self.back_word_index);
+
+            result &= (W::ONE << bits_from_old).wrapping_sub(W::ONE);
+            let bits_from_new = bit_width - bits_from_old;
+            result <<= bits_from_new;
+            result |= self.back_window >> (bits_per_word - bits_from_new);
+
+            self.back_bits_in_window = bits_per_word - bits_from_new;
+            Some(<T as Storable<W>>::from_word(result))
+        }
+    }
+}
+
 impl<T, W, E, B, V> ExactSizeIterator for FixedVecSliceIter<'_, T, W, E, B, V>
 where
     T: Storable<W>,
@@ -437,7 +651,7 @@ where
     V: Deref<Target = FixedVec<T, W, E, B>>,
 {
     fn len(&self) -> usize {
-        self.slice.len().saturating_sub(self.current_index)
+        self.back_index.saturating_sub(self.front_index)
     }
 }
 
@@ -578,4 +792,14 @@ where
         // The primary gain here is removing the check in `next()`.
         self.iter.next().unwrap_unchecked()
     }
-}
+
+    /// Returns the next element from the back without bounds checking.
+    ///
+    /// # Safety
+    ///
+    /// Calling this method when the iterator is exhausted is undefined behavior.
+    #[inline]
+    pub unsafe fn next_back_unchecked(&mut self) -> T {
+        self.iter.next_back().unwrap_unchecked()
+    }
+}