Struct Cursor 

pub struct Cursor<'a, K: ByteKey, T, PTR: TrieIndex, LEN: TrieIndex> { /* private fields */ }

Public iteration cursor over a NibbleTrie: a linear scan of the sparse index, skipping None gaps. This is correct because the index is kept sorted by invariant — occupied slots appear in non-decreasing key order (enforced by the Stage B shift-and-bump insert, and checked by the invariant-oracle tests).

iter() parks before the first key (current() is None, next() yields the first key — the idiomatic Iterator model); iter_last() parks on the last key (current() returns it, prev() walks backward). seek lands in O(keylen) via the internal tree walker, then next/prev resume the linear scan. first/last jump to the ends. The current key/value is cached at park time, so current() (and a next().current() follow-up) is a pure field read with no re-scan.

The cached refs borrow the trie (lifetime 'a), not the cursor, so the &'a T returned by current/next/prev/seek outlives the cursor borrow. The key is returned as ByteKey::Borrowed<'a> (via ByteKey::as_borrowed) — a zero-allocation view into the trie’s key buffer (&'a [u8] for Vec<u8> keys, &'a str for String keys). The slice is cached internally, so current()/next() pay only the as_borrowed view (no allocation, no re-scan).

Implementations

impl<'a, K: ByteKey, T, PTR: TrieIndex, LEN: TrieIndex> Cursor<'a, K, T, PTR, LEN>

pub fn new(trie: &'a NibbleTrie<K, T, PTR, LEN>) -> Self

Forward cursor parked before the first key.

pub fn new_last(trie: &'a NibbleTrie<K, T, PTR, LEN>) -> Self

Reverse cursor parked on the last key (or before-first if empty).

pub fn first(&mut self) -> Option<(K::Borrowed<'a>, &'a T)>

Jump to the first key (smallest slot). Returns its key/value, or None if the trie is empty. Scans forward from slot 1.

pub fn last(&mut self) -> Option<(K::Borrowed<'a>, &'a T)>

Jump to the last key (largest slot). Returns its key/value, or None if the trie is empty. Scans backward from the end of index.

pub fn current(&self) -> Option<(K::Borrowed<'a>, &'a T)>

The key/value the cursor is parked on, or None if not parked (before first, or exhausted). A pure field read — the slice/value pair is cached by park; only the zero-alloc as_borrowed view runs per call.

pub fn current_index(&self) -> Option<usize>

The slot index the cursor is parked on, or None if not parked.

pub fn next(&mut self) -> Option<(K::Borrowed<'a>, &'a T)>

Advance to the next occupied slot and return its key/value. Returns None (parking at the forward-exhausted sentinel) when no further key exists.

pub fn prev(&mut self) -> Option<(K::Borrowed<'a>, &'a T)>

Step to the previous occupied slot and return its key/value. Returns None (parking at the before-first sentinel) when no prior key exists.

pub fn next_index(&mut self) -> Option<usize>

pub fn prev_index(&mut self) -> Option<usize>

pub fn seek(&mut self, key: &[u8]) -> Option<(K::Borrowed<'a>, &'a T)>

Land on the first key ≥ key — O(keylen) via the internal tree walker — then return its key/value. Returns None if no key is ≥ key.