Struct Cursor 

pub struct Cursor {
    pub index: usize,
    pub node: Arc<Node>,
    pub parent: Option<Box<Cursor>>,
}

A cursor pointing to a specific position in a prolly tree.

Cursors provide efficient navigation through the tree structure without recursion. They maintain a reference to the current node and an index within that node, with optional parent linkage for upward navigation.

Cloning

Cursors are cloneable. Cloned cursors are independent of the original - advancing one does not affect the other.

Fields

index: usize

Current position within the node (0-based index)

node: Arc<Node>

Current node (Arc for efficient cloning)

parent: Option<Box<Cursor>>

Parent cursor for upward navigation

Implementations

impl Cursor

pub fn at_item<S: Store>( store: &S, tree: &Tree, key: &[u8], ) -> Result<Self, Error>

Navigate to the position of a key in the tree.

Follows the Arbor spec’s CursorAtItem algorithm:

1. Find index in current node
2. If leaf, done
3. Otherwise, recurse to child with parent linkage

Arguments

• store - The storage backend to load nodes from
• tree - The tree to navigate
• key - The key to position at

Returns

• Ok(Cursor) - A cursor positioned at or near the key
• Err - If a storage error occurs

Behavior

• If the tree is empty, returns a cursor with an empty node (is_valid() == false)
• If the key exists, positions at that exact key
• If the key doesn’t exist, positions at the greatest key <= target

pub fn get_key(&self) -> Option<&[u8]>

Get the current key at the cursor position.

Returns

• Some(&[u8]) - The key at the current position
• None - If the cursor is invalid (empty node or index out of bounds)

pub fn get_value(&self) -> Option<&[u8]>

Get the current value at the cursor position.

Only returns a value for leaf nodes. Internal nodes store CIDs, not values.

Returns

• Some(&[u8]) - The value at the current position (leaf nodes only)
• None - If the cursor is invalid or at an internal node

pub fn is_valid(&self) -> bool

Check if the cursor is valid.

A cursor is valid if:

• The node is not empty
• The index is within bounds

Returns

true if the cursor points to a valid entry, false otherwise.

pub fn is_at_end(&self) -> bool

Check if the cursor is at the end of its current node.

Returns

true if the cursor is at the last entry of the node, false otherwise.

pub fn advance<S: Store>(&mut self, store: &S) -> bool

Advance the cursor to the next entry in the tree.

Follows the Arbor spec’s AdvanceCursor algorithm:

1. Try to advance within current node
2. If at end, navigate up to parent
3. Advance parent and load next child
4. Descend to leftmost leaf of next subtree

Arguments

• store - The storage backend to load nodes from

Returns

• true if successfully advanced to next entry
• false if at end of tree (no more entries)

Behavior

After returning false, the cursor becomes invalid (is_valid() returns false).

Trait Implementations

impl Clone for Cursor

fn clone(&self) -> Cursor

Returns a duplicate of the value.

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

Performs copy-assignment from source.