Main Page   Modules  

Red-black trees


Detailed Description

Red-black trees are a form of binary search tree. One essential feature of binary search trees is that they need to be balanced in order to be efficient. Many algorithms exist for keeping trees balanced, but among the easiest to implement is the red-black tree. In a red-black tree, every node is given a color--either red or black--and there are various rules for what color nodes can be present where in the tree. This library implements these rules, along with functions for traversing the tree in any desired tree order.

A red-black tree is represented by a caller-allocated rb_tree_t structure. This structure describes various characteristics of the tree, such as the number of nodes in the tree, and includes a pointer to the root node of the tree. Nodes may be added to the tree using rt_add() or removed from the tree using rt_remove(). Additionally, the key on a given node may be changed using the rt_move() function. Nodes may be looked up with rt_find(), and rt_iter() will execute a user-defined function for each node in the tree in the specified order. To remove all entries in the tree, simply call the rt_flush() function. If you must manually iterate through the tree, you may call the rt_next() and rt_prev() functions to determine the next or previous nodes to visit.

There are three ways to traverse a binary tree. The first, known as "preorder," visits the root node, then traverses the left subtree in preorder, then traverses the right subtree in preorder. The second, known an "inorder," traverses the left subtree in inorder, then the root node, then the right subtree in inorder. (This particular ordering retrieves the nodes in lexical order; thus its name.) The third ordering is known as "postorder"; this ordering traverses the left subtree, the right subtree, then visits the root node. To iterate over the tree in one of these orderings, simply call rt_iter() (or rt_next() or rt_prev()) with the RBT_ORDER_PRE, RBT_ORDER_IN, or RBT_ORDER_POST flags. You may OR these flags with DB_FLAG_REVERSE to reverse the traversal ordering, if you wish.

Defines

#define RB_TREE_INIT(comp, extra)
 Red-black tree static initializer.

#define rt_verify(tree)
 Red-black tree verification macro.

#define rt_frozen(tree)
 Determine if a red-black tree is frozen.

#define rt_count(tree)
 Red-black tree count.

#define rt_root(tree)
 Red-black tree root node.

#define rt_comp(tree)
 Red-black tree comparison function.

#define rt_extra(tree)
 Extra pointer data in a red-black tree.

#define RBT_ORDER_PRE
 Preorder tree traversal method.

#define RBT_ORDER_IN
 Inorder tree traversal method.

#define RBT_ORDER_POST
 Postorder tree traversal method.

#define rt_prev(tree, node_io, flags)
 Get the previous node.

#define RB_NODE_INIT(value)
 Red-black tree node static initializer.

#define rn_verify(node)
 Red-black tree node verification macro.

#define rn_color(node)
 Red-black tree node color.

#define rn_tree(node)
 Red-black tree node's tree pointer.

#define rn_parent(node)
 Red-black tree node's parent pointer.

#define rn_left(node)
 Red-black tree node's left pointer.

#define rn_right(node)
 Red-black tree node's right pointer.

#define rn_key(node)
 Red-black tree node's key pointer.

#define rn_value(node)
 Red-black tree node's value pointer.

#define rn_isblack(node)
 Test if a given node is black.

#define rn_isred(node)
 Test if a given node is red.

#define rn_isleft(node)
 Test if a given node is the left node of its parent.

#define rn_isright(node)
 Test if a given node is the right node of its parent.


Typedefs

typedef _rb_tree_s rb_tree_t
 Red-black tree.

typedef _rb_node_s rb_node_t
 Red-black tree node.

typedef unsigned long(* rb_iter_t )(rb_tree_t *, rb_node_t *, void *)
 Red-black tree iteration callback.

typedef long(* rb_comp_t )(rb_tree_t *, db_key_t *, db_key_t *)
 Red-black tree comparison callback.

typedef enum _rb_color_e rb_color_t
 Red-black tree node color.


Enumerations

enum  _rb_color_e { RB_COLOR_NONE, RB_COLOR_RED, RB_COLOR_BLACK }
 Red-black tree node color. More...


Functions

unsigned long rt_init (rb_tree_t *tree, rb_comp_t comp, void *extra)
 Dynamically initialize a red-black tree.

unsigned long rt_add (rb_tree_t *tree, rb_node_t *node, db_key_t *key)
 Add a node to a red-black tree.

