Vely logo install | documentation | examples | changelog
16.10.0 released May 10, 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> ]

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.
Examples
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>>
}

See read-hash for more examples.
See also
Hash table ( get-hash   new-hash   purge-hash   read-hash   resize-hash   write-hash  )  SEE ALL (documentation)


Copyright (c) 2017-2023 Dasoftver LLC