Read list

Purpose: Read/update key/value pair from a linked list.

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

Copied!

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

Copied!