Read hash

19.0.0 released Nov 08, 2023

Read hash

Purpose: Get data from hash table.

// Random access to hash data:

read-hash <hash> \
    key <key> \
    value [ define ] <value> \
    [ delete [ <delete> ] ] \
    [ status [ define ] <status> ] \
    [ old-key [ define ] <old key> ]

// Sequential access to hash data:

read-hash <hash> traverse begin

read-hash <hash> traverse \
    key [ define ] <key> \
    value [ define ] <value>

Without "traverse" clause

read-hash will obtain an element from <hash>, which is a <value> pointer (in "value" clause) based on a <key> (in "key" clause). <hash> was created by new-hash. <value> can be created as a string with optional "define", but in general can be a pointer of any type. An optional "old-key" clause will obtain the pointer to a key used in a previous write-hash statement; it can be created with an optional "define".

You can also delete an element from the hash by using optional "delete" clause - the <value> is still obtained though it is no longer in the hash table. The hash element is deleted if "delete" clause is used without optional boolean expression <delete>, or if <delete> evaluates to true. Note that "delete" clause will not free any possibly allocated memory for either key or value stored in the element (see write-hash).

If no <key> was found in the hash table, optional <status> (in "status" clause) is VV_ERR_EXIST and <value> is NULL, otherwise it is VV_OKAY. A number <status> can be created with optional "define".

Note that while <key> and <old key> will contain matching strings, the <old key> will contain a pointer to a key used in a prior write-string statement, which may be different than <key>.

With "traverse" clause

read-hash with "traverse" clause obtains <key> and <value> of the current element, and then positions to the next one. Use "begin" clause to position at the very first element. This is useful if you wish to get all the key/value pairs from a hash table - note they are not extracted in any particular order. When there are no more elements, <key> is NULL.

You may search, add or delete elements while traversing a hash table, and this will be reflected in all elements not yet traversed.

Examples

In this example, new hash is created, a key/value pair is written to it, and then the value is obtained and the element deleted; return status is checked:

// Create new hash
new-hash h size 300

// Write to hash
write-hash h key "X0029" value "some data"

// Read from hash
read-hash h key "X0029" value define res status define f delete
if (f == VV_ERR_EXIST) {
    @No data in hash!
} else {
    @Deleted value is <<p-out res>>
}

The following will traverse the entire hash and display all the data:

// Position at the beginning of hash table
read-hash h traverse begin
while (1) {
    // Get elements, one by one, until NULL returned as a key
    read-hash h traverse key define k value define r
    if (k == NULL) break;
    pf-out "Key [%s] data [%s]\n", k, r
}