Blt_Tree(3)

🌳 Blt_Tree — the tree data object manual, but make it cute ✨

okay bestie, so this is from the Blt Library Procedures collection, and it's literally the page for Blt_Tree, the tree data object. sit down, grab a strawberry, we're doing data structures 💖

---

✨ NAME ✨

Blt_Tree — Tree data object. that's it, that's the vibe 🌳

---

✨ SYNOPSIS ✨

#include <bltTree.h>

struct Blt_Tree {
Tcl_Alloc(size)

Tcl_Free(ptr)

char *
Tcl_Realloc(ptr, size)

(no cap, that's exactly what's in here 🫶)

---

✨ ARGUMENTS ✨

• int size (in) — the size, in bytes, of the memory block you're allocating. yeah girl, bytes 💅
• char *ptr (in) — pointer to the memory block you wanna free or realloc.

---

✨ DESCRIPTION ✨

so these procedures give you a platform-and-compiler-independent interface for memory allocation. if your program needs to hand ownership of memory blocks back and forth between Tcl and other modules, you use these routines — not the native malloc() and free() from the C run-time library. that's the whole point, bestie.

• Tcl_Alloc returns a pointer to a block of at least size bytes, suitably aligned for any use. slay.
• Tcl_Free makes the space referred to by ptr available for further allocation. giving it back to the universe 🦋
• Tcl_Realloc changes the size of the block pointed to by ptr to size bytes and returns a pointer to the new block. the contents stay unchanged up to the lesser of the new and old sizes. and heads up — the returned location may be different from ptr. so don't be clinging to the old pointer, okay? 😭

---

✨ TREE OBJECT ROUTINES ✨

these are the library routines that let you create and destroy tree objects. every tree object has a name that uniquely identifies it. tree objects can also be shared — for example, the tree and hiertable commands may access the same tree data object. 👯‍♀️

here's the deal with tokens: each client grabs a token associated with the tree, and when all the tokens are released, the tree data object is automatically destroyed. very self-cleaning, very iconic ✨

• Blt_TreeCreate — Create a tree data object and optionally obtains a token associated with it.
• Blt_TreeExists — Indicates if a tree by a given name exists.
• Blt_TreeGetToken — Obtains a token for an existing tree data object.
• Blt_TreeReleaseToken — Releases a token for a tree data object. The tree object is deleted when all outstanding tokens have been released.
• Blt_TreeName — Returns the name of the tree object.
• Blt_TreeChangeRoot — Specifies a node as the new root to a tree.

---

✨ TREENODE ROUTINES ✨

so a tree object starts out containing only a root node. you add or delete nodes with these routines:

• Blt_TreeCreateNode — Creates a new child node for a given parent in the tree.
• Blt_TreeDeleteNode — Deletes a node and its children. (yes, all of them. it's giving generational curse 💀)
• Blt_TreeNodeId — Returns the unique node identifier for a node.
• Blt_TreeGetNode — Gets a node based upon its identifier.
• Blt_TreeFindChild — Searches for a child node given by its label in a parent node.
• Blt_TreeNodeLabel — Returns the current label for a node.
• Blt_TreeRelabelNode — Resets a node's label.
• Blt_TreeNodePath — Returns the fullpath to a node.
• Blt_TreeNodeDepth — Returns the depth of the node.
• Blt_TreeNodeDegree — Returns the number of children for a node.
• Blt_TreeIsLeaf — Indicates if a node has no children.
• Blt_TreeIsBefore — Indicates if a node is before another node in depth-first search order.
• Blt_TreeIsAncestor — Indicates if a node is an ancestor or another.
• Blt_TreeSortNode — Sorts the children of a node.
• Blt_TreeSize — Returns the number of nodes in a node and its descendants.
• Blt_TreeMoveNode

not me noticing Blt_TreeMoveNode has no description here 🙈 i'm keeping it exactly as it is, bestie. no inventing, no guessing, periodt.

---

✨ NODE NAVIGATION ✨

each node can have zero or more children nodes. these routines let you navigate the tree hierarchy 🧚

• Blt_TreeNodeParent — Returns the parent node.
• Blt_TreeFirstChild — Returns the first child of a parent node.
• Blt_TreeLastChild — Returns the last child of a parent node.
• Blt_TreeNextSibling — Returns the next sibling node in the parent's list of children.
• Blt_TreePrevSibling — Returns the previous sibling node in the parent's list of children.
• Blt_TreeRootNode — Returns the root node of the tree.
• Blt_TreeNextNode — Returns the next node in depth-first order.
• Blt_TreePrevNode — Returns the previous node in depth-first order.
• Blt_TreeEndNode — Returns the last node in the tree as determined by depth-first order.
• Blt_TreeApply — Walks through a node and all it descendants, applying a given callback procedure.
• Blt_TreeApplyDFS — Walks through a node and all it descendants in depth-first search order, applying a given callback procedure.
• Blt_TreeApplyBFS — Walks through a node and all it descendants in breadth-first search order, applying a given callback procedure.

---

✨ NODE DATA VALUES ✨

data values can be stored at any node. values have by both a string key and a Tcl_Obj value. and listen — data value keys do not have to be homogenous across all nodes (i.e. nodes don't have to contain the same keys). freedom of expression, we love to see it 🌈

there's also a special node array data type, which is its own whole thing.

• Blt_TreeGetValue — Gets the node data value given by a key.
• Blt_TreeValueExists — Indicates if a node data value given by a key exists.
• Blt_TreeSetValue — Sets a node's value of a key.
• Blt_TreeUnsetValue — Remove the node data value and key.
• Blt_TreeGetArrayValue — Gets the node data array value given by a key and an array index.
• Blt_TreeSetArrayValue — Sets the node data array value given by a key and an array index.
• Blt_TreeUnsetArrayValue — Remove the node data array value.
• Blt_TreeArrayValueExists — Determines if an array element by a given index exists.
• Blt_TreeFirstKey — Returns the key of the first value in the node.
• Blt_TreeNextKey — Returns the key of the next value in the node.
• Blt_TreePrivateValue — Lock the value to current client, making it private.
• Blt_TreePublicValue — Unlock the value so that all clients can access it.
• Blt_TreeGetKey

okay so Blt_TreeGetKey also has no description in here 💀 keeping it real, keeping it faithful, keeping it exactly as written. iykyk.

---

✨ NODE TRACES ✨

• Blt_TreeCreateTrace — Sets up a trace callback to be invoked when the node value is read, set, or unset. 👀 watching your every move, respectfully
• Blt_TreeDeleteTrace — Deletes an existing trace.

---

✨ NODE EVENTS ✨

• Blt_TreeCreateEventHandler — Sets up a callback to be invoked when events (create, delete, relabel, etc) take place on a node.
• Blt_TreeDeleteEventHandler — Deletes an existing node callback.

---

✨ KEYWORDS ✨

alloc, allocation, free, malloc, memory, realloc 🎀

---

and that's the whole page, bestie! this one's from BLT version 2.5 — mwah, go build a tree, you're gonna eat 💅✨🦋