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
• Borrow-checked: Uses RefCell for interior mutability on the R thread

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

get_element returns None for a missing index. materialize_all requires the complete declared prefix and panics if the source ends early. Neither reads past len.

pub fn from_values(values: Vec<T>) -> Self

Restore a realized sequence without constructing or advancing an iterator.

The iterator type is retained, but its state is absent: all reads use the supplied values. This supports deserialization even when I: !Default.

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 exactly the declared prefix, including already cached elements.

Does not request an element beyond len, including when len is zero or the source is infinite. On success, Self::as_materialized returns a slice whose length is exactly Self::len.

Panics

If the source ends before the declared length. The partial prefix stays cached, but is never published as a complete buffer. A failed attempt drops the iterator; another attempt cannot resume an exhausted source.

pub fn try_materialize_all(&self) -> Result<&[T], usize>

Self::materialize_all without the panic: Err carries the number of elements the source produced before it ended.

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().

Trait Implementations

impl<I: Clone, T: Clone> Clone for IterState<I, T>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

Layout

Note: Unable to compute type layout, possibly due to this type having generic parameters. Layout can only be computed for concrete, fully-instantiated types.