Trait Cursor 

pub trait Cursor: Send + Sync {
    type Value: 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);

    // Provided methods
    fn retain(&mut self, should_retain: &impl Fn(&Self::Value) -> bool) { ... }
    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.
• The cursor mutates the linked list in place. If the sole element is deleted, dropping the cursor removes the map entry.

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

Required Associated Types

type Value: 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.

Advances through cursor states 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.

Provided Methods

fn retain(&mut self, should_retain: &impl Fn(&Self::Value) -> bool)

Retains only the values in the cursor for which should_retain returns true. All other values are removed.

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".

Implementors