Cursor-based sequential iteration for Index trait

[antiguru]

Problem

Repeats<TC>::get(index) calls RankSelect::rank(index) on every access — a popcount over multiple u64 words.
For sequential iteration this recomputes bit counts from scratch per element.
The same overhead hits Lookbacks.
For composite types (tuples, #[derive(Columnar)] structs) containing these, the cost multiplies.

Design

Extend Index with a GAT cursor:

pub trait Index {
    type Ref;
    type Cursor<'a>: Iterator<Item = Self::Ref> where Self: 'a;
    fn get(&self, index: usize) -> Self::Ref;
    fn cursor(&self, range: Range<usize>) -> Self::Cursor<'_>;
    fn index_iter(&self) -> Self::Cursor<'_> where Self: Len { self.cursor(0..self.len()) }
}

• Each type provides a specialized cursor where worthwhile; others fall back to DefaultCursor (wraps get()).
• Slices use core::slice::Iter for pointer-based iteration.
• Tuples and derived structs generate composed cursors — TupleCursorN<A::Cursor, B::Cursor, ...> / FooContainerCursor<'a, ...> — that zip field cursors. Specialized cursors propagate through composites automatically.
• RepeatsCursor / LookbacksCursor seed somes_cursor / oks_cursor with one rank() at range start, then maintain incrementally: bit test + conditional increment per element.
• Bit fetches cache the current bitvector word; only re-fetch on word boundary (every 64 elements), avoiding the per-element bounds check into &[u64].
• New CursorOf<'a, C> type alias (<C as Index>::Cursor<'a>) for naming iterator types in trait associated-type slots.

Trade-offs

• Ref-form impls (&'a Repeats, &'a Lookbacks, &'a tuple, &'a Slice, derive ref form) use DefaultCursor. Composed cursors need lifetime gymnastics around intermediate references that don't work through a generic impl. The hot path — container.borrow().index_iter() — hits the owned-form specialized cursor.
• index_iter return type changes from IterOwn<&Self> to Self::Cursor<'_> — semver-major. Callers iterating with for x in c.index_iter() keep working; callers naming IterOwn<&Self> break. Item types can shift from &T to T depending on method dispatch (reflected in updated sum tests).
• container.borrow().index_iter() pattern has a lifetime limitation. The cursor borrows from the Borrowed shell, which is a temporary in that expression. Callers who need to return an iterator from a method where the Borrowed can't be stashed (e.g. fn drain(&mut self) -> Self::DrainIter<'_>) should use into_index_iter — it consumes the Copy Borrowed shell, giving an IterOwn<Borrowed<'a>> whose lifetime ties to the inner refs. Slow path, but semantically correct. A cleaner fix (cursors holding Copy inner refs directly) would require either specialization or dropping owned-form cursors; out of scope for this PR.
• Enums keep DefaultCursor. Composed dispatch across variants with per-element discriminants is non-trivial; not worth the surface-area bump for this PR.

Performance

All numbers from benches in this PR. Machine-dependent; relative improvements are the signal.

Repeats / Lookbacks direct iteration (100k elements, benches/repeats_cursor.rs):

Method	Time	Throughput	vs baseline
repeats_get	1094 µs	730 MB/s	baseline
repeats_cursor	92 µs	8647 MB/s	11.8x
lookbacks_get	1123 µs	712 MB/s	baseline
lookbacks_cursor	121 µs	6577 MB/s	9.2x

Both types eliminate per-element rank(); remaining cost is bit shift + one bounds-checked array access into somes / oks.

Derived struct with a Repeats field (100k rows, benches/derived_cursor.rs):

Method	Time	Throughput	vs baseline
derived_get (per-elem)	1228 µs	1303 MB/s	baseline
derived_cursor (composed)	107 µs	15010 MB/s	11.5x
tuple_cursor (reference)	110 µs	14511 MB/s	11.2x

derived_cursor matches tuple_cursor — the composed cursor lets derived structs benefit identically to hand-written tuples.

Options/Results (100k elements, benches/options_cursor.rs):

Method	Time	vs baseline
options_get	852 µs	baseline
options_cursor	851 µs	~same
results_get	1073 µs	baseline
results_cursor	1148 µs	~same

Options/Results see no change when iterated directly: get() cost is dominated by the somes/oks array access, not rank().
They still benefit indirectly when they appear inside composites — the Repeats / Lookbacks fields get specialized iteration via the composed cursor.

Profile after word caching (Materialize workload):

• One rank() per cursor construction, zero per element.
• IPC ~2.9, branch miss rate 0.5%.
• Remaining per-element cost: bit shift + somes.get() bounds-checked array access.

What changed

• Extended Index trait: Cursor GAT, cursor(), index_iter unified to use it.
• DefaultCursor + impl_default_cursor! macro; ~35 container impls adopt default cursor.
• RepeatsCursor + LookbacksCursor with word caching.
• Tuple macro generates TupleCursorN structs.
• columnar_derive generates FooContainerCursor<'a, ...> for structs (enums keep default).
• CursorOf<'a, C> type alias.
• into_index_iter kept as slow-path escape hatch for consuming iteration.
• New benches, tests covering word boundaries and empty ranges.

🤖 Generated with Claude Code