struct::tree_v1(n)

✨ NAME ✨

struct::tree_v1 — no cap, this is the one that creates and manipulates tree objects 🌳💖 (it's a Tcl Data Structures page, bestie, iykyk)

---

🎀 SYNOPSIS 🎀

okay so here's the vibe check on how you actually call this thing:

package require Tcl 8.5 9

package require struct::tree ?1.2.3?

treeName option ?arg arg ...?

treeName append node ?-key key? value

treeName children node

treeName cut node

treeName delete node ?node ...?

treeName depth node

treeName destroy

treeName exists node

treeName get node ?-key key?

treeName getall node

treeName keys node

treeName keyexists node ?-key key?

treeName index node

treeName insert parent index ?child ?child ...??

treeName isleaf node

treeName lappend node ?-key key? value

treeName move parent index node ?node ...?

treeName next node

treeName numchildren node

treeName parent node

treeName previous node

treeName set node ?-key key? ?value?

treeName size ?node?

treeName splice parent from ?to? ?child?

treeName swap node1 node2

treeName unset node ?-key key?

treeName walk node ?-order order? ?-type type? -command cmd

---

💖 DESCRIPTION 💖

so the ::struct::tree command makes you a brand new tree object, and it comes with a global Tcl command attached to it whose name is treeName. that command is your girl — you use her to invoke all the various operations on the tree. general form is giving:

treeName option ?arg arg ...?

Option and the args decide the exact behavior of the command. that's it, that's the whole deal 💅

---

a tree is a collection of named elements called nodes, and one of them is special-cased as the root, plus there's a relation ("parenthood") that drops a whole hierarchical structure on top of the nodes. (shoutout Data Structures and Algorithms; Aho, Hopcroft and Ullman; Addison-Wesley, 1987 📚✨). and like, on top of just maintaining the node relationships, this tree implementation also lets you associate any number of keyed values with each node. yes, any number. go feral.

the element names can be arbitrary strings, fr fr.

so a tree is lowkey similar to an array, but with three important differences:

1. Trees are accessed through an object command, whereas arrays are accessed as variables. (this means trees cannot be local to a procedure — not me finding that out the hard way 😭)
2. Trees have a hierarchical structure, whereas an array is just an unordered collection.
3. Each node of a tree has a separate collection of attributes and values. this is like an array where every value is a dictionary. iconic behaviour honestly 👑

---

🦋 The Commands 🦋

here's every command you can throw at a tree object, bestie. buckle up.

treeName append node ?-key key? value

appends a value to one of the keyed values associated with a node. if no key is specified, the key data is assumed.

treeName children node

returns a list of the children of node. 🍼

treeName cut node

removes the node specified by node from the tree — but not its children. the children of node get made children of the parent of the node, at the index at which node was located. so the kids get adopted by grandma, basically 🫶

treeName delete node ?node ...?

removes the specified nodes from the tree. all of the nodes' children will be removed as well, to prevent orphaned nodes. (yeah, it takes the whole subtree down with it. dramatic but necessary 💀)

treeName depth node

returns the number of steps from node node to the root node.

treeName destroy

destroys the tree, including its storage space and associated command. it's giving main character exit 🌈

treeName exists node

returns true if the specified node exists in the tree.

treeName get node ?-key key?

returns the value associated with the key key for the node node. if no key is specified, the key data is assumed.

treeName getall node

returns a serialized list of key/value pairs (suitable for use with [array set]) for the node. handy for when you want the whole outfit at once ✨

treeName keys node

returns a list of keys for the node.

treeName keyexists node ?-key key?

returns true if the specified key exists for the node. if no key is specified, the key data is assumed.

treeName index node

returns the index of node in its parent's list of children. for example, if a node has nodeFoo, nodeBar, and nodeBaz as children, in that order, the index of nodeBar is 1. counting from zero, bestie, we're programmers 🧮

treeName insert parent index ?child ?child ...??

inserts one or more nodes into the tree as children of the node parent. the nodes get added in the order they're given. if parent is root, it refers to the root of the tree. the new nodes get added to the parent node's child list at the index given by index. the index can be end, in which case the new nodes will be added after the current last child. 🎀

if any of the specified children already exist in treeName, those nodes will be moved from their original location to the new location indicated by this command. glow-up relocation, honestly.

if no child is specified, a single node gets added and a name will be generated for the new node. the generated name is of the form nodex, where x is a number. if names are specified they must neither contain whitespace nor colons (":"). no spaces, no colons, periodt.

the return result from this command is a list of nodes added.

treeName isleaf node

returns true if node is a leaf of the tree (if node has no children), false otherwise. 🍃

treeName lappend node ?-key key? value

appends a value (as a list) to one of the keyed values associated with a node. if no key is specified, the key data is assumed.

treeName move parent index node ?node ...?

makes the specified nodes children of parent, inserting them into the parent's child list at the index given by index. heads up bestie: the command will take all the nodes out of the tree before inserting them under the new parent, and it determines the position to place them into after the removal, before the re-insertion. this behaviour matters a lot when you're moving one or more nodes to a different index without changing their parent node. so like, the order of operations is the whole tea here 🍵

treeName next node

returns the right sibling of node, or the empty string if node was the last child of its parent.

treeName numchildren node

returns the number of immediate children of node.

treeName parent node

returns the parent of node. 👩‍👧

treeName previous node

returns the left sibling of node, or the empty string if node was the first child of its parent.

treeName set node ?-key key? ?value?

sets or gets one of the keyed values associated with a node. if no key is specified, the key data is assumed. every node that gets added to a tree has the value "" assigned to the key data automatically. a node may have any number of keyed values associated with it. if value is not specified, this command returns the current value assigned to the key; if value is specified, this command assigns that value to the key. dual purpose queen 💅

treeName size ?node?

returns a count of the number of descendants of the node node; if no node is specified, root is assumed.

treeName splice parent from ?to? ?child?

inserts a node named child into the tree as a child of the node parent. if parent is root, it refers to the root of the tree. the new node gets added to the parent node's child list at the index given by from. the children of parent which are in the range of the indices from and to are made children of child. if the value of to is not specified it defaults to end. if no name is given for child, a name will be generated for the new node. the generated name is of the form nodex, where x is a number. the return result from this command is the name of the new node. it's giving surgical precision 🧬✨

treeName swap node1 node2

swaps the position of node1 and node2 in the tree. 🔁

treeName unset node ?-key key?

removes a keyed value from the node node. if no key is specified, the key data is assumed.

treeName walk node ?-order order? ?-type type? -command cmd

performs a breadth-first or depth-first walk of the tree starting at the node node. 🌈

the type of walk, breadth-first or depth-first, is determined by the value of type; bfs indicates breadth-first, dfs indicates depth-first. depth-first is the default.

the order of the walk, pre-, post-, both- or in-order, is determined by the value of order; pre indicates pre-order, post indicates post-order, both indicates both-order and in indicates in-order. pre-order is the default.

here's what all that actually means, bestie:

• pre-order walking means a parent node is visited before any of its children. for example, a breadth-first search starting from the root will visit the root, followed by all of the root's children, followed by all of the root's grandchildren.
• post-order walking means a parent node is visited after any of its children.
• both-order walking means a parent node is visited before and after any of its children.
• in-order walking means a parent node is visited after its first child and before the second. this is a generalization of in-order walking for binary trees and will do the right thing if a binary is walked.

⚠️ the combination of a breadth-first walk with in-order is illegal. don't do it, it's not the vibe 🚫

as the walk progresses, the command cmd will be evaluated at each node. percent substitution will be performed on cmd before evaluation, just as in a bind script. the following substitutions are recognized:

• %% — insert the literal % character.
• %t — name of the tree object.
• %n — name of the current node.
• %a — name of the action occurring; one of enter, leave, or visit. enter actions occur during pre-order walks; leave actions occur during post-order walks; visit actions occur during in-order walks. in a both-order walk, the command will be evaluated twice for each node; the action is enter for the first evaluation, and leave for the second. 🎬

🐛 BUGS, IDEAS, FEEDBACK 💌

okay bestie, real talk for a sec. this doc? and the whole package it's describing? they will undoubtedly have bugs and other problems. like, no cap, that's just how software is. it's not a flaw in the vibe, it's the vibe.

so if you find one, pls pls pls report it in the category struct :: tree of the Tcllib Trackers here: http://core.tcl.tk/tcllib/reportlist

and if you have ideas for enhancements — for the package, for the docs, for either one — those go to the same place and they are so so welcome. we want them. give them to us. 🫶

when you're proposing code changes, you gotta send unified diffs, i.e. the output of diff -u. that's the format. that's the whole thing. don't be shy about it, just do it.

also, lowkey important: attachments are strongly preferred over inlined patches. like, strongly. so how do you attach stuff? here's the move:

1. create the ticket
2. go straight to the Edit form of that ticket
3. use the left-most button in the secondary navigation bar

that's it. that's the whole ritual. ✨

---

🔑 KEYWORDS 🔑

• tree

short. sweet. iconic. 👑

---

🗂 CATEGORY 🗂

• Data structures

---

©️ COPYRIGHT ©️

Copyright (c) 2002 Andreas Kupries <andreas_kupries@users.sourceforge.net>

---

and that's the page bestie!! 🌸 this one's from tcllib, version 1.2.3, and the page itself is struct::tree_v1(n) — go forth and tree responsibly 💖🦋