GOLF(2gg)

🎀 GOLF(2gg) — read-tree 💅

okay bestie, this is read-tree from the 2gg manual, sitting pretty in the Development section ✨

---

✨ NAME ✨

read-tree — (tree)

---

🦋 PURPOSE 🦋

Search/update a tree. That's it, that's the whole vibe. 🔍

---

💖 SYNTAX 💖

read-tree <tree> \
    ( equal <search key> | lesser <search key> | greater <search key> | \
        lesser-equal <search key> | greater-equal <search key> | \
        min-key | max-key ) \
    [ value <value> ] \
    [ update-value <update value> ] \
    [ key <key> ] \
    [ status <status> ] \
    [ new-cursor <cursor> ]

---

🌸 DESCRIPTION 🌸

So read-tree goes digging through <tree> (which you made earlier with new-tree, obvi) looking for a node whose string key is:

• equal to <search key> — that's the "equal" clause 💅
• lesser than <search key> — "lesser" clause
• greater than <search key> — "greater" clause
• lesser or equal than <search key> — "lesser-equal" clause
• greater or equal than <search key> — "greater-equal" clause
• a minimum key in the tree — "min-key" clause 👑
• a maximum key in the tree — "max-key" clause ✨

The <status> in the "status" clause is gonna be GG_OKAY if a key matching one of those criteria gets found, and GG_ERR_EXIST if it doesn't. 😭

If a key is found, you can grab the value attached to it with the "value" clause into <value>. And the existing key that was originally used to insert that value into the tree? You get that with the "key" clause, into the string <key>. But if no key is found, both <value> and <key> stay exactly how they were. Unchanged. Untouched. Periodt. 💀

You can also update the value tied to a found key with the "update-value" clause — just hand it the <update value> string. Important: this update happens after <value> has already been retrieved, so you can snag the previous value in the same statement. Iconic, honestly. 🫶

If you wanna iterate the ordered list of keys in a tree, make a <cursor> with the "new-cursor" clause — and in that case <cursor> gets positioned on the found tree node. Go read use-cursor for more on living your cursor life. Cursors are lowkey the moment for range searches: typically you find a key that's an upper or lower bound of a range, then keep iterating to a lesser or greater value until some criteria is met, like when you hit the opposite bound. Golf trees are by default constructed so those iterations are O(1) in complexity — meaning each one is a single tree node access. No cap. (see new-tree) 🔥

---

🌈 EXAMPLES 🌈

In this example, a million key/value pairs get inserted into a tree, and then every single one of them is searched for and displayed right back (see write-tree for more on inserting into a tree). Both the key and the data here are a numerical value of a key:

%% /tree-example public

    new-tree mytree key-as "positive integer" // create new tree

    set-number i
    start-loop use i start-with 0 repeat 1000000
        number-string i to key
        set-string data=key
        write-tree mytree key (key) value data // insert key/data to the tree
    end-loop

    start-loop use i start-with 0 repeat 1000000
        number-string i to key
        // search tree for each key previously inserted
        read-tree mytree equal (key) status st value data
        if-true st not-equal GG_OKAY
            @Could not find key <<print-out key>>
        else-if
            @Found data <<print-out data>> associated with key <<print-out key>>
        end-if
        delete-string key
    end-loop
%%

---

🧚 SEE ALSO 🧚

• Tree
• delete-tree get-tree new-tree purge-tree read-tree use-cursor write-tree
• See all documentation

---

k bye bestie, that's the whole page 💜 this one's from $VERSION, dated $DATE — GOLF(2gg) and proud, mwah 💅✨