GOLF(2gg)

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