4.9 Index Cursors

Index cursors are just like BTree cursors except you can get the main BTree value instead of the index value. There are also a parallel set of operations such as cursor-pnext instead of cursor-next which returns exists, key, primary-btree-value and index-value = primary-btree-key.

Operations that have the same behavior, but return primary btree values and keys are:

BTree Cursor Function		Index Cursor Function
cursor-first	=>	cursor-pfirst
cursor-last	=>	cursor-plast
cursor-current	=>	cursor-pcurrent
cursor-next	=>	cursor-pnext
cursor-prev	=>	cursor-pprev
cursor-set	=>	cursor-pset
cursor-set-range	=>	cursor-set-prange

The big difference between btree cursors and index cursors is that indices can have duplicate key values. This means we have to choose between incrementing over elements, unique key-values or only within a duplicate segment. There are cursor operations for each:

• Simple move. Standard btree operations work plus cursor-pnext and cursor-pprev
• Move to a different key value. cursor-pnext-nodup and cursor-pprev-nodup
• Move to next duplicate key value. cursor-pnext-dup and cursor-pprev-dup

After incrementing through a set of duplicate items using a xxx-dup function, the last next operation returns nil indicating there are no more duplicates. The consequence of this is that the cursor is now uninitialized (cursor-initialized-p) and needs to be reset by a set or set both call.

See Index Cursor API for further details.