read-hash
Purpose: Get data from hash table.
read-hash <hash> \
key <key> \
value [ define ] <value> \
[ delete [ <delete> ] ] \
[ status [ define ] <status> ] \
[ old-key [ define ] <old key> ]
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:
new-hash h size 300
write-hash h key "X0029" value "some data"
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:
read-hash h traverse begin
while (1) {
read-hash h traverse key define k value define r
if (k == NULL) break;
pf-out "Key [%s] data [%s]\n", k, r
}
See also
Hash table (
get-hash new-hash purge-hash read-hash resize-hash write-hash )
SEE ALL (
documentation)