--- name: "Blt_Tree" section: "3" platform: "linux" package: "blt-dev" version: "2.5.3+dfsg-8" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Blt_Tree" --- # Blt\_Tree(3) Tree data object. ``` ``` ## NAME Blt\_Tree - Tree data object. ## SYNOPSIS ``` #include struct Blt_Tree { Tcl_Alloc(size) Tcl_Free(ptr) char * Tcl_Realloc(ptr, size) ``` ## ARGUMENTS - int *size* (in) Size in bytes of the memory block to allocate. - char *\*ptr* (in) Pointer to memory block to free or realloc. ``` ``` ## DESCRIPTION These procedures provide a platform and compiler independent interface for memory allocation. Programs that need to transfer ownership of memory blocks between Tcl and other modules should use these routines rather than the native **malloc()** and **free()** routines provided by the C run-time library. **Tcl\_Alloc** returns a pointer to a block of at least *size* bytes suitably aligned for any use. **Tcl\_Free** makes the space referred to by *ptr* available for further allocation. **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 will be unchanged up to the lesser of the new and old sizes. The returned location may be different from *ptr*. ## TREE OBJECT ROUTINES The following library routines allow you to create and destroy tree objects. Each 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. Each client grabs a token associated with the tree. When all tokens are released the tree data object is automatically destroyed. - **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 Tree objects initially contain only a root node. You can add or delete nodes with the following routines. - **Blt\_TreeCreateNode** Creates a new child node for a given parent in the tree. - **Blt\_TreeDeleteNode** Deletes a node and its children. - **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** ## 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. Data value keys do not have to be homogenous across all nodes (i.e. nodes do not have to contain the same keys). There is also a special node array data type. - **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** ## NODE TRACES - **Blt\_TreeCreateTrace** Sets up a trace callback to be invoked when the node value is read, set, or unset. - **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