GOLF(2gg)

💖 GOLF(2gg) 💖

okay bestie, welcome to the GOLF manual, page GOLF(2gg), Development section — this one is literally all about use-cursor, and it's giving ✨tree iteration✨ energy, so grab a boba and let's go 🧋

---

🌸 NAME 🌸

use-cursor — (tree)

---

🎀 PURPOSE 🎀

Iterate to a lesser or greater key in a tree. that's it, that's the vibe 🦋

---

✨ SYNTAX ✨

use-cursor <cursor> ( current | get-lesser | get-greater ) \
    [ key <key> ] \
    [ value <value> ] \
    [ update-value <update value> ] \
    [ status <status> ]

---

💅 DESCRIPTION 💅

so use-cursor takes a <cursor> you already made earlier (peep read-tree, write-tree 👀) and uses it to iterate over tree nodes with lesser or greater key values. it can also get the keys and values of those nodes, and lowkey it can update their values too. multitasking queen 👑

🫶 CURRENT NODE 🫶

every <cursor> has a current node, right? that node gets computed first by using the current, get-lesser or get-greater clauses, and then all your other clauses get applied to it (think key, value and update-value). order matters, no cap.

the computation of a current node happens using the <cursor>'s "previous current node" — aka the current node right before use-cursor executes. here's the tea:

• if you use the current clause, the current node stays exactly the same as the previous current node. iconic, no notes 💅
• if you use the get-lesser clause, a node with a key that's the next lesser from the previous current becomes the new current ⬅️
• if you use the get-greater clause, a node with a key that's the next greater from the previous current becomes the new current ➡️

if the new current node can be found, then your other use-cursor clauses get applied to it — like grabbing a <key> or a <value>, or doing an <update value>. but if, as a result of either of these clauses, the new current node cannot be found (for instance, there's literally no lesser or greater key in the tree 😭), then the current node will be unchanged and <status> (in the status clause) will be GG_ERR_EXIST.

💜 KEY, VALUE, UPDATING VALUE, STATUS 💜

okay so the key clause will obtain the key in a current node into the <key> string. the value of the current node can be obtained in <value> with the value clause — and yes, <value> is a string. the value of the current node can also be updated to <update value> in the update-value clause; <update value> is a string too. and here's the cute part: this update is performed after <value> has been retrieved, which lets you grab the previous value in the same statement. two birds, one statement 🐦🐦

the status clause is how you get the <status> number, which is GG_ERR_EXIST if the new current node cannot be found — and in that case, the current node, <key> and <value> are all unchanged. otherwise, <status> is GG_OKAY. slay ✅

---

🔥 EXAMPLES 🔥

the following will find a value with key "999", and then iterate in the tree to find all lesser values (in descending order):

set-string k = "999"
read-tree mytree equal k status st \
    value val new-cursor cur
start-loop
    if-true st equal GG_OKAY
        @Value found is [<<print-out val>>] for key [<<print-out k>>]
        use-cursor cur get-lesser status st value val key k
    else-if
        break-loop
    end-if
end-loop

for more examples, see new-tree. 🌈

---

🌟 SEE ALSO 🌟

• Tree

delete-tree get-tree new-tree purge-tree read-tree use-cursor write-tree

See all documentation

---

and that's a wrap, bestie 🎀 this lil page was served to you on $DATE, brought to you by version $VERSION, and yes it still says GOLF(2gg) at the bottom because some things never change 💖 go forth and iterate, you absolute main character 👑