Use cursor

Purpose: Iterate to a lesser or greater key in an index.

 use-cursor <cursor> ( current | get-lesser | get-greater ) \
     [ key <key> ] \
     [ value <value> ] \
     [ update-value <update value> ] \
     [ status <status> ]

use-cursor uses <cursor> previously created (see read-index, write-index) for iteration over index nodes with lesser or greater key values. It can also obtain keys and values for such nodes, as well as update their values.

Current node

A <cursor> has a current node, which is first computed by using "current", "get-lesser" or "get-greater" clauses, and then any other clauses are applied to it (such as "key", "value" and "update-value").

The computation of a current node is performed by using a <cursor>'s "previous current node", i.e. the current node just before use-cursor executes. If "current" clause is used, the current node remains the same as previous current node. If "get-lesser" clause is used, a node with a key that is the next lesser from the previous current will become the new current. If "get-greater" clause is used, a node with a key that is the next greater from the previous current will become the new current.

If the new current node can be found, then other use-cursor clauses are applied to it, such as to obtain a <key> or <value>, or to <update value>. If, as a result of either of these clauses, the new current node cannot be found (for instance there is no lesser or greater key in the index), the current node will be unchanged and <status> (in "status" clause) will be GG_ERR_EXIST.

Key, value, updating value, status

"key" clause will obtain the key in a current node into <key> string. The value of current node can be obtained in <value> in "value" clause; <value> is a string. The value of current node can be updated to <update value> in "update-value" clause; <update value> is a string. This update is performed after <value> has been retrieved, allowing you to obtain the previous value in the same statement.

"status" clause can be used to obtain <status> number, which is GG_ERR_EXIST if the new current node cannot be found, in which case the current node, <key> and <value> are unchanged. Otherwise, <status> is GG_OKAY.

Examples

The following will find a value with key "999", and then iterate in the index to find all lesser values (in descending order):

 set-string k = "999"
 read-index myindex equal k status st \
     value val new-cursor cur
 start-loop
     if-true st equal GG_OKAY
         @Value found is [<<p-out val>>] for key [<<p-out k>>]
         use-cursor cur get-lesser status st value val key k
     else-if
         break-loop
     end-if
 end-loop

For more examples, see new-index.