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!