GOLF(2gg)

NAME
read-tree - (tree)

PURPOSE
Search/update a tree.

SYNTAX

        read-tree <tree> \
            ( equal <search key> | lesser <search key> | greater <search key> | \
                lesser-equal <search key> | greater-equal <search key> | \
                min-key | max-key ) \
            [ value <value> ] \
            [ update-value <update value> ] \
            [ key <key> ] \
            [ status <status> ] \
            [ new-cursor <cursor> ]

DESCRIPTION
read-tree will search <tree> (created with new-tree) for a node with the string key that is:

    • equal to <search key> ("equal" clause)

    • lesser than <search key> ("lesser" clause)

    • greater than <search key> ("greater" clause)

    • lesser or equal than <search key> ("lesser-equal" clause)

    • greater or equal than <search key> ("greater-equal" clause)

    • a minimum key in the tree ("min-key" clause)

    • a maximum key in the tree ("max-key" clause)

The <status> in "status" clause will be GG_OKAY if a key conforming to one of these criteria is found, and GG_ERR_EXIST if not.

If a key is found, the value associated with the key can be obtained with "value" clause in <value>; an existing key used to originally insert this value into the tree can be obtained with "key" clause in string <key>. If a key is not found, both <value> and <key> are unchanged.

You can update the value associated with a found key with "update-value" clause by specifying <update value> string. This update is performed after <value> has been retrieved, allowing you to obtain the previous value in the same statement.

If you'd like to iterate the ordered list of keys in a tree, create a <cursor> by using "new-cursor" clause, in which case <cursor> will be positioned on a found tree node. See use-cursor for more on using cursors. Cursors are useful in range searches; typically you'd find a key that is an upper or lower bound of a range and then keep iterating to a lesser or greater value until some criteria is met, such as when the opposite bound is found. Golf treees are by default constructed so that such iterations are O(1) in complexity, meaning each is a single tree node access (see new-tree).

EXAMPLES
In this example, a million key/value pairs are inserted into a tree, and then each of them is searched for and then displayed back (see write-tree for more on inserting into a tree). Both the key and the data are a numerical value of a key:

        %% /tree-example public

            new-tree mytree key-as "positive integer" // create new tree

            set-number i
            start-loop use i start-with 0 repeat 1000000
                number-string i to key
                set-string data=key
                write-tree mytree key (key) value data // insert key/data to the tree
            end-loop

            start-loop use i start-with 0 repeat 1000000
                number-string i to key
                // search tree for each key previously inserted
                read-tree mytree equal (key) status st value data
                if-true st not-equal GG_OKAY
                    @Could not find key <<print-out key>>
                else-if
                    @Found data <<print-out data>> associated with key <<print-out key>>
                end-if
                delete-string key
            end-loop
        %%

SEE ALSO
 Tree

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