Next: , Previous: Usage, Up: Usage


2.1 Overview

This package provides two, parallel, interfaces to a tree. The first, preferred, method, is to return results from searches, etc. as node data rather than as references to nodes. This helps shield the user from the vagaries of the tree implementation, and, in most cases, is really what the user wants.

The second method deals directly with node handles. This is generally more efficient, but requires more care by the user. It also permits more specialized manipulations, such as moving nodes between trees without the need to create and destroy nodes. The routines which work with node handles generally have the string `node' in their names.

Trees are constructed with rbtree_new and are destroyed with rbtree_delete. rbtree_new is passed a comparison routine which determines how the tree will be ordered.

Nodes are created and inserted into trees with rbtree_insert. They can be removed from trees either by completely destroying them, via rbtree_destroy or rbtree_destroy_node, or by detaching them from the tree via rbtree_detach_node. The latter is useful if a node is to be moved from one tree to another. Detached nodes are themeselves destroyed with rbtree_destroy_dnode.

A tree is searched with rbtree_search, rbtree_bnd_search, rbtree_search_node, or rbtree_bnd_search_node. The first two return pointers to user data, the last two pointers to the node. The rbtree_bnd_search routines return the node or data upon success, or the nodes which bracket the data upon failure.

The minimum and maximum data can be also be determined: rbtree_min; rbtree_max; rbtree_min_node; and rbtree_max_node. The latter two return handles to the appropriate node.

Tree traversals are available in two flavors. The tree can be traversed and an action performed at the in-order traversals of nodes (rbtree_traverse or rbtree_utraverse) or at any combination of traversals (pre-order, in-order, or post-order) (rbtree_walk or rbtree_uwalk). In either case, the tree may be traversed in either ascending or descending order (in this package denoted as LEFT_TO_RIGHT or RIGHT_TO_LEFT).

Once a specific node has been identfied via rbtree_min_node, rbtree_max_node or rbtree_search_node, various manipulations are possible. It can be detached from the tree (rbtree_detach_node); you can find its predecessor or successor nodes (rbtree_next_node); its data can be retrieved and modified (rbtree_node_get_data; and rbtree_node_put_data); and you can delete it (rbtree_destroy_node);.

The number of nodes in a tree is available via rbtree_count.

Finally, two trees can be joined with rbtree_join.