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