use-cursor - (tree)

use-cursor uses <cursor> previously created (see read-tree, write-tree) for iteration over tree nodes with lesser or greater key values. It can also obtain keys and values for such nodes, as well as update their values. CURRENTNODE 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 tree), the current node will be unchanged and <status> (in "status" clause) will be GG_ERR_EXIST. KEY,VALUE,UPDATINGVALUE,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.

The following will find a value with key "999", and then iterate in the tree to find all lesser values (in descending order): set-string k = "999" read-tree mytree equal k status st \ value val new-cursor cur start-loop if-true st equal GG_OKAY @Value found is [<<print-out val>>] for key [<<print-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-tree.

use-cursor - (tree)

Iterate to a lesser or greater key in a tree.

Tree delete-treeget-treenew-treepurge-treeread-treeuse-cursorwrite-tree See all documentation $DATE $VERSION GOLF(2gg)

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