Write tree

19.0.0 released Nov 08, 2023

Write tree

Purpose: Insert a key/value pair into a tree.

write-tree <tree> key <key> value <value> \
    [ status [ define ] <status> ] \
    [ new-cursor [ define ] <cursor> ]
    [ process-key ]
    [ process-value ]

write-tree inserts string <key> and associated <value> (a pointer to any type) into <tree> created by new-tree.

If <key> already exists in <tree>, <status> (in optional "status" clause) will be VV_ERR_EXIST and nothing is inserted into <tree>, otherwise it is VV_OKAY.

If optional "new-cursor" clause is used, then a <cursor> will be positioned on a newly inserted tree node. You can use use-cursor to iterate to nodes with lesser and greater key values. A cursor is a pointer to type "vely_tree_cursor".

<status> and <cursor> can be created with optional "define".

If a <tree> was created with "process-scope" clause (see new-tree), then:

if <key> and/or <value> are Vely allocated memory, then they will not be freed when the current request ends, rather they will persist while the process stays up, unless they are deleted (see delete-mem, delete-tree, purge-tree),
if <key> and/or <value> are otherwise global variables (see new-tree), then you must use "process-key" clause to specify that <key> is a global variable, and "process-value" to specify that <value> is a global variable. If you do not, it will be assumed that <key> and/or <value> are allocated by Vely and your program will likely error out.

If a <tree> was not created with "process-scope", then "process-key" and "process-data" have no effect.

Examples

Insert key "k" with value "d" into "mytree", and obtain status in "st":

write-tree mytree key k value d status define st

The following is an example of a process-scoped tree. Such a tree keeps its data across the requests, for as long as the process is alive:

%% /treesrv
    out-header default

    do-once
    new-tree define t process-scope
    end-do-once

    // Get input parameters
    task-param op
    input-param key
    input-param data

    if-task "add" // Add data to tree
        // Make a copy of key,data so they are Vely-allocated
        copy-string key to define c_key
        copy-string data to define c_data
        write-tree t key c_key value c_data status define st
        if (st == VV_ERR_EXIST) {
            delete-mem c_key
            delete-mem c_data
        }
        @Added [<<p-out key>>]
    else-task "delete" // Delete data and obtain the value deleted
        delete-tree t key (key) value define val old-key define okey status define st
        if (st == VV_ERR_EXIST) {
            @Not found [<<p-out key>>]
        } else {
            // If found, then delete key and value
            @Deleted [<<p-out val>>]
            delete-mem val
            delete-mem okey
        }
    else-task "query" // Query tree based on key value
        read-tree t key (key) value define val status define st
        if (st == VV_ERR_EXIST) {
            @Not found, queried [<<p-out key>>]
        } else {
            @Value [<<p-out val>>]
        }
    end-task
%%

See read-tree for more examples.