Struct Virtualizer 

pub struct Virtualizer<K = ItemKey> { /* private fields */ }

A headless virtualization engine.

This type is intentionally UI-agnostic:

• It does not hold any UI objects.
• Your adapter drives it by providing viewport geometry and scroll offsets.
• Rendering is exposed via zero-allocation iteration APIs (for_each_virtual_*).

For smooth scrolling / tweens / anchoring patterns, see the virtualizer-adapter crate.

Implementations

impl<K: KeyCacheKey> Virtualizer<K>

pub fn new(options: VirtualizerOptions<K>) -> Self

Creates a new virtualizer from options.

If options.initial_rect and/or options.initial_offset are set, those values are applied immediately.

Examples found in repository

examples/basic.rs (line 5)

fn main() {
    let mut v = Virtualizer::new(VirtualizerOptions::new(1_000_000, |_| 1));
    v.set_viewport_and_scroll(10, 123_456);

    let mut items = Vec::new();
    v.for_each_virtual_item(|it| items.push(it));
    println!("total_size={}", v.total_size());
    println!("visible_range={:?}", v.virtual_range());
    println!("first_visible={:?}", items.first());

    let off = v.scroll_to_index_offset(999_999, Align::End);
    v.set_scroll_offset_clamped(off);
    println!("after scroll_to_index: offset={}", v.scroll_offset());
}

examples/keyed_reorder.rs (line 6)

fn main() {
    // Example: measurements follow keys after reorder.
    let mut v = Virtualizer::new(VirtualizerOptions::new(2, |_| 1));
    v.measure(0, 10);
    println!(
        "before reorder: size0={:?} size1={:?}",
        v.item_size(0),
        v.item_size(1)
    );

    // Simulate data reorder by changing the key mapping.
    v.set_get_item_key(|i| if i == 0 { 1 } else { 0 });
    // Note: in real apps you usually keep `get_item_key` stable and call `sync_item_keys()` when
    // your underlying dataset is reordered while `count` stays the same.

    println!(
        "after reorder: size0={:?} size1={:?}",
        v.item_size(0),
        v.item_size(1)
    );
}

examples/measurement_cache.rs (line 9)

fn main() {
    // Example: export and import measurement cache (key -> measured size).
    //
    // This is useful if you want to persist measurements across screens/sessions so that the
    // virtualizer can start with better estimates and avoid re-measuring everything.
    let mut v1 = Virtualizer::new(VirtualizerOptions::new(10, |_| 1));
    v1.measure(2, 10);
    v1.measure(5, 42);

    let snapshot = v1.export_measurement_cache();
    println!("exported_cache_len={}", snapshot.len());

    let mut v2 = Virtualizer::new(VirtualizerOptions::new(10, |_| 1));
    println!(
        "before import: size2={:?} size5={:?}",
        v2.item_size(2),
        v2.item_size(5)
    );

    v2.import_measurement_cache(snapshot);
    println!(
        "after import: cache_len={} size2={:?} size5={:?}",
        v2.measurement_cache_len(),
        v2.item_size(2),
        v2.item_size(5)
    );
}

examples/dynamic_measurement.rs (line 6)

fn main() {
    // Example: dynamic measurement + scroll jump prevention.
    let mut v = Virtualizer::new(VirtualizerOptions::new(100, |_| 10));
    v.set_viewport_and_scroll_clamped(30, 200);

    println!(
        "before: off={} total={} range={:?}",
        v.scroll_offset(),
        v.total_size(),
        v.virtual_range()
    );

    // If an item before the viewport changes size, `resize_item` can adjust scroll_offset to
    // prevent visual jumps.
    let applied = v.resize_item(0, 30);
    println!(
        "resize_item(0): applied_delta={applied} off={} total={}",
        v.scroll_offset(),
        v.total_size()
    );

    // Measuring an item updates sizes and may adjust scroll (TanStack-aligned behavior).
    v.measure(1, 50);
    println!(
        "measure(1): off={} total={}",
        v.scroll_offset(),
        v.total_size()
    );

    // If you want to update measurements without changing scroll, use `measure_unadjusted`.
    v.measure_unadjusted(2, 30);

    // Scroll-to helpers still work with updated measurements.
    let to = v.scroll_to_index_offset(10, Align::Start);
    v.set_scroll_offset_clamped(to);
    println!(
        "set_scroll_offset_clamped(scroll_to_index_offset(10)): off={} range={:?}",
        v.scroll_offset(),
        v.virtual_range()
    );
}

examples/tween_scroll.rs (line 49)

fn main() {
    // Simulate an adapter that drives scroll_offset with a tween.
    let mut v = Virtualizer::new(VirtualizerOptions::new(10_000, |_| 1));
    v.set_viewport_and_scroll_clamped(20, 0);

    let to = v.scroll_to_index_offset(2_000, Align::Center);
    let mut tween = Tween::new(v.scroll_offset(), to, 0, 240);

    let mut now_ms = 0u64;
    let mut frame = 0u64;

    loop {
        // Simulate a 60fps "tick".
        now_ms = now_ms.saturating_add(16);
        frame += 1;

        // Adapter samples tween and writes it into the virtualizer.
        let off = tween.sample(now_ms);
        v.apply_scroll_offset_event_clamped(off, now_ms);

        // Render: a UI would iterate items and draw them.
        let mut first: Option<usize> = None;
        let mut last: Option<usize> = None;
        v.for_each_virtual_item(|it| {
            first.get_or_insert(it.index);
            last = Some(it.index);
        });

        if frame.is_multiple_of(5) {
            println!(
                "t={now_ms}ms off={} visible={:?} first={:?} last={:?}",
                v.scroll_offset(),
                v.visible_range(),
                first,
                last
            );
        }

        // Simulate user input interrupting the animation:
        // at ~120ms, retarget to a new index.
        if (120..120 + 16).contains(&now_ms) {
            let new_to = v.scroll_to_index_offset(7_500, Align::Start);
            tween.retarget(now_ms, new_to, 300);
        }

        if tween.is_done(now_ms) {
            break;
        }
    }

    // Mark scroll as finished for adapters that use this state.
    v.set_is_scrolling(false);

    println!(
        "done: off={} range={:?}",
        v.scroll_offset(),
        v.virtual_range()
    );
}

examples/pinned_headers.rs (line 42)

fn main() {
    // Example: pinned/sticky "headers" at fixed indexes.
    let mut opts = VirtualizerOptions::new(1_000, |_| 1);
    opts.overscan = 2;

    let pinned: Arc<[usize]> = Arc::from([0usize, 10, 20, 30, 40, 999]);
    opts.range_extractor = Some(Arc::new({
        let pinned = Arc::clone(&pinned);
        move |r: Range, emit: &mut dyn FnMut(usize)| {
            let mut e = IndexEmitter::new(r, emit);
            // IMPORTANT: indexes must be emitted in ascending order.
            //
            // We want pinned rows both before and after the overscanned range. To keep the output
            // sorted, emit:
            // 1) pinned indexes before the overscanned range
            // 2) the overscanned contiguous range
            // 3) pinned indexes after the overscanned range
            let overscanned_start = r.start_index.saturating_sub(r.overscan);
            let overscanned_end = r.end_index.saturating_add(r.overscan).min(r.count);

            for &idx in pinned.iter() {
                if idx < overscanned_start {
                    e.emit_pinned(idx);
                }
            }

            e.emit_overscanned();

            for &idx in pinned.iter() {
                if idx >= overscanned_end {
                    e.emit_pinned(idx);
                }
            }
        }
    }));

    let mut v = Virtualizer::new(opts);
    v.set_viewport_and_scroll_clamped(10, 500);

    let mut collected = Vec::new();
    v.for_each_virtual_index(|i| collected.push(i));

    println!("visible_range={:?}", v.visible_range());
    println!("virtual_range={:?}", v.virtual_range());
    println!(
        "indexes_len={} first_20={:?}",
        collected.len(),
        &collected[..20.min(collected.len())]
    );

    // A real UI would typically iterate items:
    let mut headers = 0usize;
    v.for_each_virtual_item(|it| {
        if pinned.binary_search(&it.index).is_ok() {
            headers += 1;
        }
    });
    println!("pinned_headers_in_output={headers}");
}

Additional examples can be found in:

• examples/adapter_sim.rs

pub fn options(&self) -> &VirtualizerOptions<K>

pub fn set_options(&mut self, options: VirtualizerOptions<K>)

pub fn update_options(&mut self, f: impl FnOnce(&mut VirtualizerOptions<K>))

Clones the current options, applies f, then delegates to set_options.

This is useful when you want to update multiple options at once while letting the virtualizer decide what needs to be rebuilt (estimates/fenwick/reset).

