GOLF(2gg)

NAME
read-list - (linked-list)

PURPOSE
Read/update key/value pair from a linked list.

SYNTAX

        read-list <list> \
            key <key> \
            value <value> \
            [ update-value <update value> ] [ update-key <update key> ] \
            [ status <status> ]

DESCRIPTION
read-list retrieves an element from the linked <list>, storing it into <key> string (in "key" clause) and <value> string (in "value" clause). After each read-list, the list's current element remains at the element read; use position-list to move it (for instance to the next one).

If an element could not be retrieved, <status> number (in "status" clause) will be GG_ERR_EXIST and <key> and <value> will be unchanged (this can happen if current list element is beyond the last element, such as for instance if "end" clause is used in position-list statement), otherwise <status> is GG_OKAY.

Initially when the list is created with new-list, read-list starts with the first element in the list. Use position-list to change the default list's current element.

You can update the element's value with "update-value" clause by specifying <update value> string. This update is performed after a <value> has been retrieved, allowing you to obtain the previous value in the same statement.

You can update the element's key with "update-key" clause by specifying <update key> string. This update is performed after a <key> has been retrieved, allowing you to obtain the previous key in the same statement.

EXAMPLES
In this example, a linked list is created, and three key/value pairs added. They are then retrieved from the last towards the first element, and then again in the opposite direction:

        new-list mylist

        // Add data to the list
        write-list mylist key "key1" value "value1"
        write-list mylist key "key2" value "value2"
        write-list mylist key "key3" value "value3"

        position-list mylist last
        start-loop
           // Get data from the list starting with the last one, producing value1, value2, value3
           read-list mylist key k value v
           @Obtained key <<print-out k>> with value <<print-out v>>
           position-list mylist previous status s
           // Check if no more data
           if-true s equal GG_ERR_EXIST
               break-loop
           end-if
        end-loop

        // Now the list is positioned at the first element, reading produces value3, value2, value1
        start-loop
           read-list mylist key k value v status s
           if-true s equal GG_ERR_EXIST
               break-loop
           end-if
           @Again obtained key <<print-out k>> with value <<print-out v>>
           position-list mylist next
        end-loop

        purge-list mylist

SEE ALSO
 Linked list

delete-list get-list new-list position-list purge-list read-list write-list See all documentation