Struct IterState 

pub struct IterState<I, T> {
    len: usize,
    iter: RefCell<Option<I>>,
    cache: RefCell<Vec<T>>,
    materialized: OnceLock<Vec<T>>,
}

Core state for iterator-backed ALTREP vectors.

Provides lazy element generation with caching for random-access semantics. Iterator elements are cached as they’re accessed, enabling repeatable reads.

Type Parameters

• I: The iterator type (must be ExactSizeIterator or provide explicit length)
• T: The element type produced by the iterator

Design

• Lazy: Elements generated on-demand via elt(i)
• Cached: Once generated, elements stored in cache for repeat access
• Materializable: Can be fully materialized for Dataptr or serialization
• Safe: Uses RefCell for interior mutability, protected by R’s GC

Fields

len: usize

Vector length (from ExactSizeIterator::len() or explicit)

iter: RefCell<Option<I>>

Iterator state (consumed as we advance)

cache: RefCell<Vec<T>>

Cache of generated elements (prefix of the vector)

materialized: OnceLock<Vec<T>>

Full materialization (when all elements have been generated)

Implementations

impl<I, T> IterState<I, T>

where I: Iterator<Item = T>,

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

Create a new iterator state with an explicit length.

Arguments

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

Length Mismatch

If the iterator produces a different number of elements than len:

• Fewer elements: Missing indices return None/NA/default values
• More elements: Extra elements are ignored (truncated to len)

A warning is printed to stderr when a mismatch is detected.

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

where T: Copy,

Ensure the element at index i is in the cache and return it by value.

Advances the iterator as needed. Only works for Copy types.

Returns

• Some(T) if element exists and has been generated
• None if index is out of bounds or iterator exhausted before reaching index i

pub fn materialize_all(&self) -> &[T]

Materialize all remaining elements from the iterator.

After this call, all elements are guaranteed to be in memory and as_materialized() will return Some.

Length Mismatch Handling

If the iterator produces fewer elements than declared len, the missing elements are left uninitialized in the cache (callers should handle this via bounds checking). If the iterator produces more elements than declared, extra elements are silently ignored (truncated to len).

A warning is printed to stderr if a length mismatch is detected.

pub fn as_materialized(&self) -> Option<&[T]>

Get the materialized vector if all elements have been generated.

Returns None if not yet fully materialized.

pub fn len(&self) -> usize

Get the current length.

pub fn is_empty(&self) -> bool

Check if the vector is empty.

impl<I, T> IterState<I, T>

where I: ExactSizeIterator<Item = T>,

pub fn from_exact_size(iter: I) -> Self

Create a new iterator state from an ExactSizeIterator.

The length is automatically determined from iter.len().