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