Struct SparseIterState 

pub struct SparseIterState<I, T> {
    len: usize,
    iter: RefCell<Option<(I, usize)>>,
    cache: RefCell<BTreeMap<usize, T>>,
}

Core state for sparse iterator-backed ALTREP vectors.

Unlike super::IterState, this variant uses Iterator::nth() to skip elements efficiently, only caching the elements that are actually accessed.

Type Parameters

• I: The iterator type
• T: The element type produced by the iterator

Design

• Sparse: Only accessed elements are cached (uses BTreeMap)
• Skipping: Uses nth() to skip directly to requested indices
• Trade-off: Skipped elements are gone forever (iterator is consumed)
• Best for: Large iterators where only a small subset of elements are accessed

Comparison with IterState

Feature	IterState	SparseIterState
Cache storage	Contiguous Vec<T>	Sparse BTreeMap<usize, T>
Access pattern	Prefix (0..=i) cached	Only accessed indices cached
Skipped elements	All cached	Gone forever (return NA)
Memory for sparse access	O(max_index)	O(num_accessed)
as_slice() support	Yes (after full materialization)	No (sparse)

Example

use miniextendr_api::altrep_data::SparseIterIntData;

// Create from an infinite-ish iterator
let data = SparseIterIntData::from_iter((0..).map(|x| x * 2), 1_000_000);

// Access only element 999_999 - skips directly there
let last = data.elt(999_999);  // Only this element is generated

// Element 0 was skipped and is now inaccessible
let first = data.elt(0);  // Returns NA_INTEGER

Fields

len: usize

Vector length

iter: RefCell<Option<(I, usize)>>

Iterator state: (iterator, next index the iterator will produce)

cache: RefCell<BTreeMap<usize, T>>

Sparse cache of accessed elements

Implementations

impl<I, T> SparseIterState<I, T>

where I: Iterator<Item = T>,

pub fn new(iter: I, len: usize) -> Self

Create a new sparse iterator state with an explicit length.

Arguments

• iter: The iterator to wrap
• len: The expected number of elements

pub fn get_element(&self, i: usize) -> Option<T>

where T: Copy,

Get an element, skipping intermediate elements if needed.

Uses Iterator::nth() to skip efficiently. Skipped elements are consumed from the iterator and cannot be retrieved later.

Returns

• Some(T) if element exists and is accessible
• None if:
  • Index is out of bounds
  • Element was already skipped (iterator advanced past it)
  • Iterator exhausted before reaching the index

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

Get the current iterator position (next index to be produced).

Returns None if the iterator has been exhausted.

pub fn is_cached(&self, i: usize) -> bool

Check if an element has been cached.

pub fn cached_count(&self) -> usize

Get the number of cached elements.

pub fn len(&self) -> usize

Get the current length.

pub fn is_empty(&self) -> bool

Check if the vector is empty.

impl<I, T> SparseIterState<I, T>

where I: ExactSizeIterator<Item = T>,

pub fn from_exact_size(iter: I) -> Self

Create a new sparse iterator state from an ExactSizeIterator.