Trait Cursor 

pub trait Cursor: Send + Sync {
    type Value: Eq + Send + Sync;

    // Required methods
    fn next(&mut self) -> Option<&Self::Value>;
    fn insert(&mut self, value: Self::Value);
    fn delete(&mut self);
    fn update(&mut self, value: Self::Value);
    fn prune(&mut self, predicate: &impl Fn(&Self::Value) -> bool);

    // Provided method
    fn find(&mut self, predicate: impl Fn(&Self::Value) -> bool) -> bool { ... }
}

A mutable iterator over the values associated with a translated key, allowing in-place modifications.

The Cursor provides a way to traverse and modify the linked list of values associated with a translated key by an index while maintaining its structure. It supports:

• Iteration via next() to access values.
• Modification via update() to change the current value.
• Insertion via insert() to add new values.
• Deletion via delete() to remove values.

Safety

• Must call next() before update(), insert(), or delete() to establish a valid position.
• Once next() returns None, only insert() can be called.
• Dropping the Cursor automatically restores the list structure by reattaching any detached next nodes.

If you don’t need advanced functionality, just use insert(), insert_and_prune(), or remove() from Unordered instead.

Required Associated Types

type Value: Eq + Send + Sync

The type of values the cursor iterates over.

Required Methods

fn next(&mut self) -> Option<&Self::Value>

Advances the cursor to the next value in the chain, returning a reference to it.

This method must be called before any other operations (insert(), delete(), etc.). If either insert() or delete() is called, next() must be called to set a new active item. If after insert(), the next active item is the item after the inserted item. If after delete(), the next active item is the item after the deleted item.

Handles transitions between phases and adjusts for deletions. Returns None when the list is exhausted. It is safe to call next() even after it returns None.

fn insert(&mut self, value: Self::Value)

Inserts a new value at the current position.

fn delete(&mut self)

Deletes the current value, adjusting the list structure.

fn update(&mut self, value: Self::Value)

Updates the value at the current position in the iteration.

Panics if called before next() or after iteration is complete (Status::Done phase).

fn prune(&mut self, predicate: &impl Fn(&Self::Value) -> bool)

Removes anything in the cursor that satisfies the predicate.

Provided Methods

fn find(&mut self, predicate: impl Fn(&Self::Value) -> bool) -> bool

Advances the cursor until finding a value matching the predicate.

Returns true if a matching value is found, with the cursor positioned at that element. Returns false if no match is found and the cursor is exhausted.

After a successful find (returning true), the cursor is positioned at the found element, allowing operations like update() or delete() to be called on it without requiring another call to next().

This method follows similar semantics to Iterator::find, consuming items until a match is found or the iterator is exhausted.

Examples

let mut cursor = index.get_mut(&key)?;
if cursor.find(|&value| value == 42) {
    // Cursor is positioned at the element with value 42
    cursor.update(100); // Update it to 100
}

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<K: Ord + Send + Sync, V: Eq + Send + Sync> Cursor for commonware_storage::index::ordered::Cursor<'_, K, V>

type Value = V

impl<K: Send + Sync, V: Eq + Send + Sync> Cursor for commonware_storage::index::unordered::Cursor<'_, K, V>

type Value = V