NAME

       use-cursor -  (tree)

PURPOSE

       Iterate to a lesser or greater key in a tree.

SYNTAX

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

DESCRIPTION

       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.

       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 tree), 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 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.

SEE ALSO

        Tree

       delete-tree get-tree new-tree purge-tree read-tree use-cursor write-tree See all documentation

$DATE                                               $VERSION                                           GOLF(2gg)