Blt_TreeDeleteNode(3)

📦 version 2.5.3, in debian bookworm, debian trixie, nixpkgs unstable, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 Blt_TreeDeleteNode — the "bye bestie, take your whole family with you" procedure 💖

okay so this is a page from the BLT Library Procedures manual, and the star of the show is Blt_TreeDeleteNode(3). sit down, grab a strawberry 🍓, and let's get into it.

✨ NAME ✨

Blt_TreeDeleteNode — deletes a node and its descendants. not just the node. the whole bloodline. 💀

🌸 SYNOPSIS 🌸

#include <bltTree.h>

Blt_TreeNode
Blt_TreeDeleteNode(tree, node)

🎀 ARGUMENTS 🎀

  • Blt_Tree tree (in) — the tree containing the node. your tree. the one you're about to do surgery on.
  • Blt_TreeNode node (in) — the node to be deleted. the target. 👑

💅 DESCRIPTION 💅

so what does it actually do? this procedure deletes a given node and all its descendants from a tree data object. it's giving spring cleaning. it's giving "we're not doing that branch of the family tree anymore." ✨

the arguments, one by one:

  • tree — the tree containing the parent node.
  • node — node to be deleted. the node and its descendant nodes are deleted. and not just the nodes themselves — each node's data values get deleted too. also, the reference count of the Tcl_Obj is decremented. yes, it's thorough. it's an overachiever. we love that for it. 💖
⚠️ important caveat bestie: since all tree objects must contain at least a root node, the root node itself can't be deleted unless the tree is released and destroyed. so here's the tea — you can clear a tree by deleting its root, but the root node will remain until the tree is destroyed. it's not ghosting you, it literally cannot leave. 😭

🔥 RETURNS 🔥

always returns TCL_OK. always. no drama, no surprises.

but heads up: errors generated in notification callbacks are backgrounded (see Tcl_TreeCreateNotifyHandler). so like, the drama happens off-screen. 👀

🦋 EXAMPLE 🦋

the following example deletes the root node:

Blt_TreeNode root;

root = Blt_TreeRootNode(token);
Blt_TreeDeleteNode(token, root);

iconic. short. efficient. ate and left no crumbs. 💅

🌈 NOTIFICATIONS 🌈

Blt_TreeDeleteNode can trigger tree notify events. you can be notified whenever a node is deleted by using the Blt_TreeCreateNotifyHandler. a callback routine is registered that will be automatically invoked whenever a node is deleted via Blt_TreeDeleteNode to the tree. so basically you get a little ping every time something gets yeeted. 🔔 main character energy fr fr.

⭐ KEYWORDS ⭐

tree, token

and that's the whole page, bestie. no cap, every single detail is still in there — we just made it cute. this was BLT 2.5, and the page you're reading is Blt_TreeDeleteNode(3) from the BLT Library Procedures manual. mwah. 🫶💖✨

📦 where this page comes from