unsigned long rt_move (rb_tree_t *tree, rb_node_t *node, db_key_t *key)
 Move a node in a red-black tree.

unsigned long rt_remove (rb_tree_t *tree, rb_node_t *node)
 Remove a node from a red-black tree.

unsigned long rt_find (rb_tree_t *tree, rb_node_t **node_p, db_key_t *key)
 Find an entry in a red-black table.

unsigned long rt_next (rb_tree_t *tree, rb_node_t **node_io, unsigned long flags)
 Get the next node.

unsigned long rt_iter (rb_tree_t *tree, rb_node_t *start, rb_iter_t iter_func, void *extra, unsigned long flags)
 Iterate over each entry in a red-black tree.

unsigned long rt_flush (rb_tree_t *tree, rb_iter_t flush_func, void *extra)
 Flush a red-black tree.

unsigned long rn_init (rb_node_t *node, void *value)
 Dynamically initialize a red-black tree node.


Define Documentation

#define RB_NODE_INIT value   
 

This macro statically initializes a rb_node_t.

Parameters:
value  A pointer to void representing the object associated with the node.

#define RB_TREE_INIT comp,
extra   
 

This macro statically initializes a rb_tree_t.

Parameters:
comp  A rb_comp_t function pointer for a comparison function.
extra  Extra pointer data that should be associated with the red-black tree.

#define RBT_ORDER_IN
 

If this flag is passed to rt_iter(), an inorder iteration will be performed.

#define RBT_ORDER_POST
 

If this flag is passed to rt_iter(), a postorder iteration will be performed.

#define RBT_ORDER_PRE
 

If this flag is passed to rt_iter(), a preorder iteration will be performed.

#define rn_color node   
 

This macro retrieves the color of the node.

Parameters:
node  A pointer to a rb_node_t.
Returns:
A rb_color_t value expressing the color of the node.

#define rn_isblack node   
 

This macro safely tests whether a given red-black tree node is black.

Warning:
This macro may evaluate the node argument twice.
Parameters:
node  A pointer to a rb_node_t.
Returns:
Boolean true if node is black or false otherwise.

#define rn_isleft node   
 

This macro safely tests whether a given red-black tree node is the left node of its parent.

Warning:
This macro may evaluate the node argument three times.
Parameters:
node  A pointer to a rb_node_t.
Returns:
Boolean true if node is the left node of its parent or false otherwise.

#define rn_isred node   
 

This macro safely tests whether a given red-black tree node is red.

Warning:
This macro may evaluate the node argument twice.
Parameters:
node  A pointer to a rb_node_t.
Returns:
Boolean true if node is red or false otherwise.

#define rn_isright node   
 

This macro safely tests whether a given red-black tree node is the right node of its parent.

Warning:
This macro may evaluate the node argument three times.
Parameters:
node  A pointer to a rb_node_t.
Returns:
Boolean true if node is the right node of its parent or false otherwise.

#define rn_key node   
 

This macro retrieves the key associated with the red-black tree node.

Parameters:
node  A pointer to a rb_node_t.
Returns:
A pointer to a db_key_t.

#define rn_left node   
 

This macro retrieves a pointer to the node's left node.

Parameters:
node  A pointer to a rb_node_t.
Returns:
A pointer to a rb_node_t representing the left node of the given node.

#define rn_parent node   
 

This macro retrieves a pointer to the node's parent node.

Parameters:
node  A pointer to a rb_node_t.
Returns:
A pointer to a rb_node_t representing the parent of the given node.

#define rn_right node   
 

This macro retrieves a pointer to the node's right node.

Parameters:
node  A pointer to a rb_node_t.
Returns:
A pointer to a rb_node_t representing the right node of the given node.

#define rn_tree node   
 

This macro retrieves a pointer to the red-black tree the node is in.

Parameters:
node  A pointer to a rb_node_t.
Returns:
A pointer to a rb_tree_t.

#define rn_value node   
 

This macro retrieves the value associated with the red-black tree's node. It may be treated as an lvalue to change that value. Care should be taken when using this option.

Parameters:
node  A pointer to a rb_node_t.
Returns:
A pointer to void representing the value associated with this node.

#define rn_verify node   
 

This macro verifies that a given pointer actually does point to a red-black tree node.

