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

$DATE                                               $VERSION                                           GOLF(2gg)