NAME¶

read-hash - (hash)

PURPOSE¶

Get data from hash.

SYNTAX¶

// Random access to hash data:
read-hash <hash> \


    key <key> \


    value <value> \


    [ delete [ <delete> ] ] \


    [ status <status> ] 
// Sequential access to hash data:
read-hash <hash> traverse begin
read-hash <hash> traverse \


    key <key> \


    value <value>  \


    [ delete [ <delete> ] ] \


    [ status <status> ] \

DESCRIPTION¶

WITHOUT TRAVERSE CLAUSE

read-hash will obtain an element from <hash>, which is a string <value> (in "value" clause) based on a string <key> (in "key" clause). <hash> was created by new-hash.

You can also delete an element from the hash by using "delete" clause - the <value> is still obtained though it is no longer in the hash. The hash element is deleted if "delete" clause is used without boolean variable <delete>, or if <delete> evaluates to true.

If no <key> was found in the hash, <status> number (in "status" clause) is GG_ERR_EXIST and <value> is unchanged, otherwise <status> is GG_OKAY.

WITH TRAVERSE CLAUSE

read-hash with "traverse" clause obtains <key> and <value> of the current element, and then positions to the next one. You can also delete this element from the hash by using "delete" clause - the <key> and <value> are still obtained though the element is no longer in the hash. The hash element is deleted if "delete" clause is used without boolean variable <delete>, or if <delete> evaluates to true.

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 - note they are not extracted in any particular order. When there are no more elements, <key> and <value> are unchanged and <status> number (in "status" clause) is GG_ERR_EXIST, otherwise <status> is GG_OKAY.

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

EXAMPLES¶

In this example, a 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 
// Write to a hash
write-hash h key "X0029" value "some data"
// Read from a hash 
read-hash h key "X0029" value res status f delete
if-true f equal GG_ERR_EXIST


    @No data in the hash!
else-if


    @Deleted value is <<print-out res>>
end-if

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

// Position at the beginning of the hash 
read-hash h traverse begin
start-loop


    // Get elements, one by one, until NULL returned as a key


    read-hash h traverse key k value r status f


    if-true f equal GG_ERR_EXIST


        break;


    end-if


    print-format "Key [%s] data [%s]\n", k, r
end-loop

SEE ALSO¶

Hash

get-hash new-hash purge-hash read-hash resize-hash write-hash See all documentation