read-hash

Get data from hash table.

// Random access to hash data:

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

// 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 <value> (in "value" clause) based on a <key> (in "key" clause) from <hash> created by new-hash. <value> can be created as a string with optional "define", but in general can be a pointer of any type.

You can also delete the key/value pair from the hash by using optional "delete" clause - the <value> is still obtained though it is no longer in the hash table.

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".

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.

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

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
}

Hash table ( get-hash   new-hash   purge-hash   read-hash   resize-hash   write-hash  )  SEE ALL (documentation)