Warning:
This macro may evaluate the node argument twice.
Parameters:
node  A pointer to a rb_node_t.
Returns:
Boolean true if entry is a valid red-black tree node or false otherwise.

#define rt_comp tree   
 

This macro retrieves the comparison function pointer.

Parameters:
tree  A pointer to a rb_tree_t.
Returns:
A rb_comp_t.

#define rt_count tree   
 

This macro retrieves the total number of items actually in the red-black tree.

Parameters:
tree  A pointer to a rb_tree_t.
Returns:
An unsigned long containing a count of the number of items in the red-black tree.

#define rt_extra tree   
 

This macro retrieves the extra pointer data associated with a particular red-black tree.

Parameters:
tree  A pointer to a rb_tree_t.
Returns:
A pointer to void.

#define rt_frozen tree   
 

This macro returns a non-zero value if the tree is currently frozen. The red-black tree may be frozen if there is an iteration in progress.

Parameters:
tree  A pointer to a rb_tree_t.
Returns:
A zero value if the table is not frozen or a non-zero value if the table is frozen.

#define rt_prev tree,
node_io,
flags   
 

Obtains the previous node in the given iteration scheme. See rt_next() for more information.

#define rt_root tree   
 

This macro retrieves the root node of the tree.

Parameters:
tree  A pointer to a rb_tree_t.
Returns:
A pointer to a rb_node_t.

#define rt_verify tree   
 

This macro verifies that a given pointer actually does point to a red-black tree.

Warning:
This macro may evaluate the tree argument twice.
Parameters:
tree  A pointer to a rb_tree_t.
Returns:
Boolean true if tree is a valid red-black tree or false otherwise.


Typedef Documentation

typedef enum _rb_color_e rb_color_t
 

See the documentation for the enumeration _rb_color_e.

typedef long(* rb_comp_t)(rb_tree_t *, db_key_t *, db_key_t *)
 

This function pointer references a callback used to compare nodes in a red-black tree. It should return 0 for identical entries, less than 0 if the first key is less than the second, or greater than 0 if the first key is greater than the second.

typedef unsigned long(* rb_iter_t)(rb_tree_t *, rb_node_t *, void *)
 

This function pointer references a callback used by rb_iter() and rb_flush(). It should return 0 for success. A non-zero return value will terminate the operation and will become the return value of the call.

typedef struct _rb_node_s rb_node_t
 

This structure represents a single node in a red-black tree.

typedef struct _rb_tree_s rb_tree_t
 

This structure is the basis of all red-black trees maintained by this library.


Enumeration Type Documentation

enum _rb_color_e
 

This enumeration is used to specify the color of a node of a red-black tree.

Enumeration values:
RB_COLOR_NONE  Node is uncolored as of yet.
RB_COLOR_RED  Node is red.
RB_COLOR_BLACK  Node is black.


Function Documentation

unsigned long rn_init rb_node_t   node,
void *    value
 

This function dynamically initializes a red-black tree node.

Parameters:
node  A pointer to a rb_tree_t to be initialized.
value  A pointer to void which will be the value of the red-black tree entry.
Return values:
DB_ERR_BADARGS  A NULL pointer was passed for node.

unsigned long rt_add rb_tree_t   tree,
rb_node_t   node,
db_key_t   key
 

This function adds a node to a red-black tree.

Parameters:
tree  A pointer to a rb_tree_t.
node  A pointer to a rb_node_t to be added to the tree.
key  A pointer to a db_key_t containing the key for the node.
Return values:
DB_ERR_BADARGS  An invalid argument was given.
DB_ERR_BUSY  The node is already in a tree.
DB_ERR_FROZEN  The tree is currently frozen.
DB_ERR_DUPLICATE  The entry is a duplicate of an existing node.

unsigned long rt_find rb_tree_t   tree,
rb_node_t **    node_p,
db_key_t   key
 

This function looks up an entry matching the given key.

Parameters:
tree  A pointer to a rb_tree_t.
node_p  A pointer to a pointer to a rb_node_t. This is a result parameter. If NULL is passed, the lookup will be performed and an appropriate error code returned.
key  A pointer to a db_key_t describing the item to find.
Return values:
DB_ERR_BADARGS  An argument was invalid.
DB_ERR_NOENTRY  No matching entry was found.

