Read hash

Purpose: Get data from hash.

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

Copied!

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.

- Subscription shortcut
You can also get the value of a <hash> element by using subscription operator ([]), for instance here you'd reference the element "one" of hash 'vals' in the comparison statement:

new-hash sub
write-hash sub key "three" value "some value"
...
if-true sub["three"] equal "some value"
    @Found element
end-if

Copied!

You can use the subscriptive form of <hash>[<index>] in any expression, where <index> is a string value that matches the hash key. Note that if element <hash>[<index>] does not exist, the value returned is an empty string (""); use read-hash form to check status or delete an element.

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

Copied!

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

Copied!