pub fn set_on_change( &mut self, on_change: Option<impl Fn(&Virtualizer<K>, bool) + Send + Sync + 'static>, )

pub fn set_initial_offset(&mut self, initial_offset: u64)

pub fn set_initial_offset_provider( &mut self, initial_offset: impl Fn() -> u64 + Send + Sync + 'static, )

pub fn set_use_scrollend_event(&mut self, use_scrollend_event: bool)

pub fn set_is_scrolling_reset_delay_ms(&mut self, delay_ms: u64)

pub fn batch_update(&mut self, f: impl FnOnce(&mut Self))

Batches multiple updates into a single on_change notification.

This is recommended for UI adapters: on a typical frame, you might update the scroll rect, scroll offset, and is_scrolling state together. Without batching, each setter may trigger on_change, which can be expensive if the callback drives rendering.

pub fn count(&self) -> usize

pub fn enabled(&self) -> bool

pub fn set_enabled(&mut self, enabled: bool)

Examples found in repository

examples/adapter_sim.rs (line 73)

fn main() {
    // Simulate a framework adapter that owns the scroll state.
    let saved_scroll = Arc::new(AtomicU64::new(120));

    let opts = VirtualizerOptions::new(1000, |_| 1)
        .with_initial_rect(Some(Rect {
            main: 10,
            cross: 80,
        }))
        .with_initial_offset_provider({
            let saved_scroll = Arc::clone(&saved_scroll);
            move || saved_scroll.load(Ordering::Relaxed)
        })
        .with_scroll_margin(5)
        .with_range_extractor(Some(|r: Range, emit: &mut dyn FnMut(usize)| {
            // Pin a "sticky header" at index 0, regardless of scroll position.
            let mut e = virtualizer::IndexEmitter::new(r, emit);
            e.emit_pinned(0);
            e.emit_visible();
        }));

    let mut v = Virtualizer::new(opts);

    // First render: scroll offset comes from the provider.
    println!("initial scroll_offset={}", v.scroll_offset());
    println!("initial scroll_rect={:?}", v.scroll_rect());

    // Adapter updates rect + scroll offset on events.
    v.apply_scroll_frame(
        Rect {
            main: 12,
            cross: 80,
        },
        200,
        0,
    );

    let mut items = Vec::new();
    v.for_each_virtual_item_keyed(|it| items.push(it));
    println!(
        "is_scrolling={}, visible_range={:?}, items_len={}",
        v.is_scrolling(),
        v.visible_range(),
        items.len()
    );
    println!("first_item={:?}", items.first());

    // Demonstrate scroll-to helpers.
    let target = v.scroll_to_index_offset(500, Align::Start);
    v.set_scroll_offset_clamped(target);
    println!("after scroll_to_index: scroll_offset={}", v.scroll_offset());

    // Demonstrate dynamic measurement + scroll adjustment.
    let applied = v.resize_item(0, 20);
    println!("resize_item applied_scroll_adjustment={applied}");

    // Simulate reorder: change key mapping. This automatically rebuilds per-index sizes from the
    // key-based measurement cache. In real apps, you usually keep `get_item_key` stable and call
    // `sync_item_keys()` when your dataset is reordered while `count` stays the same.
    v.set_get_item_key(|i| if i == 0 { 1 } else { i as u64 });

    // Debounced scrolling reset without relying on a native scrollend event.
    v.update_scrolling(200);
    println!("after update_scrolling: is_scrolling={}", v.is_scrolling());

    // Toggle enabled to disable all queries.
    v.set_enabled(false);
    let mut disabled_len = 0usize;
    v.for_each_virtual_item(|_| disabled_len += 1);
    println!(
        "disabled total_size={}, items_len={}",
        v.total_size(),
        disabled_len
    );
}

pub fn is_scrolling(&self) -> bool

Examples found in repository

examples/adapter_sim.rs (line 48)

fn main() {
    // Simulate a framework adapter that owns the scroll state.
    let saved_scroll = Arc::new(AtomicU64::new(120));

    let opts = VirtualizerOptions::new(1000, |_| 1)
        .with_initial_rect(Some(Rect {
            main: 10,
            cross: 80,
        }))
        .with_initial_offset_provider({
            let saved_scroll = Arc::clone(&saved_scroll);
            move || saved_scroll.load(Ordering::Relaxed)
        })
        .with_scroll_margin(5)
        .with_range_extractor(Some(|r: Range, emit: &mut dyn FnMut(usize)| {
            // Pin a "sticky header" at index 0, regardless of scroll position.
            let mut e = virtualizer::IndexEmitter::new(r, emit);
            e.emit_pinned(0);
            e.emit_visible();
        }));

    let mut v = Virtualizer::new(opts);

    // First render: scroll offset comes from the provider.
    println!("initial scroll_offset={}", v.scroll_offset());
    println!("initial scroll_rect={:?}", v.scroll_rect());

    // Adapter updates rect + scroll offset on events.
    v.apply_scroll_frame(
        Rect {
            main: 12,
            cross: 80,
        },
        200,
        0,
    );

    let mut items = Vec::new();
    v.for_each_virtual_item_keyed(|it| items.push(it));
    println!(
        "is_scrolling={}, visible_range={:?}, items_len={}",
        v.is_scrolling(),
        v.visible_range(),
        items.len()
    );
    println!("first_item={:?}", items.first());

    // Demonstrate scroll-to helpers.
    let target = v.scroll_to_index_offset(500, Align::Start);
    v.set_scroll_offset_clamped(target);
    println!("after scroll_to_index: scroll_offset={}", v.scroll_offset());

    // Demonstrate dynamic measurement + scroll adjustment.
    let applied = v.resize_item(0, 20);
    println!("resize_item applied_scroll_adjustment={applied}");

    // Simulate reorder: change key mapping. This automatically rebuilds per-index sizes from the
    // key-based measurement cache. In real apps, you usually keep `get_item_key` stable and call
    // `sync_item_keys()` when your dataset is reordered while `count` stays the same.
    v.set_get_item_key(|i| if i == 0 { 1 } else { i as u64 });

    // Debounced scrolling reset without relying on a native scrollend event.
    v.update_scrolling(200);
    println!("after update_scrolling: is_scrolling={}", v.is_scrolling());

    // Toggle enabled to disable all queries.
    v.set_enabled(false);
    let mut disabled_len = 0usize;
    v.for_each_virtual_item(|_| disabled_len += 1);
    println!(
        "disabled total_size={}, items_len={}",
        v.total_size(),
        disabled_len
    );
}

pub fn scroll_direction(&self) -> Option<ScrollDirection>

pub fn set_is_scrolling(&mut self, is_scrolling: bool)

Examples found in repository

examples/tween_scroll.rs (line 98)

fn main() {
    // Simulate an adapter that drives scroll_offset with a tween.
    let mut v = Virtualizer::new(VirtualizerOptions::new(10_000, |_| 1));
    v.set_viewport_and_scroll_clamped(20, 0);

    let to = v.scroll_to_index_offset(2_000, Align::Center);
    let mut tween = Tween::new(v.scroll_offset(), to, 0, 240);

    let mut now_ms = 0u64;
    let mut frame = 0u64;

    loop {
        // Simulate a 60fps "tick".
        now_ms = now_ms.saturating_add(16);
        frame += 1;

        // Adapter samples tween and writes it into the virtualizer.
        let off = tween.sample(now_ms);
        v.apply_scroll_offset_event_clamped(off, now_ms);

        // Render: a UI would iterate items and draw them.
        let mut first: Option<usize> = None;
        let mut last: Option<usize> = None;
        v.for_each_virtual_item(|it| {
            first.get_or_insert(it.index);
            last = Some(it.index);
        });

        if frame.is_multiple_of(5) {
            println!(
                "t={now_ms}ms off={} visible={:?} first={:?} last={:?}",
                v.scroll_offset(),
                v.visible_range(),
                first,
                last
            );
        }

        // Simulate user input interrupting the animation:
        // at ~120ms, retarget to a new index.
        if (120..120 + 16).contains(&now_ms) {
            let new_to = v.scroll_to_index_offset(7_500, Align::Start);
            tween.retarget(now_ms, new_to, 300);
        }

        if tween.is_done(now_ms) {
            break;
        }
    }

    // Mark scroll as finished for adapters that use this state.
    v.set_is_scrolling(false);

    println!(
        "done: off={} range={:?}",
        v.scroll_offset(),
        v.virtual_range()
    );
}

pub fn notify_scroll_event(&mut self, now_ms: u64)

pub fn update_scrolling(&mut self, now_ms: u64)

Examples found in repository

examples/adapter_sim.rs (line 69)

fn main() {
    // Simulate a framework adapter that owns the scroll state.
    let saved_scroll = Arc::new(AtomicU64::new(120));

    let opts = VirtualizerOptions::new(1000, |_| 1)
        .with_initial_rect(Some(Rect {
            main: 10,
            cross: 80,
        }))
        .with_initial_offset_provider({
            let saved_scroll = Arc::clone(&saved_scroll);
            move || saved_scroll.load(Ordering::Relaxed)
        })
        .with_scroll_margin(5)
        .with_range_extractor(Some(|r: Range, emit: &mut dyn FnMut(usize)| {
            // Pin a "sticky header" at index 0, regardless of scroll position.
            let mut e = virtualizer::IndexEmitter::new(r, emit);
            e.emit_pinned(0);
            e.emit_visible();
        }));

    let mut v = Virtualizer::new(opts);

    // First render: scroll offset comes from the provider.
    println!("initial scroll_offset={}", v.scroll_offset());
    println!("initial scroll_rect={:?}", v.scroll_rect());

    // Adapter updates rect + scroll offset on events.
    v.apply_scroll_frame(
        Rect {
            main: 12,
            cross: 80,
        },
        200,
        0,
    );

    let mut items = Vec::new();
    v.for_each_virtual_item_keyed(|it| items.push(it));
    println!(
        "is_scrolling={}, visible_range={:?}, items_len={}",
        v.is_scrolling(),
        v.visible_range(),
        items.len()
    );
    println!("first_item={:?}", items.first());

    // Demonstrate scroll-to helpers.
    let target = v.scroll_to_index_offset(500, Align::Start);
    v.set_scroll_offset_clamped(target);
    println!("after scroll_to_index: scroll_offset={}", v.scroll_offset());

    // Demonstrate dynamic measurement + scroll adjustment.
    let applied = v.resize_item(0, 20);
    println!("resize_item applied_scroll_adjustment={applied}");

    // Simulate reorder: change key mapping. This automatically rebuilds per-index sizes from the
    // key-based measurement cache. In real apps, you usually keep `get_item_key` stable and call
    // `sync_item_keys()` when your dataset is reordered while `count` stays the same.
    v.set_get_item_key(|i| if i == 0 { 1 } else { i as u64 });

    // Debounced scrolling reset without relying on a native scrollend event.
    v.update_scrolling(200);
    println!("after update_scrolling: is_scrolling={}", v.is_scrolling());

    // Toggle enabled to disable all queries.
    v.set_enabled(false);
    let mut disabled_len = 0usize;
    v.for_each_virtual_item(|_| disabled_len += 1);
    println!(
        "disabled total_size={}, items_len={}",
        v.total_size(),
        disabled_len
    );
}

pub fn viewport_size(&self) -> u32

pub fn scroll_rect(&self) -> Rect

Examples found in repository

examples/adapter_sim.rs (line 32)

fn main() {
    // Simulate a framework adapter that owns the scroll state.
    let saved_scroll = Arc::new(AtomicU64::new(120));

    let opts = VirtualizerOptions::new(1000, |_| 1)
        .with_initial_rect(Some(Rect {
            main: 10,
            cross: 80,
        }))
        .with_initial_offset_provider({
            let saved_scroll = Arc::clone(&saved_scroll);
            move || saved_scroll.load(Ordering::Relaxed)
        })
        .with_scroll_margin(5)
        .with_range_extractor(Some(|r: Range, emit: &mut dyn FnMut(usize)| {
            // Pin a "sticky header" at index 0, regardless of scroll position.
            let mut e = virtualizer::IndexEmitter::new(r, emit);
            e.emit_pinned(0);
            e.emit_visible();
        }));

    let mut v = Virtualizer::new(opts);

    // First render: scroll offset comes from the provider.
    println!("initial scroll_offset={}", v.scroll_offset());
    println!("initial scroll_rect={:?}", v.scroll_rect());

    // Adapter updates rect + scroll offset on events.
    v.apply_scroll_frame(
        Rect {
            main: 12,
            cross: 80,
        },
        200,
        0,
    );

    let mut items = Vec::new();
    v.for_each_virtual_item_keyed(|it| items.push(it));
    println!(
        "is_scrolling={}, visible_range={:?}, items_len={}",
        v.is_scrolling(),
        v.visible_range(),
        items.len()
    );
    println!("first_item={:?}", items.first());

    // Demonstrate scroll-to helpers.
    let target = v.scroll_to_index_offset(500, Align::Start);
    v.set_scroll_offset_clamped(target);
    println!("after scroll_to_index: scroll_offset={}", v.scroll_offset());

    // Demonstrate dynamic measurement + scroll adjustment.
    let applied = v.resize_item(0, 20);
    println!("resize_item applied_scroll_adjustment={applied}");

    // Simulate reorder: change key mapping. This automatically rebuilds per-index sizes from the
    // key-based measurement cache. In real apps, you usually keep `get_item_key` stable and call
    // `sync_item_keys()` when your dataset is reordered while `count` stays the same.
    v.set_get_item_key(|i| if i == 0 { 1 } else { i as u64 });

    // Debounced scrolling reset without relying on a native scrollend event.
    v.update_scrolling(200);
    println!("after update_scrolling: is_scrolling={}", v.is_scrolling());

    // Toggle enabled to disable all queries.
    v.set_enabled(false);
    let mut disabled_len = 0usize;
    v.for_each_virtual_item(|_| disabled_len += 1);
    println!(
        "disabled total_size={}, items_len={}",
        v.total_size(),
        disabled_len
    );
}

pub fn viewport_state(&self) -> ViewportState

Returns a lightweight snapshot of the current viewport state.

pub fn scroll_state(&self) -> ScrollState

Returns a lightweight snapshot of the current scroll state.

pub fn frame_state(&self) -> FrameState

Returns a combined snapshot of viewport + scroll state.

pub fn restore_viewport_state(&mut self, viewport: ViewportState)

Restores viewport geometry from a previously captured snapshot.

pub fn restore_scroll_state(&mut self, scroll: ScrollState, now_ms: u64)

Restores scroll state from a previously captured snapshot.

When scroll.is_scrolling is true, this will update the internal scrolling timers as if a scroll event happened at now_ms.

pub fn restore_frame_state(&mut self, frame: FrameState, now_ms: u64)

Restores both viewport + scroll state from a previously captured snapshot.

When frame.scroll.is_scrolling is true, this will update the internal scrolling timers as if a scroll event happened at now_ms.

pub fn set_scroll_rect(&mut self, rect: Rect)

pub fn apply_scroll_rect_event(&mut self, rect: Rect)

Applies a scroll rect update from your UI layer.

Prefer this (or apply_scroll_frame*) over calling multiple setters when you have an on_change callback that may trigger expensive work (like rendering/layout).

pub fn scroll_offset(&self) -> u64

Examples found in repository

examples/basic.rs (line 16)

fn main() {
    let mut v = Virtualizer::new(VirtualizerOptions::new(1_000_000, |_| 1));
    v.set_viewport_and_scroll(10, 123_456);

    let mut items = Vec::new();
    v.for_each_virtual_item(|it| items.push(it));
    println!("total_size={}", v.total_size());
    println!("visible_range={:?}", v.virtual_range());
    println!("first_visible={:?}", items.first());

    let off = v.scroll_to_index_offset(999_999, Align::End);
    v.set_scroll_offset_clamped(off);
    println!("after scroll_to_index: offset={}", v.scroll_offset());
}

examples/dynamic_measurement.rs (line 11)

fn main() {
    // Example: dynamic measurement + scroll jump prevention.
    let mut v = Virtualizer::new(VirtualizerOptions::new(100, |_| 10));
    v.set_viewport_and_scroll_clamped(30, 200);

    println!(
        "before: off={} total={} range={:?}",
        v.scroll_offset(),
        v.total_size(),
        v.virtual_range()
    );

    // If an item before the viewport changes size, `resize_item` can adjust scroll_offset to
    // prevent visual jumps.
    let applied = v.resize_item(0, 30);
    println!(
        "resize_item(0): applied_delta={applied} off={} total={}",
        v.scroll_offset(),
        v.total_size()
    );

    // Measuring an item updates sizes and may adjust scroll (TanStack-aligned behavior).
    v.measure(1, 50);
    println!(
        "measure(1): off={} total={}",
        v.scroll_offset(),
        v.total_size()
    );

    // If you want to update measurements without changing scroll, use `measure_unadjusted`.
    v.measure_unadjusted(2, 30);

    // Scroll-to helpers still work with updated measurements.
    let to = v.scroll_to_index_offset(10, Align::Start);
    v.set_scroll_offset_clamped(to);
    println!(
        "set_scroll_offset_clamped(scroll_to_index_offset(10)): off={} range={:?}",
        v.scroll_offset(),
        v.virtual_range()
    );
}

examples/tween_scroll.rs (line 53)

fn main() {
    // Simulate an adapter that drives scroll_offset with a tween.
    let mut v = Virtualizer::new(VirtualizerOptions::new(10_000, |_| 1));
    v.set_viewport_and_scroll_clamped(20, 0);

    let to = v.scroll_to_index_offset(2_000, Align::Center);
    let mut tween = Tween::new(v.scroll_offset(), to, 0, 240);

    let mut now_ms = 0u64;
    let mut frame = 0u64;

    loop {
        // Simulate a 60fps "tick".
        now_ms = now_ms.saturating_add(16);
        frame += 1;

        // Adapter samples tween and writes it into the virtualizer.
        let off = tween.sample(now_ms);
        v.apply_scroll_offset_event_clamped(off, now_ms);

        // Render: a UI would iterate items and draw them.
        let mut first: Option<usize> = None;
        let mut last: Option<usize> = None;
        v.for_each_virtual_item(|it| {
            first.get_or_insert(it.index);
            last = Some(it.index);
        });

        if frame.is_multiple_of(5) {
            println!(
                "t={now_ms}ms off={} visible={:?} first={:?} last={:?}",
                v.scroll_offset(),
                v.visible_range(),
                first,
                last
            );
        }

        // Simulate user input interrupting the animation:
        // at ~120ms, retarget to a new index.
        if (120..120 + 16).contains(&now_ms) {
            let new_to = v.scroll_to_index_offset(7_500, Align::Start);
            tween.retarget(now_ms, new_to, 300);
        }

        if tween.is_done(now_ms) {
            break;
        }
    }

    // Mark scroll as finished for adapters that use this state.
    v.set_is_scrolling(false);

    println!(
        "done: off={} range={:?}",
        v.scroll_offset(),
        v.virtual_range()
    );
}

examples/adapter_sim.rs (line 31)

fn main() {
    // Simulate a framework adapter that owns the scroll state.
    let saved_scroll = Arc::new(AtomicU64::new(120));

    let opts = VirtualizerOptions::new(1000, |_| 1)
        .with_initial_rect(Some(Rect {
            main: 10,
            cross: 80,
        }))
        .with_initial_offset_provider({
            let saved_scroll = Arc::clone(&saved_scroll);
            move || saved_scroll.load(Ordering::Relaxed)
        })
        .with_scroll_margin(5)
        .with_range_extractor(Some(|r: Range, emit: &mut dyn FnMut(usize)| {
            // Pin a "sticky header" at index 0, regardless of scroll position.
            let mut e = virtualizer::IndexEmitter::new(r, emit);
            e.emit_pinned(0);
            e.emit_visible();
        }));

    let mut v = Virtualizer::new(opts);

    // First render: scroll offset comes from the provider.
    println!("initial scroll_offset={}", v.scroll_offset());
    println!("initial scroll_rect={:?}", v.scroll_rect());

    // Adapter updates rect + scroll offset on events.
    v.apply_scroll_frame(
        Rect {
            main: 12,
            cross: 80,
        },
        200,
        0,
    );

    let mut items = Vec::new();
    v.for_each_virtual_item_keyed(|it| items.push(it));
    println!(
        "is_scrolling={}, visible_range={:?}, items_len={}",
        v.is_scrolling(),
        v.visible_range(),
        items.len()
    );
    println!("first_item={:?}", items.first());

    // Demonstrate scroll-to helpers.
    let target = v.scroll_to_index_offset(500, Align::Start);
    v.set_scroll_offset_clamped(target);
    println!("after scroll_to_index: scroll_offset={}", v.scroll_offset());

    // Demonstrate dynamic measurement + scroll adjustment.
    let applied = v.resize_item(0, 20);
    println!("resize_item applied_scroll_adjustment={applied}");

    // Simulate reorder: change key mapping. This automatically rebuilds per-index sizes from the
    // key-based measurement cache. In real apps, you usually keep `get_item_key` stable and call
    // `sync_item_keys()` when your dataset is reordered while `count` stays the same.
    v.set_get_item_key(|i| if i == 0 { 1 } else { i as u64 });

    // Debounced scrolling reset without relying on a native scrollend event.
    v.update_scrolling(200);
    println!("after update_scrolling: is_scrolling={}", v.is_scrolling());

    // Toggle enabled to disable all queries.
    v.set_enabled(false);
    let mut disabled_len = 0usize;
    v.for_each_virtual_item(|_| disabled_len += 1);
    println!(
        "disabled total_size={}, items_len={}",
        v.total_size(),
        disabled_len
    );
}

pub fn scroll_offset_in_list(&self) -> u64

pub fn set_viewport_size(&mut self, size: u32)

pub fn set_scroll_offset(&mut self, offset: u64)

pub fn apply_scroll_offset_event(&mut self, offset: u64, now_ms: u64)

Applies a scroll offset update from your UI layer (e.g. wheel/drag), and marks the virtualizer as scrolling.

pub fn set_scroll_offset_clamped(&mut self, offset: u64)

Examples found in repository

examples/basic.rs (line 15)

fn main() {
    let mut v = Virtualizer::new(VirtualizerOptions::new(1_000_000, |_| 1));
    v.set_viewport_and_scroll(10, 123_456);

    let mut items = Vec::new();
    v.for_each_virtual_item(|it| items.push(it));
    println!("total_size={}", v.total_size());
    println!("visible_range={:?}", v.virtual_range());
    println!("first_visible={:?}", items.first());

    let off = v.scroll_to_index_offset(999_999, Align::End);
    v.set_scroll_offset_clamped(off);
    println!("after scroll_to_index: offset={}", v.scroll_offset());
}

examples/dynamic_measurement.rs (line 38)

fn main() {
    // Example: dynamic measurement + scroll jump prevention.
    let mut v = Virtualizer::new(VirtualizerOptions::new(100, |_| 10));
    v.set_viewport_and_scroll_clamped(30, 200);

    println!(
        "before: off={} total={} range={:?}",
        v.scroll_offset(),
        v.total_size(),
        v.virtual_range()
    );

    // If an item before the viewport changes size, `resize_item` can adjust scroll_offset to
    // prevent visual jumps.
    let applied = v.resize_item(0, 30);
    println!(
        "resize_item(0): applied_delta={applied} off={} total={}",
        v.scroll_offset(),
        v.total_size()
    );

    // Measuring an item updates sizes and may adjust scroll (TanStack-aligned behavior).
    v.measure(1, 50);
    println!(
        "measure(1): off={} total={}",
        v.scroll_offset(),
        v.total_size()
    );

    // If you want to update measurements without changing scroll, use `measure_unadjusted`.
    v.measure_unadjusted(2, 30);

    // Scroll-to helpers still work with updated measurements.
    let to = v.scroll_to_index_offset(10, Align::Start);
    v.set_scroll_offset_clamped(to);
    println!(
        "set_scroll_offset_clamped(scroll_to_index_offset(10)): off={} range={:?}",
        v.scroll_offset(),
        v.virtual_range()
    );
}

examples/adapter_sim.rs (line 56)

fn main() {
    // Simulate a framework adapter that owns the scroll state.
    let saved_scroll = Arc::new(AtomicU64::new(120));

    let opts = VirtualizerOptions::new(1000, |_| 1)
        .with_initial_rect(Some(Rect {
            main: 10,
            cross: 80,
        }))
        .with_initial_offset_provider({
            let saved_scroll = Arc::clone(&saved_scroll);
            move || saved_scroll.load(Ordering::Relaxed)
        })
        .with_scroll_margin(5)
        .with_range_extractor(Some(|r: Range, emit: &mut dyn FnMut(usize)| {
            // Pin a "sticky header" at index 0, regardless of scroll position.
            let mut e = virtualizer::IndexEmitter::new(r, emit);
            e.emit_pinned(0);
            e.emit_visible();
        }));

    let mut v = Virtualizer::new(opts);

    // First render: scroll offset comes from the provider.
    println!("initial scroll_offset={}", v.scroll_offset());
    println!("initial scroll_rect={:?}", v.scroll_rect());

    // Adapter updates rect + scroll offset on events.
    v.apply_scroll_frame(
        Rect {
            main: 12,
            cross: 80,
        },
        200,
        0,
    );

    let mut items = Vec::new();
    v.for_each_virtual_item_keyed(|it| items.push(it));
    println!(
        "is_scrolling={}, visible_range={:?}, items_len={}",
        v.is_scrolling(),
        v.visible_range(),
        items.len()
    );
    println!("first_item={:?}", items.first());

    // Demonstrate scroll-to helpers.
    let target = v.scroll_to_index_offset(500, Align::Start);
    v.set_scroll_offset_clamped(target);
    println!("after scroll_to_index: scroll_offset={}", v.scroll_offset());

    // Demonstrate dynamic measurement + scroll adjustment.
    let applied = v.resize_item(0, 20);
    println!("resize_item applied_scroll_adjustment={applied}");

    // Simulate reorder: change key mapping. This automatically rebuilds per-index sizes from the
    // key-based measurement cache. In real apps, you usually keep `get_item_key` stable and call
    // `sync_item_keys()` when your dataset is reordered while `count` stays the same.
    v.set_get_item_key(|i| if i == 0 { 1 } else { i as u64 });

    // Debounced scrolling reset without relying on a native scrollend event.
    v.update_scrolling(200);
    println!("after update_scrolling: is_scrolling={}", v.is_scrolling());

    // Toggle enabled to disable all queries.
    v.set_enabled(false);
    let mut disabled_len = 0usize;
    v.for_each_virtual_item(|_| disabled_len += 1);
    println!(
        "disabled total_size={}, items_len={}",
        v.total_size(),
        disabled_len
    );
}

pub fn apply_scroll_offset_event_clamped(&mut self, offset: u64, now_ms: u64)

Same as apply_scroll_offset_event, but clamps the offset.

Examples found in repository

examples/tween_scroll.rs (line 65)

fn main() {
    // Simulate an adapter that drives scroll_offset with a tween.
    let mut v = Virtualizer::new(VirtualizerOptions::new(10_000, |_| 1));
    v.set_viewport_and_scroll_clamped(20, 0);

    let to = v.scroll_to_index_offset(2_000, Align::Center);
    let mut tween = Tween::new(v.scroll_offset(), to, 0, 240);

    let mut now_ms = 0u64;
    let mut frame = 0u64;

    loop {
        // Simulate a 60fps "tick".
        now_ms = now_ms.saturating_add(16);
        frame += 1;

        // Adapter samples tween and writes it into the virtualizer.
        let off = tween.sample(now_ms);
        v.apply_scroll_offset_event_clamped(off, now_ms);

        // Render: a UI would iterate items and draw them.
        let mut first: Option<usize> = None;
        let mut last: Option<usize> = None;
        v.for_each_virtual_item(|it| {
            first.get_or_insert(it.index);
            last = Some(it.index);
        });

        if frame.is_multiple_of(5) {
            println!(
                "t={now_ms}ms off={} visible={:?} first={:?} last={:?}",
                v.scroll_offset(),
                v.visible_range(),
                first,
                last
            );
        }

        // Simulate user input interrupting the animation:
        // at ~120ms, retarget to a new index.
        if (120..120 + 16).contains(&now_ms) {
            let new_to = v.scroll_to_index_offset(7_500, Align::Start);
            tween.retarget(now_ms, new_to, 300);
        }

        if tween.is_done(now_ms) {
            break;
        }
    }

    // Mark scroll as finished for adapters that use this state.
    v.set_is_scrolling(false);

    println!(
        "done: off={} range={:?}",
        v.scroll_offset(),
        v.virtual_range()
    );
}

pub fn set_viewport_and_scroll( &mut self, viewport_size: u32, scroll_offset: u64, )

Examples found in repository

examples/basic.rs (line 6)

fn main() {
    let mut v = Virtualizer::new(VirtualizerOptions::new(1_000_000, |_| 1));
    v.set_viewport_and_scroll(10, 123_456);

    let mut items = Vec::new();
    v.for_each_virtual_item(|it| items.push(it));
    println!("total_size={}", v.total_size());
    println!("visible_range={:?}", v.virtual_range());
    println!("first_visible={:?}", items.first());

    let off = v.scroll_to_index_offset(999_999, Align::End);
    v.set_scroll_offset_clamped(off);
    println!("after scroll_to_index: offset={}", v.scroll_offset());
}

pub fn set_viewport_and_scroll_clamped( &mut self, viewport_size: u32, scroll_offset: u64, )

Examples found in repository

examples/dynamic_measurement.rs (line 7)

fn main() {
    // Example: dynamic measurement + scroll jump prevention.
    let mut v = Virtualizer::new(VirtualizerOptions::new(100, |_| 10));
    v.set_viewport_and_scroll_clamped(30, 200);

    println!(
        "before: off={} total={} range={:?}",
        v.scroll_offset(),
        v.total_size(),
        v.virtual_range()
    );

    // If an item before the viewport changes size, `resize_item` can adjust scroll_offset to
    // prevent visual jumps.
    let applied = v.resize_item(0, 30);
    println!(
        "resize_item(0): applied_delta={applied} off={} total={}",
        v.scroll_offset(),
        v.total_size()
    );

    // Measuring an item updates sizes and may adjust scroll (TanStack-aligned behavior).
    v.measure(1, 50);
    println!(
        "measure(1): off={} total={}",
        v.scroll_offset(),
        v.total_size()
    );

    // If you want to update measurements without changing scroll, use `measure_unadjusted`.
    v.measure_unadjusted(2, 30);

    // Scroll-to helpers still work with updated measurements.
    let to = v.scroll_to_index_offset(10, Align::Start);
    v.set_scroll_offset_clamped(to);
    println!(
        "set_scroll_offset_clamped(scroll_to_index_offset(10)): off={} range={:?}",
        v.scroll_offset(),
        v.virtual_range()
    );
}

examples/tween_scroll.rs (line 50)

fn main() {
    // Simulate an adapter that drives scroll_offset with a tween.
    let mut v = Virtualizer::new(VirtualizerOptions::new(10_000, |_| 1));
    v.set_viewport_and_scroll_clamped(20, 0);

    let to = v.scroll_to_index_offset(2_000, Align::Center);
    let mut tween = Tween::new(v.scroll_offset(), to, 0, 240);

    let mut now_ms = 0u64;
    let mut frame = 0u64;

    loop {
        // Simulate a 60fps "tick".
        now_ms = now_ms.saturating_add(16);
        frame += 1;

        // Adapter samples tween and writes it into the virtualizer.
        let off = tween.sample(now_ms);
        v.apply_scroll_offset_event_clamped(off, now_ms);

        // Render: a UI would iterate items and draw them.
        let mut first: Option<usize> = None;
        let mut last: Option<usize> = None;
        v.for_each_virtual_item(|it| {
            first.get_or_insert(it.index);
            last = Some(it.index);
        });

        if frame.is_multiple_of(5) {
            println!(
                "t={now_ms}ms off={} visible={:?} first={:?} last={:?}",
                v.scroll_offset(),
                v.visible_range(),
                first,
                last
            );
        }

        // Simulate user input interrupting the animation:
        // at ~120ms, retarget to a new index.
        if (120..120 + 16).contains(&now_ms) {
            let new_to = v.scroll_to_index_offset(7_500, Align::Start);
            tween.retarget(now_ms, new_to, 300);
        }

        if tween.is_done(now_ms) {
            break;
        }
    }

    // Mark scroll as finished for adapters that use this state.
    v.set_is_scrolling(false);

    println!(
        "done: off={} range={:?}",
        v.scroll_offset(),
        v.virtual_range()
    );
}

examples/pinned_headers.rs (line 43)

fn main() {
    // Example: pinned/sticky "headers" at fixed indexes.
    let mut opts = VirtualizerOptions::new(1_000, |_| 1);
    opts.overscan = 2;

    let pinned: Arc<[usize]> = Arc::from([0usize, 10, 20, 30, 40, 999]);
    opts.range_extractor = Some(Arc::new({
        let pinned = Arc::clone(&pinned);
        move |r: Range, emit: &mut dyn FnMut(usize)| {
            let mut e = IndexEmitter::new(r, emit);
            // IMPORTANT: indexes must be emitted in ascending order.
            //
            // We want pinned rows both before and after the overscanned range. To keep the output
            // sorted, emit:
            // 1) pinned indexes before the overscanned range
            // 2) the overscanned contiguous range
            // 3) pinned indexes after the overscanned range
            let overscanned_start = r.start_index.saturating_sub(r.overscan);
            let overscanned_end = r.end_index.saturating_add(r.overscan).min(r.count);

            for &idx in pinned.iter() {
                if idx < overscanned_start {
                    e.emit_pinned(idx);
                }
            }

            e.emit_overscanned();

            for &idx in pinned.iter() {
                if idx >= overscanned_end {
                    e.emit_pinned(idx);
                }
            }
        }
    }));

    let mut v = Virtualizer::new(opts);
    v.set_viewport_and_scroll_clamped(10, 500);

    let mut collected = Vec::new();
    v.for_each_virtual_index(|i| collected.push(i));

    println!("visible_range={:?}", v.visible_range());
    println!("virtual_range={:?}", v.virtual_range());
    println!(
        "indexes_len={} first_20={:?}",
        collected.len(),
        &collected[..20.min(collected.len())]
    );

    // A real UI would typically iterate items:
    let mut headers = 0usize;
    v.for_each_virtual_item(|it| {
        if pinned.binary_search(&it.index).is_ok() {
            headers += 1;
        }
    });
    println!("pinned_headers_in_output={headers}");
}

pub fn apply_scroll_frame( &mut self, rect: Rect, scroll_offset: u64, now_ms: u64, )

Applies both scroll rect and scroll offset in a single coalesced update.

This is the recommended entry point for UI adapters that receive scroll events along with updated viewport/rect information.

Examples found in repository

examples/adapter_sim.rs (lines 35-42)

fn main() {
    // Simulate a framework adapter that owns the scroll state.
    let saved_scroll = Arc::new(AtomicU64::new(120));

    let opts = VirtualizerOptions::new(1000, |_| 1)
        .with_initial_rect(Some(Rect {
            main: 10,
            cross: 80,
        }))
        .with_initial_offset_provider({
            let saved_scroll = Arc::clone(&saved_scroll);
            move || saved_scroll.load(Ordering::Relaxed)
        })
        .with_scroll_margin(5)
        .with_range_extractor(Some(|r: Range, emit: &mut dyn FnMut(usize)| {
            // Pin a "sticky header" at index 0, regardless of scroll position.
            let mut e = virtualizer::IndexEmitter::new(r, emit);
            e.emit_pinned(0);
            e.emit_visible();
        }));

    let mut v = Virtualizer::new(opts);

    // First render: scroll offset comes from the provider.
    println!("initial scroll_offset={}", v.scroll_offset());
    println!("initial scroll_rect={:?}", v.scroll_rect());

    // Adapter updates rect + scroll offset on events.
    v.apply_scroll_frame(
        Rect {
            main: 12,
            cross: 80,
        },
        200,
        0,
    );

    let mut items = Vec::new();
    v.for_each_virtual_item_keyed(|it| items.push(it));
    println!(
        "is_scrolling={}, visible_range={:?}, items_len={}",
        v.is_scrolling(),
        v.visible_range(),
        items.len()
    );
    println!("first_item={:?}", items.first());

    // Demonstrate scroll-to helpers.
    let target = v.scroll_to_index_offset(500, Align::Start);
    v.set_scroll_offset_clamped(target);
    println!("after scroll_to_index: scroll_offset={}", v.scroll_offset());

    // Demonstrate dynamic measurement + scroll adjustment.
    let applied = v.resize_item(0, 20);
    println!("resize_item applied_scroll_adjustment={applied}");

    // Simulate reorder: change key mapping. This automatically rebuilds per-index sizes from the
    // key-based measurement cache. In real apps, you usually keep `get_item_key` stable and call
    // `sync_item_keys()` when your dataset is reordered while `count` stays the same.
    v.set_get_item_key(|i| if i == 0 { 1 } else { i as u64 });

    // Debounced scrolling reset without relying on a native scrollend event.
    v.update_scrolling(200);
    println!("after update_scrolling: is_scrolling={}", v.is_scrolling());

    // Toggle enabled to disable all queries.
    v.set_enabled(false);
    let mut disabled_len = 0usize;
    v.for_each_virtual_item(|_| disabled_len += 1);
    println!(
        "disabled total_size={}, items_len={}",
        v.total_size(),
        disabled_len
    );
}

pub fn apply_scroll_frame_clamped( &mut self, rect: Rect, scroll_offset: u64, now_ms: u64, )

Same as apply_scroll_frame, but clamps the offset.

pub fn set_count(&mut self, count: usize)

pub fn set_overscan(&mut self, overscan: usize)

pub fn set_padding(&mut self, padding_start: u32, padding_end: u32)

pub fn set_scroll_padding( &mut self, scroll_padding_start: u32, scroll_padding_end: u32, )

pub fn set_scroll_margin(&mut self, scroll_margin: u32)

pub fn set_gap(&mut self, gap: u32)

pub fn set_get_item_key( &mut self, f: impl Fn(usize) -> K + Send + Sync + 'static, )

Examples found in repository

examples/keyed_reorder.rs (line 15)

fn main() {
    // Example: measurements follow keys after reorder.
    let mut v = Virtualizer::new(VirtualizerOptions::new(2, |_| 1));
    v.measure(0, 10);
    println!(
        "before reorder: size0={:?} size1={:?}",
        v.item_size(0),
        v.item_size(1)
    );

    // Simulate data reorder by changing the key mapping.
    v.set_get_item_key(|i| if i == 0 { 1 } else { 0 });
    // Note: in real apps you usually keep `get_item_key` stable and call `sync_item_keys()` when
    // your underlying dataset is reordered while `count` stays the same.

    println!(
        "after reorder: size0={:?} size1={:?}",
        v.item_size(0),
        v.item_size(1)
    );
}

examples/adapter_sim.rs (line 66)

fn main() {
    // Simulate a framework adapter that owns the scroll state.
    let saved_scroll = Arc::new(AtomicU64::new(120));

    let opts = VirtualizerOptions::new(1000, |_| 1)
        .with_initial_rect(Some(Rect {
            main: 10,
            cross: 80,
        }))
        .with_initial_offset_provider({
            let saved_scroll = Arc::clone(&saved_scroll);
            move || saved_scroll.load(Ordering::Relaxed)
        })
        .with_scroll_margin(5)
        .with_range_extractor(Some(|r: Range, emit: &mut dyn FnMut(usize)| {
            // Pin a "sticky header" at index 0, regardless of scroll position.
            let mut e = virtualizer::IndexEmitter::new(r, emit);
            e.emit_pinned(0);
            e.emit_visible();
        }));

    let mut v = Virtualizer::new(opts);

    // First render: scroll offset comes from the provider.
    println!("initial scroll_offset={}", v.scroll_offset());
    println!("initial scroll_rect={:?}", v.scroll_rect());

    // Adapter updates rect + scroll offset on events.
    v.apply_scroll_frame(
        Rect {
            main: 12,
            cross: 80,
        },
        200,
        0,
    );

    let mut items = Vec::new();
    v.for_each_virtual_item_keyed(|it| items.push(it));
    println!(
        "is_scrolling={}, visible_range={:?}, items_len={}",
        v.is_scrolling(),
        v.visible_range(),
        items.len()
    );
    println!("first_item={:?}", items.first());

    // Demonstrate scroll-to helpers.
    let target = v.scroll_to_index_offset(500, Align::Start);
    v.set_scroll_offset_clamped(target);
    println!("after scroll_to_index: scroll_offset={}", v.scroll_offset());

    // Demonstrate dynamic measurement + scroll adjustment.
    let applied = v.resize_item(0, 20);
    println!("resize_item applied_scroll_adjustment={applied}");

    // Simulate reorder: change key mapping. This automatically rebuilds per-index sizes from the
    // key-based measurement cache. In real apps, you usually keep `get_item_key` stable and call
    // `sync_item_keys()` when your dataset is reordered while `count` stays the same.
    v.set_get_item_key(|i| if i == 0 { 1 } else { i as u64 });

    // Debounced scrolling reset without relying on a native scrollend event.
    v.update_scrolling(200);
    println!("after update_scrolling: is_scrolling={}", v.is_scrolling());

    // Toggle enabled to disable all queries.
    v.set_enabled(false);
    let mut disabled_len = 0usize;
    v.for_each_virtual_item(|_| disabled_len += 1);
    println!(
        "disabled total_size={}, items_len={}",
        v.total_size(),
        disabled_len
    );
}

pub fn set_should_adjust_scroll_position_on_item_size_change( &mut self, f: Option<impl Fn(&Virtualizer<K>, VirtualItem, i64) -> bool + Send + Sync + 'static>, )

pub fn sync_item_keys(&mut self)

pub fn set_range_extractor( &mut self, f: Option<impl Fn(Range, &mut dyn FnMut(usize)) + Send + Sync + 'static>, )

pub fn set_estimate_size( &mut self, f: impl Fn(usize) -> u32 + Send + Sync + 'static, )

pub fn reset_measurements(&mut self)

pub fn measurement_cache_len(&self) -> usize

Returns the number of cached measured sizes (key → size).

Examples found in repository

examples/measurement_cache.rs (line 26)

fn main() {
    // Example: export and import measurement cache (key -> measured size).
    //
    // This is useful if you want to persist measurements across screens/sessions so that the
    // virtualizer can start with better estimates and avoid re-measuring everything.
    let mut v1 = Virtualizer::new(VirtualizerOptions::new(10, |_| 1));
    v1.measure(2, 10);
    v1.measure(5, 42);

    let snapshot = v1.export_measurement_cache();
    println!("exported_cache_len={}", snapshot.len());

    let mut v2 = Virtualizer::new(VirtualizerOptions::new(10, |_| 1));
    println!(
        "before import: size2={:?} size5={:?}",
        v2.item_size(2),
        v2.item_size(5)
    );

    v2.import_measurement_cache(snapshot);
    println!(
        "after import: cache_len={} size2={:?} size5={:?}",
        v2.measurement_cache_len(),
        v2.item_size(2),
        v2.item_size(5)
    );
}

pub fn for_each_cached_size(&self, f: impl FnMut(&K, u32))

Iterates over the cached measured sizes (key → size) without allocations.

pub fn export_measurement_cache(&self) -> Vec<(K, u32)>

where K: Clone,

Exports the cached measured sizes as a Vec (useful for persistence).

Examples found in repository

examples/measurement_cache.rs (line 13)

fn main() {
    // Example: export and import measurement cache (key -> measured size).
    //
    // This is useful if you want to persist measurements across screens/sessions so that the
    // virtualizer can start with better estimates and avoid re-measuring everything.
    let mut v1 = Virtualizer::new(VirtualizerOptions::new(10, |_| 1));
    v1.measure(2, 10);
    v1.measure(5, 42);

    let snapshot = v1.export_measurement_cache();
    println!("exported_cache_len={}", snapshot.len());

    let mut v2 = Virtualizer::new(VirtualizerOptions::new(10, |_| 1));
    println!(
        "before import: size2={:?} size5={:?}",
        v2.item_size(2),
        v2.item_size(5)
    );

    v2.import_measurement_cache(snapshot);
    println!(
        "after import: cache_len={} size2={:?} size5={:?}",
        v2.measurement_cache_len(),
        v2.item_size(2),
        v2.item_size(5)
    );
}

pub fn import_measurement_cache( &mut self, entries: impl IntoIterator<Item = (K, u32)>, )

Replaces the cached measured sizes from an iterator (useful when restoring state).

Note: this rebuilds internal per-index sizes using the current key mapping.

Examples found in repository

examples/measurement_cache.rs (line 23)

fn main() {
    // Example: export and import measurement cache (key -> measured size).
    //
    // This is useful if you want to persist measurements across screens/sessions so that the
    // virtualizer can start with better estimates and avoid re-measuring everything.
    let mut v1 = Virtualizer::new(VirtualizerOptions::new(10, |_| 1));
    v1.measure(2, 10);
    v1.measure(5, 42);

    let snapshot = v1.export_measurement_cache();
    println!("exported_cache_len={}", snapshot.len());

    let mut v2 = Virtualizer::new(VirtualizerOptions::new(10, |_| 1));
    println!(
        "before import: size2={:?} size5={:?}",
        v2.item_size(2),
        v2.item_size(5)
    );

    v2.import_measurement_cache(snapshot);
    println!(
        "after import: cache_len={} size2={:?} size5={:?}",
        v2.measurement_cache_len(),
        v2.item_size(2),
        v2.item_size(5)
    );
}

pub fn measure(&mut self, index: usize, size: u32)

Marks an item as measured and updates its cached size.

This is aligned with TanStack Virtual’s “measure element” behavior: if the measured item is before the current scroll offset, the virtualizer may adjust scroll_offset to prevent a visible “jump”.

If you want to update measurements without any scroll adjustment, use measure_unadjusted.

Examples found in repository

examples/keyed_reorder.rs (line 7)

fn main() {
    // Example: measurements follow keys after reorder.
    let mut v = Virtualizer::new(VirtualizerOptions::new(2, |_| 1));
    v.measure(0, 10);
    println!(
        "before reorder: size0={:?} size1={:?}",
        v.item_size(0),
        v.item_size(1)
    );

    // Simulate data reorder by changing the key mapping.
    v.set_get_item_key(|i| if i == 0 { 1 } else { 0 });
    // Note: in real apps you usually keep `get_item_key` stable and call `sync_item_keys()` when
    // your underlying dataset is reordered while `count` stays the same.

    println!(
        "after reorder: size0={:?} size1={:?}",
        v.item_size(0),
        v.item_size(1)
    );
}

examples/measurement_cache.rs (line 10)

fn main() {
    // Example: export and import measurement cache (key -> measured size).
    //
    // This is useful if you want to persist measurements across screens/sessions so that the
    // virtualizer can start with better estimates and avoid re-measuring everything.
    let mut v1 = Virtualizer::new(VirtualizerOptions::new(10, |_| 1));
    v1.measure(2, 10);
    v1.measure(5, 42);

    let snapshot = v1.export_measurement_cache();
    println!("exported_cache_len={}", snapshot.len());

    let mut v2 = Virtualizer::new(VirtualizerOptions::new(10, |_| 1));
    println!(
        "before import: size2={:?} size5={:?}",
        v2.item_size(2),
        v2.item_size(5)
    );

    v2.import_measurement_cache(snapshot);
    println!(
        "after import: cache_len={} size2={:?} size5={:?}",
        v2.measurement_cache_len(),
        v2.item_size(2),
        v2.item_size(5)
    );
}

examples/dynamic_measurement.rs (line 26)

fn main() {
    // Example: dynamic measurement + scroll jump prevention.
    let mut v = Virtualizer::new(VirtualizerOptions::new(100, |_| 10));
    v.set_viewport_and_scroll_clamped(30, 200);

    println!(
        "before: off={} total={} range={:?}",
        v.scroll_offset(),
        v.total_size(),
        v.virtual_range()
    );

    // If an item before the viewport changes size, `resize_item` can adjust scroll_offset to
    // prevent visual jumps.
    let applied = v.resize_item(0, 30);
    println!(
        "resize_item(0): applied_delta={applied} off={} total={}",
        v.scroll_offset(),
        v.total_size()
    );

    // Measuring an item updates sizes and may adjust scroll (TanStack-aligned behavior).
    v.measure(1, 50);
    println!(
        "measure(1): off={} total={}",
        v.scroll_offset(),
        v.total_size()
    );

    // If you want to update measurements without changing scroll, use `measure_unadjusted`.
    v.measure_unadjusted(2, 30);

    // Scroll-to helpers still work with updated measurements.
    let to = v.scroll_to_index_offset(10, Align::Start);
    v.set_scroll_offset_clamped(to);
    println!(
        "set_scroll_offset_clamped(scroll_to_index_offset(10)): off={} range={:?}",
        v.scroll_offset(),
        v.virtual_range()
    );
}

pub fn measure_keyed(&mut self, index: usize, key: K, size: u32)

Same as Self::measure, but uses a precomputed key to avoid recomputing get_item_key.

pub fn measure_unadjusted(&mut self, index: usize, size: u32)

Marks an item as measured and updates its cached size without adjusting scroll_offset.

Examples found in repository

examples/dynamic_measurement.rs (line 34)

fn main() {
    // Example: dynamic measurement + scroll jump prevention.
    let mut v = Virtualizer::new(VirtualizerOptions::new(100, |_| 10));
    v.set_viewport_and_scroll_clamped(30, 200);

    println!(
        "before: off={} total={} range={:?}",
        v.scroll_offset(),
        v.total_size(),
        v.virtual_range()
    );

    // If an item before the viewport changes size, `resize_item` can adjust scroll_offset to
    // prevent visual jumps.
    let applied = v.resize_item(0, 30);
    println!(
        "resize_item(0): applied_delta={applied} off={} total={}",
        v.scroll_offset(),
        v.total_size()
    );

    // Measuring an item updates sizes and may adjust scroll (TanStack-aligned behavior).
    v.measure(1, 50);
    println!(
        "measure(1): off={} total={}",
        v.scroll_offset(),
        v.total_size()
    );

    // If you want to update measurements without changing scroll, use `measure_unadjusted`.
    v.measure_unadjusted(2, 30);

    // Scroll-to helpers still work with updated measurements.
    let to = v.scroll_to_index_offset(10, Align::Start);
    v.set_scroll_offset_clamped(to);
    println!(
        "set_scroll_offset_clamped(scroll_to_index_offset(10)): off={} range={:?}",
        v.scroll_offset(),
        v.virtual_range()
    );
}

pub fn measure_keyed_unadjusted(&mut self, index: usize, key: K, size: u32)

Same as Self::measure_unadjusted, but uses a precomputed key.

pub fn resize_item(&mut self, index: usize, size: u32) -> i64

Examples found in repository

examples/dynamic_measurement.rs (line 18)

fn main() {
    // Example: dynamic measurement + scroll jump prevention.
    let mut v = Virtualizer::new(VirtualizerOptions::new(100, |_| 10));
    v.set_viewport_and_scroll_clamped(30, 200);

    println!(
        "before: off={} total={} range={:?}",
        v.scroll_offset(),
        v.total_size(),
        v.virtual_range()
    );

    // If an item before the viewport changes size, `resize_item` can adjust scroll_offset to
    // prevent visual jumps.
    let applied = v.resize_item(0, 30);
    println!(
        "resize_item(0): applied_delta={applied} off={} total={}",
        v.scroll_offset(),
        v.total_size()
    );

    // Measuring an item updates sizes and may adjust scroll (TanStack-aligned behavior).
    v.measure(1, 50);
    println!(
        "measure(1): off={} total={}",
        v.scroll_offset(),
        v.total_size()
    );

    // If you want to update measurements without changing scroll, use `measure_unadjusted`.
    v.measure_unadjusted(2, 30);

    // Scroll-to helpers still work with updated measurements.
    let to = v.scroll_to_index_offset(10, Align::Start);
    v.set_scroll_offset_clamped(to);
    println!(
        "set_scroll_offset_clamped(scroll_to_index_offset(10)): off={} range={:?}",
        v.scroll_offset(),
        v.virtual_range()
    );
}

examples/adapter_sim.rs (line 60)

fn main() {
    // Simulate a framework adapter that owns the scroll state.
    let saved_scroll = Arc::new(AtomicU64::new(120));

    let opts = VirtualizerOptions::new(1000, |_| 1)
        .with_initial_rect(Some(Rect {
            main: 10,
            cross: 80,
        }))
        .with_initial_offset_provider({
            let saved_scroll = Arc::clone(&saved_scroll);
            move || saved_scroll.load(Ordering::Relaxed)
        })
        .with_scroll_margin(5)
        .with_range_extractor(Some(|r: Range, emit: &mut dyn FnMut(usize)| {
            // Pin a "sticky header" at index 0, regardless of scroll position.
            let mut e = virtualizer::IndexEmitter::new(r, emit);
            e.emit_pinned(0);
            e.emit_visible();
        }));

    let mut v = Virtualizer::new(opts);

    // First render: scroll offset comes from the provider.
    println!("initial scroll_offset={}", v.scroll_offset());
    println!("initial scroll_rect={:?}", v.scroll_rect());

    // Adapter updates rect + scroll offset on events.
    v.apply_scroll_frame(
        Rect {
            main: 12,
            cross: 80,
        },
        200,
        0,
    );

    let mut items = Vec::new();
    v.for_each_virtual_item_keyed(|it| items.push(it));
    println!(
        "is_scrolling={}, visible_range={:?}, items_len={}",
        v.is_scrolling(),
        v.visible_range(),
        items.len()
    );
    println!("first_item={:?}", items.first());

    // Demonstrate scroll-to helpers.
    let target = v.scroll_to_index_offset(500, Align::Start);
    v.set_scroll_offset_clamped(target);
    println!("after scroll_to_index: scroll_offset={}", v.scroll_offset());

    // Demonstrate dynamic measurement + scroll adjustment.
    let applied = v.resize_item(0, 20);
    println!("resize_item applied_scroll_adjustment={applied}");

    // Simulate reorder: change key mapping. This automatically rebuilds per-index sizes from the
    // key-based measurement cache. In real apps, you usually keep `get_item_key` stable and call
    // `sync_item_keys()` when your dataset is reordered while `count` stays the same.
    v.set_get_item_key(|i| if i == 0 { 1 } else { i as u64 });

    // Debounced scrolling reset without relying on a native scrollend event.
    v.update_scrolling(200);
    println!("after update_scrolling: is_scrolling={}", v.is_scrolling());

    // Toggle enabled to disable all queries.
    v.set_enabled(false);
    let mut disabled_len = 0usize;
    v.for_each_virtual_item(|_| disabled_len += 1);
    println!(
        "disabled total_size={}, items_len={}",
        v.total_size(),
        disabled_len
    );
}

pub fn resize_item_keyed(&mut self, index: usize, key: K, size: u32) -> i64

pub fn measure_many( &mut self, measurements: impl IntoIterator<Item = (usize, u32)>, )

Measures multiple items in one pass.

Like Self::measure, this may adjust scroll_offset to prevent jumps.

pub fn measure_many_unadjusted( &mut self, measurements: impl IntoIterator<Item = (usize, u32)>, )

Measures multiple items without adjusting scroll_offset.

pub fn resize_item_many( &mut self, measurements: impl IntoIterator<Item = (usize, u32)>, ) -> i64

pub fn is_measured(&self, index: usize) -> bool

pub fn total_size(&self) -> u64

Examples found in repository

examples/basic.rs (line 10)

fn main() {
    let mut v = Virtualizer::new(VirtualizerOptions::new(1_000_000, |_| 1));
    v.set_viewport_and_scroll(10, 123_456);

    let mut items = Vec::new();
    v.for_each_virtual_item(|it| items.push(it));
    println!("total_size={}", v.total_size());
    println!("visible_range={:?}", v.virtual_range());
    println!("first_visible={:?}", items.first());

    let off = v.scroll_to_index_offset(999_999, Align::End);
    v.set_scroll_offset_clamped(off);
    println!("after scroll_to_index: offset={}", v.scroll_offset());
}

examples/dynamic_measurement.rs (line 12)

fn main() {
    // Example: dynamic measurement + scroll jump prevention.
    let mut v = Virtualizer::new(VirtualizerOptions::new(100, |_| 10));
    v.set_viewport_and_scroll_clamped(30, 200);

    println!(
        "before: off={} total={} range={:?}",
        v.scroll_offset(),
        v.total_size(),
        v.virtual_range()
    );

    // If an item before the viewport changes size, `resize_item` can adjust scroll_offset to
    // prevent visual jumps.
    let applied = v.resize_item(0, 30);
    println!(
        "resize_item(0): applied_delta={applied} off={} total={}",
        v.scroll_offset(),
        v.total_size()
    );

    // Measuring an item updates sizes and may adjust scroll (TanStack-aligned behavior).
    v.measure(1, 50);
    println!(
        "measure(1): off={} total={}",
        v.scroll_offset(),
        v.total_size()
    );

    // If you want to update measurements without changing scroll, use `measure_unadjusted`.
    v.measure_unadjusted(2, 30);

    // Scroll-to helpers still work with updated measurements.
    let to = v.scroll_to_index_offset(10, Align::Start);
    v.set_scroll_offset_clamped(to);
    println!(
        "set_scroll_offset_clamped(scroll_to_index_offset(10)): off={} range={:?}",
        v.scroll_offset(),
        v.virtual_range()
    );
}

examples/adapter_sim.rs (line 78)

fn main() {
    // Simulate a framework adapter that owns the scroll state.
    let saved_scroll = Arc::new(AtomicU64::new(120));

    let opts = VirtualizerOptions::new(1000, |_| 1)
        .with_initial_rect(Some(Rect {
            main: 10,
            cross: 80,
        }))
        .with_initial_offset_provider({
            let saved_scroll = Arc::clone(&saved_scroll);
            move || saved_scroll.load(Ordering::Relaxed)
        })
        .with_scroll_margin(5)
        .with_range_extractor(Some(|r: Range, emit: &mut dyn FnMut(usize)| {
            // Pin a "sticky header" at index 0, regardless of scroll position.
            let mut e = virtualizer::IndexEmitter::new(r, emit);
            e.emit_pinned(0);
            e.emit_visible();
        }));

    let mut v = Virtualizer::new(opts);

    // First render: scroll offset comes from the provider.
    println!("initial scroll_offset={}", v.scroll_offset());
    println!("initial scroll_rect={:?}", v.scroll_rect());

    // Adapter updates rect + scroll offset on events.
    v.apply_scroll_frame(
        Rect {
            main: 12,
            cross: 80,
        },
        200,
        0,
    );

    let mut items = Vec::new();
    v.for_each_virtual_item_keyed(|it| items.push(it));
    println!(
        "is_scrolling={}, visible_range={:?}, items_len={}",
        v.is_scrolling(),
        v.visible_range(),
        items.len()
    );
    println!("first_item={:?}", items.first());

    // Demonstrate scroll-to helpers.
    let target = v.scroll_to_index_offset(500, Align::Start);
    v.set_scroll_offset_clamped(target);
    println!("after scroll_to_index: scroll_offset={}", v.scroll_offset());

    // Demonstrate dynamic measurement + scroll adjustment.
    let applied = v.resize_item(0, 20);
    println!("resize_item applied_scroll_adjustment={applied}");

    // Simulate reorder: change key mapping. This automatically rebuilds per-index sizes from the
    // key-based measurement cache. In real apps, you usually keep `get_item_key` stable and call
    // `sync_item_keys()` when your dataset is reordered while `count` stays the same.
    v.set_get_item_key(|i| if i == 0 { 1 } else { i as u64 });

    // Debounced scrolling reset without relying on a native scrollend event.
    v.update_scrolling(200);
    println!("after update_scrolling: is_scrolling={}", v.is_scrolling());

    // Toggle enabled to disable all queries.
    v.set_enabled(false);
    let mut disabled_len = 0usize;
    v.for_each_virtual_item(|_| disabled_len += 1);
    println!(
        "disabled total_size={}, items_len={}",
        v.total_size(),
        disabled_len
    );
}

pub fn key_for(&self, index: usize) -> K

pub fn virtual_range(&self) -> VirtualRange

Examples found in repository

examples/basic.rs (line 11)

fn main() {
    let mut v = Virtualizer::new(VirtualizerOptions::new(1_000_000, |_| 1));
    v.set_viewport_and_scroll(10, 123_456);

    let mut items = Vec::new();
    v.for_each_virtual_item(|it| items.push(it));
    println!("total_size={}", v.total_size());
    println!("visible_range={:?}", v.virtual_range());
    println!("first_visible={:?}", items.first());

    let off = v.scroll_to_index_offset(999_999, Align::End);
    v.set_scroll_offset_clamped(off);
    println!("after scroll_to_index: offset={}", v.scroll_offset());
}

examples/dynamic_measurement.rs (line 13)

fn main() {
    // Example: dynamic measurement + scroll jump prevention.
    let mut v = Virtualizer::new(VirtualizerOptions::new(100, |_| 10));
    v.set_viewport_and_scroll_clamped(30, 200);

    println!(
        "before: off={} total={} range={:?}",
        v.scroll_offset(),
        v.total_size(),
        v.virtual_range()
    );

    // If an item before the viewport changes size, `resize_item` can adjust scroll_offset to
    // prevent visual jumps.
    let applied = v.resize_item(0, 30);
    println!(
        "resize_item(0): applied_delta={applied} off={} total={}",
        v.scroll_offset(),
        v.total_size()
    );

    // Measuring an item updates sizes and may adjust scroll (TanStack-aligned behavior).
    v.measure(1, 50);
    println!(
        "measure(1): off={} total={}",
        v.scroll_offset(),
        v.total_size()
    );

    // If you want to update measurements without changing scroll, use `measure_unadjusted`.
    v.measure_unadjusted(2, 30);

    // Scroll-to helpers still work with updated measurements.
    let to = v.scroll_to_index_offset(10, Align::Start);
    v.set_scroll_offset_clamped(to);
    println!(
        "set_scroll_offset_clamped(scroll_to_index_offset(10)): off={} range={:?}",
        v.scroll_offset(),
        v.virtual_range()
    );
}

examples/tween_scroll.rs (line 103)

fn main() {
    // Simulate an adapter that drives scroll_offset with a tween.
    let mut v = Virtualizer::new(VirtualizerOptions::new(10_000, |_| 1));
    v.set_viewport_and_scroll_clamped(20, 0);

    let to = v.scroll_to_index_offset(2_000, Align::Center);
    let mut tween = Tween::new(v.scroll_offset(), to, 0, 240);

    let mut now_ms = 0u64;
    let mut frame = 0u64;

    loop {
        // Simulate a 60fps "tick".
        now_ms = now_ms.saturating_add(16);
        frame += 1;

        // Adapter samples tween and writes it into the virtualizer.
        let off = tween.sample(now_ms);
        v.apply_scroll_offset_event_clamped(off, now_ms);

        // Render: a UI would iterate items and draw them.
        let mut first: Option<usize> = None;
        let mut last: Option<usize> = None;
        v.for_each_virtual_item(|it| {
            first.get_or_insert(it.index);
            last = Some(it.index);
        });

        if frame.is_multiple_of(5) {
            println!(
                "t={now_ms}ms off={} visible={:?} first={:?} last={:?}",
                v.scroll_offset(),
                v.visible_range(),
                first,
                last
            );
        }

        // Simulate user input interrupting the animation:
        // at ~120ms, retarget to a new index.
        if (120..120 + 16).contains(&now_ms) {
            let new_to = v.scroll_to_index_offset(7_500, Align::Start);
            tween.retarget(now_ms, new_to, 300);
        }

        if tween.is_done(now_ms) {
            break;
        }
    }

    // Mark scroll as finished for adapters that use this state.
    v.set_is_scrolling(false);

    println!(
        "done: off={} range={:?}",
        v.scroll_offset(),
        v.virtual_range()
    );
}

examples/pinned_headers.rs (line 49)

fn main() {
    // Example: pinned/sticky "headers" at fixed indexes.
    let mut opts = VirtualizerOptions::new(1_000, |_| 1);
    opts.overscan = 2;

    let pinned: Arc<[usize]> = Arc::from([0usize, 10, 20, 30, 40, 999]);
    opts.range_extractor = Some(Arc::new({
        let pinned = Arc::clone(&pinned);
        move |r: Range, emit: &mut dyn FnMut(usize)| {
            let mut e = IndexEmitter::new(r, emit);
            // IMPORTANT: indexes must be emitted in ascending order.
            //
            // We want pinned rows both before and after the overscanned range. To keep the output
            // sorted, emit:
            // 1) pinned indexes before the overscanned range
            // 2) the overscanned contiguous range
            // 3) pinned indexes after the overscanned range
            let overscanned_start = r.start_index.saturating_sub(r.overscan);
            let overscanned_end = r.end_index.saturating_add(r.overscan).min(r.count);

            for &idx in pinned.iter() {
                if idx < overscanned_start {
                    e.emit_pinned(idx);
                }
            }

            e.emit_overscanned();

            for &idx in pinned.iter() {
                if idx >= overscanned_end {
                    e.emit_pinned(idx);
                }
            }
        }
    }));

    let mut v = Virtualizer::new(opts);
    v.set_viewport_and_scroll_clamped(10, 500);

    let mut collected = Vec::new();
    v.for_each_virtual_index(|i| collected.push(i));

    println!("visible_range={:?}", v.visible_range());
    println!("virtual_range={:?}", v.virtual_range());
    println!(
        "indexes_len={} first_20={:?}",
        collected.len(),
        &collected[..20.min(collected.len())]
    );

    // A real UI would typically iterate items:
    let mut headers = 0usize;
    v.for_each_virtual_item(|it| {
        if pinned.binary_search(&it.index).is_ok() {
            headers += 1;
        }
    });
    println!("pinned_headers_in_output={headers}");
}

pub fn virtual_range_for( &self, scroll_offset: u64, viewport_size: u32, ) -> VirtualRange

pub fn visible_range(&self) -> VirtualRange

Examples found in repository

examples/tween_scroll.rs (line 79)

fn main() {
    // Simulate an adapter that drives scroll_offset with a tween.
    let mut v = Virtualizer::new(VirtualizerOptions::new(10_000, |_| 1));
    v.set_viewport_and_scroll_clamped(20, 0);

    let to = v.scroll_to_index_offset(2_000, Align::Center);
    let mut tween = Tween::new(v.scroll_offset(), to, 0, 240);

    let mut now_ms = 0u64;
    let mut frame = 0u64;

    loop {
        // Simulate a 60fps "tick".
        now_ms = now_ms.saturating_add(16);
        frame += 1;

        // Adapter samples tween and writes it into the virtualizer.
        let off = tween.sample(now_ms);
        v.apply_scroll_offset_event_clamped(off, now_ms);

        // Render: a UI would iterate items and draw them.
        let mut first: Option<usize> = None;
        let mut last: Option<usize> = None;
        v.for_each_virtual_item(|it| {
            first.get_or_insert(it.index);
            last = Some(it.index);
        });

        if frame.is_multiple_of(5) {
            println!(
                "t={now_ms}ms off={} visible={:?} first={:?} last={:?}",
                v.scroll_offset(),
                v.visible_range(),
                first,
                last
            );
        }

        // Simulate user input interrupting the animation:
        // at ~120ms, retarget to a new index.
        if (120..120 + 16).contains(&now_ms) {
            let new_to = v.scroll_to_index_offset(7_500, Align::Start);
            tween.retarget(now_ms, new_to, 300);
        }

        if tween.is_done(now_ms) {
            break;
        }
    }

    // Mark scroll as finished for adapters that use this state.
    v.set_is_scrolling(false);

    println!(
        "done: off={} range={:?}",
        v.scroll_offset(),
        v.virtual_range()
    );
}

examples/pinned_headers.rs (line 48)

fn main() {
    // Example: pinned/sticky "headers" at fixed indexes.
    let mut opts = VirtualizerOptions::new(1_000, |_| 1);
    opts.overscan = 2;

    let pinned: Arc<[usize]> = Arc::from([0usize, 10, 20, 30, 40, 999]);
    opts.range_extractor = Some(Arc::new({
        let pinned = Arc::clone(&pinned);
        move |r: Range, emit: &mut dyn FnMut(usize)| {
            let mut e = IndexEmitter::new(r, emit);
            // IMPORTANT: indexes must be emitted in ascending order.
            //
            // We want pinned rows both before and after the overscanned range. To keep the output
            // sorted, emit:
            // 1) pinned indexes before the overscanned range
            // 2) the overscanned contiguous range
            // 3) pinned indexes after the overscanned range
            let overscanned_start = r.start_index.saturating_sub(r.overscan);
            let overscanned_end = r.end_index.saturating_add(r.overscan).min(r.count);

            for &idx in pinned.iter() {
                if idx < overscanned_start {
                    e.emit_pinned(idx);
                }
            }

            e.emit_overscanned();

            for &idx in pinned.iter() {
                if idx >= overscanned_end {
                    e.emit_pinned(idx);
                }
            }
        }
    }));

    let mut v = Virtualizer::new(opts);
    v.set_viewport_and_scroll_clamped(10, 500);

    let mut collected = Vec::new();
    v.for_each_virtual_index(|i| collected.push(i));

    println!("visible_range={:?}", v.visible_range());
    println!("virtual_range={:?}", v.virtual_range());
    println!(
        "indexes_len={} first_20={:?}",
        collected.len(),
        &collected[..20.min(collected.len())]
    );

    // A real UI would typically iterate items:
    let mut headers = 0usize;
    v.for_each_virtual_item(|it| {
        if pinned.binary_search(&it.index).is_ok() {
            headers += 1;
        }
    });
    println!("pinned_headers_in_output={headers}");
}

examples/adapter_sim.rs (line 49)

fn main() {
    // Simulate a framework adapter that owns the scroll state.
    let saved_scroll = Arc::new(AtomicU64::new(120));

    let opts = VirtualizerOptions::new(1000, |_| 1)
        .with_initial_rect(Some(Rect {
            main: 10,
            cross: 80,
        }))
        .with_initial_offset_provider({
            let saved_scroll = Arc::clone(&saved_scroll);
            move || saved_scroll.load(Ordering::Relaxed)
        })
        .with_scroll_margin(5)
        .with_range_extractor(Some(|r: Range, emit: &mut dyn FnMut(usize)| {
            // Pin a "sticky header" at index 0, regardless of scroll position.
            let mut e = virtualizer::IndexEmitter::new(r, emit);
            e.emit_pinned(0);
            e.emit_visible();
        }));

    let mut v = Virtualizer::new(opts);

    // First render: scroll offset comes from the provider.
    println!("initial scroll_offset={}", v.scroll_offset());
    println!("initial scroll_rect={:?}", v.scroll_rect());

    // Adapter updates rect + scroll offset on events.
    v.apply_scroll_frame(
        Rect {
            main: 12,
            cross: 80,
        },
        200,
        0,
    );

    let mut items = Vec::new();
    v.for_each_virtual_item_keyed(|it| items.push(it));
    println!(
        "is_scrolling={}, visible_range={:?}, items_len={}",
        v.is_scrolling(),
        v.visible_range(),
        items.len()
    );
    println!("first_item={:?}", items.first());

    // Demonstrate scroll-to helpers.
    let target = v.scroll_to_index_offset(500, Align::Start);
    v.set_scroll_offset_clamped(target);
    println!("after scroll_to_index: scroll_offset={}", v.scroll_offset());

    // Demonstrate dynamic measurement + scroll adjustment.
    let applied = v.resize_item(0, 20);
    println!("resize_item applied_scroll_adjustment={applied}");

    // Simulate reorder: change key mapping. This automatically rebuilds per-index sizes from the
    // key-based measurement cache. In real apps, you usually keep `get_item_key` stable and call
    // `sync_item_keys()` when your dataset is reordered while `count` stays the same.
    v.set_get_item_key(|i| if i == 0 { 1 } else { i as u64 });

    // Debounced scrolling reset without relying on a native scrollend event.
    v.update_scrolling(200);
    println!("after update_scrolling: is_scrolling={}", v.is_scrolling());

    // Toggle enabled to disable all queries.
    v.set_enabled(false);
    let mut disabled_len = 0usize;
    v.for_each_virtual_item(|_| disabled_len += 1);
    println!(
        "disabled total_size={}, items_len={}",
        v.total_size(),
        disabled_len
    );
}

pub fn visible_range_for( &self, scroll_offset: u64, viewport_size: u32, ) -> VirtualRange

pub fn for_each_virtual_index(&self, f: impl FnMut(usize))

Examples found in repository

examples/pinned_headers.rs (line 46)

fn main() {
    // Example: pinned/sticky "headers" at fixed indexes.
    let mut opts = VirtualizerOptions::new(1_000, |_| 1);
    opts.overscan = 2;

    let pinned: Arc<[usize]> = Arc::from([0usize, 10, 20, 30, 40, 999]);
    opts.range_extractor = Some(Arc::new({
        let pinned = Arc::clone(&pinned);
        move |r: Range, emit: &mut dyn FnMut(usize)| {
            let mut e = IndexEmitter::new(r, emit);
            // IMPORTANT: indexes must be emitted in ascending order.
            //
            // We want pinned rows both before and after the overscanned range. To keep the output
            // sorted, emit:
            // 1) pinned indexes before the overscanned range
            // 2) the overscanned contiguous range
            // 3) pinned indexes after the overscanned range
            let overscanned_start = r.start_index.saturating_sub(r.overscan);
            let overscanned_end = r.end_index.saturating_add(r.overscan).min(r.count);

            for &idx in pinned.iter() {
                if idx < overscanned_start {
                    e.emit_pinned(idx);
                }
            }

            e.emit_overscanned();

            for &idx in pinned.iter() {
                if idx >= overscanned_end {
                    e.emit_pinned(idx);
                }
            }
        }
    }));

    let mut v = Virtualizer::new(opts);
    v.set_viewport_and_scroll_clamped(10, 500);

    let mut collected = Vec::new();
    v.for_each_virtual_index(|i| collected.push(i));

    println!("visible_range={:?}", v.visible_range());
    println!("virtual_range={:?}", v.virtual_range());
    println!(
        "indexes_len={} first_20={:?}",
        collected.len(),
        &collected[..20.min(collected.len())]
    );

    // A real UI would typically iterate items:
    let mut headers = 0usize;
    v.for_each_virtual_item(|it| {
        if pinned.binary_search(&it.index).is_ok() {
            headers += 1;
        }
    });
    println!("pinned_headers_in_output={headers}");
}

pub fn for_each_virtual_index_for( &self, scroll_offset: u64, viewport_size: u32, f: impl FnMut(usize), )

pub fn for_each_virtual_item(&self, f: impl FnMut(VirtualItem))

Examples found in repository

examples/basic.rs (line 9)

fn main() {
    let mut v = Virtualizer::new(VirtualizerOptions::new(1_000_000, |_| 1));
    v.set_viewport_and_scroll(10, 123_456);

    let mut items = Vec::new();
    v.for_each_virtual_item(|it| items.push(it));
    println!("total_size={}", v.total_size());
    println!("visible_range={:?}", v.virtual_range());
    println!("first_visible={:?}", items.first());

    let off = v.scroll_to_index_offset(999_999, Align::End);
    v.set_scroll_offset_clamped(off);
    println!("after scroll_to_index: offset={}", v.scroll_offset());
}

examples/tween_scroll.rs (lines 70-73)

fn main() {
    // Simulate an adapter that drives scroll_offset with a tween.
    let mut v = Virtualizer::new(VirtualizerOptions::new(10_000, |_| 1));
    v.set_viewport_and_scroll_clamped(20, 0);

    let to = v.scroll_to_index_offset(2_000, Align::Center);
    let mut tween = Tween::new(v.scroll_offset(), to, 0, 240);

    let mut now_ms = 0u64;
    let mut frame = 0u64;

    loop {
        // Simulate a 60fps "tick".
        now_ms = now_ms.saturating_add(16);
        frame += 1;

        // Adapter samples tween and writes it into the virtualizer.
        let off = tween.sample(now_ms);
        v.apply_scroll_offset_event_clamped(off, now_ms);

        // Render: a UI would iterate items and draw them.
        let mut first: Option<usize> = None;
        let mut last: Option<usize> = None;
        v.for_each_virtual_item(|it| {
            first.get_or_insert(it.index);
            last = Some(it.index);
        });

        if frame.is_multiple_of(5) {
            println!(
                "t={now_ms}ms off={} visible={:?} first={:?} last={:?}",
                v.scroll_offset(),
                v.visible_range(),
                first,
                last
            );
        }

        // Simulate user input interrupting the animation:
        // at ~120ms, retarget to a new index.
        if (120..120 + 16).contains(&now_ms) {
            let new_to = v.scroll_to_index_offset(7_500, Align::Start);
            tween.retarget(now_ms, new_to, 300);
        }

        if tween.is_done(now_ms) {
            break;
        }
    }

    // Mark scroll as finished for adapters that use this state.
    v.set_is_scrolling(false);

    println!(
        "done: off={} range={:?}",
        v.scroll_offset(),
        v.virtual_range()
    );
}

examples/pinned_headers.rs (lines 58-62)

fn main() {
    // Example: pinned/sticky "headers" at fixed indexes.
    let mut opts = VirtualizerOptions::new(1_000, |_| 1);
    opts.overscan = 2;

    let pinned: Arc<[usize]> = Arc::from([0usize, 10, 20, 30, 40, 999]);
    opts.range_extractor = Some(Arc::new({
        let pinned = Arc::clone(&pinned);
        move |r: Range, emit: &mut dyn FnMut(usize)| {
            let mut e = IndexEmitter::new(r, emit);
            // IMPORTANT: indexes must be emitted in ascending order.
            //
            // We want pinned rows both before and after the overscanned range. To keep the output
            // sorted, emit:
            // 1) pinned indexes before the overscanned range
            // 2) the overscanned contiguous range
            // 3) pinned indexes after the overscanned range
            let overscanned_start = r.start_index.saturating_sub(r.overscan);
            let overscanned_end = r.end_index.saturating_add(r.overscan).min(r.count);

            for &idx in pinned.iter() {
                if idx < overscanned_start {
                    e.emit_pinned(idx);
                }
            }

            e.emit_overscanned();

            for &idx in pinned.iter() {
                if idx >= overscanned_end {
                    e.emit_pinned(idx);
                }
            }
        }
    }));

    let mut v = Virtualizer::new(opts);
    v.set_viewport_and_scroll_clamped(10, 500);

    let mut collected = Vec::new();
    v.for_each_virtual_index(|i| collected.push(i));

    println!("visible_range={:?}", v.visible_range());
    println!("virtual_range={:?}", v.virtual_range());
    println!(
        "indexes_len={} first_20={:?}",
        collected.len(),
        &collected[..20.min(collected.len())]
    );

    // A real UI would typically iterate items:
    let mut headers = 0usize;
    v.for_each_virtual_item(|it| {
        if pinned.binary_search(&it.index).is_ok() {
            headers += 1;
        }
    });
    println!("pinned_headers_in_output={headers}");
}

examples/adapter_sim.rs (line 75)

fn main() {
    // Simulate a framework adapter that owns the scroll state.
    let saved_scroll = Arc::new(AtomicU64::new(120));

    let opts = VirtualizerOptions::new(1000, |_| 1)
        .with_initial_rect(Some(Rect {
            main: 10,
            cross: 80,
        }))
        .with_initial_offset_provider({
            let saved_scroll = Arc::clone(&saved_scroll);
            move || saved_scroll.load(Ordering::Relaxed)
        })
        .with_scroll_margin(5)
        .with_range_extractor(Some(|r: Range, emit: &mut dyn FnMut(usize)| {
            // Pin a "sticky header" at index 0, regardless of scroll position.
            let mut e = virtualizer::IndexEmitter::new(r, emit);
            e.emit_pinned(0);
            e.emit_visible();
        }));

    let mut v = Virtualizer::new(opts);

    // First render: scroll offset comes from the provider.
    println!("initial scroll_offset={}", v.scroll_offset());
    println!("initial scroll_rect={:?}", v.scroll_rect());

    // Adapter updates rect + scroll offset on events.
    v.apply_scroll_frame(
        Rect {
            main: 12,
            cross: 80,
        },
        200,
        0,
    );

    let mut items = Vec::new();
    v.for_each_virtual_item_keyed(|it| items.push(it));
    println!(
        "is_scrolling={}, visible_range={:?}, items_len={}",
        v.is_scrolling(),
        v.visible_range(),
        items.len()
    );
    println!("first_item={:?}", items.first());

    // Demonstrate scroll-to helpers.
    let target = v.scroll_to_index_offset(500, Align::Start);
    v.set_scroll_offset_clamped(target);
    println!("after scroll_to_index: scroll_offset={}", v.scroll_offset());

    // Demonstrate dynamic measurement + scroll adjustment.
    let applied = v.resize_item(0, 20);
    println!("resize_item applied_scroll_adjustment={applied}");

    // Simulate reorder: change key mapping. This automatically rebuilds per-index sizes from the
    // key-based measurement cache. In real apps, you usually keep `get_item_key` stable and call
    // `sync_item_keys()` when your dataset is reordered while `count` stays the same.
    v.set_get_item_key(|i| if i == 0 { 1 } else { i as u64 });

    // Debounced scrolling reset without relying on a native scrollend event.
    v.update_scrolling(200);
    println!("after update_scrolling: is_scrolling={}", v.is_scrolling());

    // Toggle enabled to disable all queries.
    v.set_enabled(false);
    let mut disabled_len = 0usize;
    v.for_each_virtual_item(|_| disabled_len += 1);
    println!(
        "disabled total_size={}, items_len={}",
        v.total_size(),
        disabled_len
    );
}

pub fn for_each_virtual_item_for( &self, scroll_offset: u64, viewport_size: u32, f: impl FnMut(VirtualItem), )

pub fn for_each_virtual_item_keyed(&self, f: impl FnMut(VirtualItemKeyed<K>))

Examples found in repository

examples/adapter_sim.rs (line 45)

fn main() {
    // Simulate a framework adapter that owns the scroll state.
    let saved_scroll = Arc::new(AtomicU64::new(120));

    let opts = VirtualizerOptions::new(1000, |_| 1)
        .with_initial_rect(Some(Rect {
            main: 10,
            cross: 80,
        }))
        .with_initial_offset_provider({
            let saved_scroll = Arc::clone(&saved_scroll);
            move || saved_scroll.load(Ordering::Relaxed)
        })
        .with_scroll_margin(5)
        .with_range_extractor(Some(|r: Range, emit: &mut dyn FnMut(usize)| {
            // Pin a "sticky header" at index 0, regardless of scroll position.
            let mut e = virtualizer::IndexEmitter::new(r, emit);
            e.emit_pinned(0);
            e.emit_visible();
        }));

    let mut v = Virtualizer::new(opts);

    // First render: scroll offset comes from the provider.
    println!("initial scroll_offset={}", v.scroll_offset());
    println!("initial scroll_rect={:?}", v.scroll_rect());

    // Adapter updates rect + scroll offset on events.
    v.apply_scroll_frame(
        Rect {
            main: 12,
            cross: 80,
        },
        200,
        0,
    );

    let mut items = Vec::new();
    v.for_each_virtual_item_keyed(|it| items.push(it));
    println!(
        "is_scrolling={}, visible_range={:?}, items_len={}",
        v.is_scrolling(),
        v.visible_range(),
        items.len()
    );
    println!("first_item={:?}", items.first());

    // Demonstrate scroll-to helpers.
    let target = v.scroll_to_index_offset(500, Align::Start);
    v.set_scroll_offset_clamped(target);
    println!("after scroll_to_index: scroll_offset={}", v.scroll_offset());

    // Demonstrate dynamic measurement + scroll adjustment.
    let applied = v.resize_item(0, 20);
    println!("resize_item applied_scroll_adjustment={applied}");

    // Simulate reorder: change key mapping. This automatically rebuilds per-index sizes from the
    // key-based measurement cache. In real apps, you usually keep `get_item_key` stable and call
    // `sync_item_keys()` when your dataset is reordered while `count` stays the same.
    v.set_get_item_key(|i| if i == 0 { 1 } else { i as u64 });

    // Debounced scrolling reset without relying on a native scrollend event.
    v.update_scrolling(200);
    println!("after update_scrolling: is_scrolling={}", v.is_scrolling());

    // Toggle enabled to disable all queries.
    v.set_enabled(false);
    let mut disabled_len = 0usize;
    v.for_each_virtual_item(|_| disabled_len += 1);
    println!(
        "disabled total_size={}, items_len={}",
        v.total_size(),
        disabled_len
    );
}

pub fn for_each_virtual_item_keyed_for( &self, scroll_offset: u64, viewport_size: u32, f: impl FnMut(VirtualItemKeyed<K>), )

pub fn scroll_to_index(&mut self, index: usize, align: Align) -> u64

Programmatically scrolls to an index (no animation).

This sets the internal scroll_offset to the computed (clamped) target and triggers on_change. It does not mark the virtualizer as “scrolling”.

If you want “user scrolling” semantics (e.g. to drive is_scrolling debouncing), call apply_scroll_offset_event_clamped(scroll_to_index_offset(...), now_ms) instead.

Returns the applied (clamped) offset.

pub fn scroll_to_index_offset(&self, index: usize, align: Align) -> u64

Examples found in repository

examples/basic.rs (line 14)

fn main() {
    let mut v = Virtualizer::new(VirtualizerOptions::new(1_000_000, |_| 1));
    v.set_viewport_and_scroll(10, 123_456);

    let mut items = Vec::new();
    v.for_each_virtual_item(|it| items.push(it));
    println!("total_size={}", v.total_size());
    println!("visible_range={:?}", v.virtual_range());
    println!("first_visible={:?}", items.first());

    let off = v.scroll_to_index_offset(999_999, Align::End);
    v.set_scroll_offset_clamped(off);
    println!("after scroll_to_index: offset={}", v.scroll_offset());
}

examples/dynamic_measurement.rs (line 37)

fn main() {
    // Example: dynamic measurement + scroll jump prevention.
    let mut v = Virtualizer::new(VirtualizerOptions::new(100, |_| 10));
    v.set_viewport_and_scroll_clamped(30, 200);

    println!(
        "before: off={} total={} range={:?}",
        v.scroll_offset(),
        v.total_size(),
        v.virtual_range()
    );

    // If an item before the viewport changes size, `resize_item` can adjust scroll_offset to
    // prevent visual jumps.
    let applied = v.resize_item(0, 30);
    println!(
        "resize_item(0): applied_delta={applied} off={} total={}",
        v.scroll_offset(),
        v.total_size()
    );

    // Measuring an item updates sizes and may adjust scroll (TanStack-aligned behavior).
    v.measure(1, 50);
    println!(
        "measure(1): off={} total={}",
        v.scroll_offset(),
        v.total_size()
    );

    // If you want to update measurements without changing scroll, use `measure_unadjusted`.
    v.measure_unadjusted(2, 30);

    // Scroll-to helpers still work with updated measurements.
    let to = v.scroll_to_index_offset(10, Align::Start);
    v.set_scroll_offset_clamped(to);
    println!(
        "set_scroll_offset_clamped(scroll_to_index_offset(10)): off={} range={:?}",
        v.scroll_offset(),
        v.virtual_range()
    );
}

examples/tween_scroll.rs (line 52)

fn main() {
    // Simulate an adapter that drives scroll_offset with a tween.
    let mut v = Virtualizer::new(VirtualizerOptions::new(10_000, |_| 1));
    v.set_viewport_and_scroll_clamped(20, 0);

    let to = v.scroll_to_index_offset(2_000, Align::Center);
    let mut tween = Tween::new(v.scroll_offset(), to, 0, 240);

    let mut now_ms = 0u64;
    let mut frame = 0u64;

    loop {
        // Simulate a 60fps "tick".
        now_ms = now_ms.saturating_add(16);
        frame += 1;

        // Adapter samples tween and writes it into the virtualizer.
        let off = tween.sample(now_ms);
        v.apply_scroll_offset_event_clamped(off, now_ms);

        // Render: a UI would iterate items and draw them.
        let mut first: Option<usize> = None;
        let mut last: Option<usize> = None;
        v.for_each_virtual_item(|it| {
            first.get_or_insert(it.index);
            last = Some(it.index);
        });

        if frame.is_multiple_of(5) {
            println!(
                "t={now_ms}ms off={} visible={:?} first={:?} last={:?}",
                v.scroll_offset(),
                v.visible_range(),
                first,
                last
            );
        }

        // Simulate user input interrupting the animation:
        // at ~120ms, retarget to a new index.
        if (120..120 + 16).contains(&now_ms) {
            let new_to = v.scroll_to_index_offset(7_500, Align::Start);
            tween.retarget(now_ms, new_to, 300);
        }

        if tween.is_done(now_ms) {
            break;
        }
    }

    // Mark scroll as finished for adapters that use this state.
    v.set_is_scrolling(false);

    println!(
        "done: off={} range={:?}",
        v.scroll_offset(),
        v.virtual_range()
    );
}

examples/adapter_sim.rs (line 55)

fn main() {
    // Simulate a framework adapter that owns the scroll state.
    let saved_scroll = Arc::new(AtomicU64::new(120));

    let opts = VirtualizerOptions::new(1000, |_| 1)
        .with_initial_rect(Some(Rect {
            main: 10,
            cross: 80,
        }))
        .with_initial_offset_provider({
            let saved_scroll = Arc::clone(&saved_scroll);
            move || saved_scroll.load(Ordering::Relaxed)
        })
        .with_scroll_margin(5)
        .with_range_extractor(Some(|r: Range, emit: &mut dyn FnMut(usize)| {
            // Pin a "sticky header" at index 0, regardless of scroll position.
            let mut e = virtualizer::IndexEmitter::new(r, emit);
            e.emit_pinned(0);
            e.emit_visible();
        }));

    let mut v = Virtualizer::new(opts);

    // First render: scroll offset comes from the provider.
    println!("initial scroll_offset={}", v.scroll_offset());
    println!("initial scroll_rect={:?}", v.scroll_rect());

    // Adapter updates rect + scroll offset on events.
    v.apply_scroll_frame(
        Rect {
            main: 12,
            cross: 80,
        },
        200,
        0,
    );

    let mut items = Vec::new();
    v.for_each_virtual_item_keyed(|it| items.push(it));
    println!(
        "is_scrolling={}, visible_range={:?}, items_len={}",
        v.is_scrolling(),
        v.visible_range(),
        items.len()
    );
    println!("first_item={:?}", items.first());

    // Demonstrate scroll-to helpers.
    let target = v.scroll_to_index_offset(500, Align::Start);
    v.set_scroll_offset_clamped(target);
    println!("after scroll_to_index: scroll_offset={}", v.scroll_offset());

    // Demonstrate dynamic measurement + scroll adjustment.
    let applied = v.resize_item(0, 20);
    println!("resize_item applied_scroll_adjustment={applied}");

    // Simulate reorder: change key mapping. This automatically rebuilds per-index sizes from the
    // key-based measurement cache. In real apps, you usually keep `get_item_key` stable and call
    // `sync_item_keys()` when your dataset is reordered while `count` stays the same.
    v.set_get_item_key(|i| if i == 0 { 1 } else { i as u64 });

    // Debounced scrolling reset without relying on a native scrollend event.
    v.update_scrolling(200);
    println!("after update_scrolling: is_scrolling={}", v.is_scrolling());

    // Toggle enabled to disable all queries.
    v.set_enabled(false);
    let mut disabled_len = 0usize;
    v.for_each_virtual_item(|_| disabled_len += 1);
    println!(
        "disabled total_size={}, items_len={}",
        v.total_size(),
        disabled_len
    );
}

pub fn collect_virtual_indexes(&self, out: &mut Vec<usize>)

Collects virtual item indexes into out (clears out first).

This is a convenience wrapper around Self::for_each_virtual_index. For maximum performance, prefer for_each_virtual_index and reuse a scratch buffer in your adapter.

pub fn collect_virtual_indexes_for( &self, scroll_offset: u64, viewport_size: u32, out: &mut Vec<usize>, )

Collects virtual item indexes into out for a given scroll_offset/viewport_size.

This clears out first.

pub fn collect_virtual_items(&self, out: &mut Vec<VirtualItem>)

Collects virtual items into out (clears out first).

This is a convenience wrapper around Self::for_each_virtual_item. For maximum performance, prefer for_each_virtual_item and reuse a scratch buffer in your adapter.

pub fn collect_virtual_items_for( &self, scroll_offset: u64, viewport_size: u32, out: &mut Vec<VirtualItem>, )

Collects virtual items into out for a given scroll_offset/viewport_size.

This clears out first.

pub fn collect_virtual_items_keyed(&self, out: &mut Vec<VirtualItemKeyed<K>>)

Collects keyed virtual items into out (clears out first).

This is a convenience wrapper around Self::for_each_virtual_item_keyed.

pub fn collect_virtual_items_keyed_for( &self, scroll_offset: u64, viewport_size: u32, out: &mut Vec<VirtualItemKeyed<K>>, )

Collects keyed virtual items into out for a given scroll_offset/viewport_size.

This clears out first.

pub fn index_at_offset(&self, offset: u64) -> Option<usize>

pub fn item_start(&self, index: usize) -> Option<u64>

pub fn item_size(&self, index: usize) -> Option<u32>

Examples found in repository

examples/keyed_reorder.rs (line 10)

fn main() {
    // Example: measurements follow keys after reorder.
    let mut v = Virtualizer::new(VirtualizerOptions::new(2, |_| 1));
    v.measure(0, 10);
    println!(
        "before reorder: size0={:?} size1={:?}",
        v.item_size(0),
        v.item_size(1)
    );

    // Simulate data reorder by changing the key mapping.
    v.set_get_item_key(|i| if i == 0 { 1 } else { 0 });
    // Note: in real apps you usually keep `get_item_key` stable and call `sync_item_keys()` when
    // your underlying dataset is reordered while `count` stays the same.

    println!(
        "after reorder: size0={:?} size1={:?}",
        v.item_size(0),
        v.item_size(1)
    );
}

examples/measurement_cache.rs (line 19)

fn main() {
    // Example: export and import measurement cache (key -> measured size).
    //
    // This is useful if you want to persist measurements across screens/sessions so that the
    // virtualizer can start with better estimates and avoid re-measuring everything.
    let mut v1 = Virtualizer::new(VirtualizerOptions::new(10, |_| 1));
    v1.measure(2, 10);
    v1.measure(5, 42);

    let snapshot = v1.export_measurement_cache();
    println!("exported_cache_len={}", snapshot.len());

    let mut v2 = Virtualizer::new(VirtualizerOptions::new(10, |_| 1));
    println!(
        "before import: size2={:?} size5={:?}",
        v2.item_size(2),
        v2.item_size(5)
    );

    v2.import_measurement_cache(snapshot);
    println!(
        "after import: cache_len={} size2={:?} size5={:?}",
        v2.measurement_cache_len(),
        v2.item_size(2),
        v2.item_size(5)
    );
}

pub fn item_end(&self, index: usize) -> Option<u64>

pub fn virtual_item_for_offset(&self, offset: u64) -> Option<VirtualItem>

pub fn virtual_item_keyed_for_offset( &self, offset: u64, ) -> Option<VirtualItemKeyed<K>>

pub fn max_scroll_offset(&self) -> u64

pub fn clamp_scroll_offset(&self, offset: u64) -> u64

Trait Implementations

impl<K: Clone> Clone for Virtualizer<K>

fn clone(&self) -> Virtualizer<K>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<K: Debug> Debug for Virtualizer<K>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.