GOLF(2gg)

💖 GOLF(2gg) — read-list 💖

okay bestie, sit down, hydrate, because we're about to talk about the read-list function from the Development section of the Golf manual and honestly? it's giving iconic. ✨

---

🌸 NAME 🌸

read-list — it's a linked-list situation 💅 (yes, literally, that's the whole name, she's mysterious like that)

---

🎀 PURPOSE 🎀

Read and/or update a key/value pair from a linked list. no cap, that's the vibe. 🦋

---

✨ SYNTAX ✨

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

look at her. she's beautiful. the \ line continuations are doing their little thing. 🫶

---

👑 DESCRIPTION 👑

so read-list goes into your linked <list> and pulls out an element, dropping it into the <key> string (that's the key clause) and the <value> string (that's the value clause). 🍓

here's the tea though: after every read-list, the list's current element stays exactly where it was read. it does not move on its own. if you wanna move it, that's a position-list job (say, to the next one). the way that she just stays put... lowkey respectful. 🙈

if an element could not be retrieved, the <status> number (in the status clause) will be GG_ERR_EXIST, and <key> and <value> will be unchanged. when does that happen? when the current list element is beyond the last element — like, for instance, if the end clause got used in a position-list statement. 💀 otherwise <status> is GG_OKAY. periodt.

when the list is first created with new-list, read-list starts at the first element in the list. wanna change that default current element? that's position-list again. she's everywhere, she's the main character. 👑

you can also update the element's value with the update-value clause by handing over an <update value> string. and the timing? chef's kiss. this update happens after a <value> has been retrieved, which means you can get the previous value in the same statement. obsessed. 🔥

same deal for the key: you can update the element's key with the update-key clause by specifying an <update key> string. this update also happens after a <key> has been retrieved, so you get the previous key in the same statement too. two for one, we love a multitasker. 💜

---

🌈 EXAMPLES 🌈

okay so in this example, a linked list gets created and three key/value pairs get added. then they get retrieved from the last towards the first element, and then again in the opposite direction. slay. ✨

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

the way she walks backwards through the list and then forwards again... character development. 🦋 and yes, purge-list mylist at the end because we clean up after ourselves in this house. 🧚

---

💫 SEE ALSO 💫

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

go read those too, bestie, they're all part of the same friend group. 🫶

---

and that's the whole page!! 💖 this was GOLF(2gg) from Development, dated $DATE, version $VERSION — mwah, iconic, no notes, go forth and read your lists. 💅✨🎀