NAME
Blt_Tree - Tree data object.
SYNOPSIS
#include <bltTree.h>
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