19.0.0 released Nov 08, 2023
Write hash

Purpose: Store key/value pair into a hash table.

write-hash <hash> \
    key <key> \
    value <value> \
    [ status [ define ] <status> ] \
    [ old-value [ define ] <old value> ]
    [ old-key [ define ] <old key> ]
    [ process-key ]
    [ process-value ]

write-hash will store pointers <key> (in "key" clause) and <value> (specified in "value" clause) into hash table <hash>, which must be created with new-hash.

<key> is a string and <value> can be a pointer of any type, allowing storage of any kind of data; collectively they are called an "element". Memory pointed by <key> and <value> must not go out of scope or be freed while the hash is used - if necessary, store a copy (see copy-string for strings); this is because write-hash does not make copies of <key> and <value>, rather only the pointers to those are stored in the hash.

If <key> already exists in the hash table, then the pointer to old value associated with it is returned in the optional <old value> (in "old-value" clause) and the pointer to old key is returned in the optional <old key> (in "old-key" clause) - in this case the optional number <status> (in "status" clause) has a value of VV_ERR_EXIST.

If <key> did not exist, <status> will be VV_OKAY and <old value>/<old key> are NULL. Both <status> and <old value>/<old key> can be created with "define" clause.

Note that while <key> and <old key> will contain matching strings when <status> is VV_ERR_EXIST, the <old key> will contain a pointer to a key used in the previous write-string statement.

If a <hash> was created with "process-scope" clause (see new-hash), then:
If a <hash> was not created with "process-scope", then "process-key" and "process-data" have no effect.
Writing data to hash:
new-hash define h size 1000
write-hash h key "mykey" value "some data"

Writing new value with the same key and obtaining the previous value (which is "some data"):
write-hash h key "mykey" value "new data" status define st old-value define od
if (st == VV_ERR_EXIST) {
    @Previous value for this key is <<p-out od>>

The following is a hash key/value server, where a process-scoped hash is created. It provides inserting, deleting and querying key/value pairs. Such a server process can run indefinitely and provide a key service:
%% /hashsrv
    out-header default

    new-hash define h size 1024 process-scope

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

    if-task "add" // Add data to hash, make a copy as input params are request-scoped
        copy-string key to define c_key
        copy-string data to define c_data
        write-hash h key c_key value c_data old-value define old_data old-key define old_key status define st
        if (st == VV_ERR_EXIST) {
            delete-mem old_key
            delete-mem old_data
        @Added [<<p-out key>>]
    else-task "delete" // Delete data and obtain the value deleted
        read-hash h key (key) value define val old-key define okey delete 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 hash based on key value
        read-hash h key (key) value define val status define st
        if (st == VV_ERR_EXIST) {
            @Not found, queried [<<p-out key>>]
        } else {
            @Value [<<p-out val>>]

See read-hash for more examples.
See also
Hash table
See all

You are free to copy, redistribute and adapt this web page (even commercially), as long as you give credit and provide a dofollow link back to this page - see full license at CC-BY-4.0. Copyright (c) 2019-2023 Dasoftver LLC. Vely and elephant logo are trademarks of Dasoftver LLC. The software and information on this web site are provided "AS IS" and without any warranties or guarantees of any kind. Icons from table-icons.io copyright PaweĊ‚ Kuna, licensed under MIT license.