unsigned long rt_flush rb_tree_t   tree,
rb_iter_t    flush_func,
void *    extra
 

This function flushes a red-black tree--that is, it removes each node from the tree. If a flush_func is specified, it will be called on the node after it has been removed from the tree, and may safely call free().

Parameters:
tree  A pointer to a rb_tree_t.
flush_func  A pointer to a callback function used to perform user-specified actions on a node after removing it from the tree. May be NULL. See the documentation for rb_iter_t for more information.
extra  A void pointer that will be passed to flush_func.
Return values:
DB_ERR_BADARGS  An argument was invalid.
DB_ERR_FROZEN  The red-black tree is frozen.

unsigned long rt_init rb_tree_t   tree,
rb_comp_t    comp,
void *    extra
 

This function dynamically initializes a red-black tree.

Parameters:
tree  A pointer to a rb_tree_t to be initialized.
comp  A rb_comp_t function pointer for a comparison function.
extra  Extra pointer data that should be associated with the tree.
Return values:
DB_ERR_BADARGS  An invalid argument was given.

unsigned long rt_iter rb_tree_t   tree,
rb_node_t   start,
rb_iter_t    iter_func,
void *    extra,
unsigned long    flags
 

This function iterates over every node in a red-black tree in the given traversal order, executing the given iter_func on each node.

Parameters:
tree  A pointer to a rb_tree_t.
start  A pointer to a rb_node_t describing where in the tree to start. If NULL is passed, the first element of the tree for the specified order will be assumed.
iter_func  A pointer to a callback function used to perform user-specified actions on a node in the red-black tree. NULL is an invalid value. See the documentation for rb_iter_t for more information.
extra  A void pointer that will be passed to iter_func.
flags  One of RBT_ORDER_PRE, RBT_ORDER_IN, or RBT_ORDER_POST, possibly ORed with DB_FLAG_REVERSE to reverse the order of iteration. Zero is not allowed.
Return values:
DB_ERR_BADARGS  An argument was invalid.
DB_ERR_WRONGTABLE  start is not in this red-black tree.

unsigned long rt_move rb_tree_t   tree,
rb_node_t   node,
db_key_t   key
 

This function moves an existing node in the red-black tree to correspond to the new key.

Parameters:
tree  A pointer to a rb_tree_t.
node  A pointer to a rb_node_t to be moved. It must already be in the red-black tree.
key  A pointer to a db_key_t describing the new key for the node.
Return values:
DB_ERR_BADARGS  An invalid argument was given.
DB_ERR_UNUSED  Node is not in a red-black tree.
DB_ERR_WRONGTABLE  Node is not in this tree.
DB_ERR_FROZEN  Red-black tree is frozen.
DB_ERR_DUPLICATE  New key is a duplicate of an existing key.
DB_ERR_READDFAILED  Unable to re-add node to tree.

unsigned long rt_next rb_tree_t   tree,
rb_node_t **    node_io,
unsigned long    flags
 

This function obtains the next node in the given iteration scheme. The node_io parameter is a value-result parameter--if the node pointer to which it points is NULL, the first node for the given iteration order will be loaded; otherwise, the next node in the given iteration order will be loaded.

Parameters:
tree  A pointer to a rb_tree_t.
node_io  A pointer to a pointer to a rb_node_t. If the pointer to which node_io points is NULL, the first node will be loaded, otherwise the next node will be loaded.
flags  One of RBT_ORDER_PRE, RBT_ORDER_IN, or RBT_ORDER_POST, possibly ORed with DB_FLAG_REVERSE to reverse the order of iteration. Zero is not allowed.
Return values:
DB_ERR_BADARGS  An argument was invalid.
DB_ERR_WRONGTABLE  start is not in this red-black tree.

unsigned long rt_remove rb_tree_t   tree,
rb_node_t   node
 

This function removes the given node from the specified red-black tree.

Parameters:
tree  A pointer to a rb_tree_t.
node  A pointer to a rb_node_t to be removed from the tree.
Return values:
DB_ERR_BADARGS  An invalid argument was given.
DB_ERR_UNUSED  Node is not in a red-black tree.
DB_ERR_WRONGTABLE  Node is not in this tree.
DB_ERR_FROZEN  Red-black tree is frozen.


Generated on Thu Dec 11 01:24:36 2003 for Database Primitives Library by doxygen1.2.18