Vely logo Empower C
install  tutorials  examples
documentation  license  about

12.1.0 released on Sep 19, 2022

read-hash



PURPOSE:


Get data from hash table.

SYNTAX:


// 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>


DESCRIPTION:



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.

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
}


SEE ALSO:


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



Copyright (c) 2022 DaSoftver LLC. Vely is a trademark of Dasoftver LLC. The software and information herein are provided "AS IS" and without any warranties or guarantees of any kind. Icons copyright PaweĊ‚ Kuna licensed under MIT. This web page is licensed under CC-BY-SA-4.0.