RBTREE(3)               NetBSD Library Functions Manual              RBTREE(3)

NAME
     rbtree -- red-black tree

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     #include <sys/rbtree.h>

     void
     rb_tree_init(rb_tree_t *rbt, const rb_tree_ops_t *ops);

     void *
     rb_tree_insert_node(rb_tree_t *rbt, void *rb);

     void
     rb_tree_remove_node(rb_tree_t *rbt, void *rb);

     void *
     rb_tree_find_node(rb_tree_t *rbt, const void *key);

     void *
     rb_tree_find_node_geq(rb_tree_t *rbt, const void *key);

     void *
     rb_tree_find_node_leq(rb_tree_t *rbt, const void *key);

     void *
     rb_tree_iterate(rb_tree_t *rbt, void *rb, unsigned int direction);

     void *
     RB_TREE_MIN(rb_tree_t *rbt);

     void *
     RB_TREE_MAX(rb_tree_t *rbt);

     RB_TREE_FOREACH(void *rb, rb_tree_t *rbt);

     RB_TREE_FOREACH_REVERSE(void *rb, rb_tree_t *rbt);

DESCRIPTION
     rbtree provides red-black trees.  A red-black tree is a binary search
     tree with the node color as an extra attribute.  It fulfills a set of
     conditions:

           1.   Every search path from the root to a leaf consists of the same
                number of black nodes.

           2.   Each red node (except for the root) has a black parent.

           3.   Each leaf node is black.

     Every operation on a red-black tree is bounded as O(lg n).  The maximum
     height of a red-black tree is 2lg (n+1).

TYPES
     rb_tree_t
              A red-black tree.

     typedef signed int (* rbto_compare_nodes_fn)(void *context, const void
              *node1, const void *node2);
              The node-comparison function.  Defines an ordering on nodes.
              Returns a negative value if the first node node1 precedes the
              second node node2.  Returns a positive value if the first node
              node1 follows the second node node2.  Returns 0 if the first
              node node1 and the second node node2 are identical according to
              the ordering.

     typedef signed int (* rbto_compare_key_fn)(void *context, const void
              *node, const void *key);
              The node-key comparison function.  Defines the order of nodes
              and keys.  Returns a negative value if the node node precedes
              the key key.  Returns a positive value if the node node follows
              the key key.  Returns 0 if the node node is identical to the key
              key according to the ordering.

     rb_tree_ops_t
              Defines the function for comparing two nodes in the same tree,
              the function for comparing a node in the tree with a key, the
              offset of member rb_node_t within the node type, and the opaque
              context pointer passed to the comparison functions.  Members of
              rb_tree_ops_t are

                      rbto_compare_nodes_fn rbto_compare_nodes;
                      rbto_compare_key_fn rbto_compare_key;
                      size_t rbto_node_offset;
                      void *rbto_context;

     rb_node_t
              A node in a red-black tree has this structure as a member.  The
              offset of the rb_node_t member in the caller's node structure
              should be provided as rbto_node_offset.  (None of the functions
              in the rbtree interface are meant to take pointers directly to
              the rb_node_t member.)

FUNCTIONS
     rb_tree_init(rbt, ops)
              Initialize the red-black tree rbt.  Let the comparison functions
              given by ops define the order of nodes in the tree for the pur-
              poses of insertion, search, and iteration.  rb_tree_init()
              always succeeds.

     rb_tree_insert_node(rbt, rb)
              Insert the node rb into the tree rbt.  Return inserted node on
              success, already existing node on failure.

     rb_tree_remove_node(rbt, rb)
              Remove the node rb from the tree rbt.

     rb_tree_find_node(rbt, key)
              Search the tree rbt for a node exactly matching key.  If no such
              node is in the tree, return NULL.  Otherwise, return the match-
              ing node.

     rb_tree_find_node_geq(rbt, key)
              Search the tree rbt for a node that exactly matches key and
              return it.  If no such node is present, return the first node
              following key or, if no such node is in the tree, return NULL.

     rb_tree_find_node_leq(rbt, key)
              Search the tree rbt for a node that exactly matches key and
              return it.  If no such node is present, return the first node
              preceding key or, if no such node is in the tree, return NULL.

     rb_tree_iterate(rbt, rb, direction)
              If direction is RB_DIR_LEFT, return the node in the tree rbt
              immediately preceding the node rb or, if rb is NULL, return the
              first node in rbt or, if the tree is empty, return NULL.

              If direction is RB_DIR_RIGHT, return the node in the tree rbt
              immediately following the node rb or, if rb is NULL, return the
              last node in rbt or, if the tree is empty, return NULL.

     RB_TREE_MIN(rbt)
              Return the first node in rbt, i.e. the node with the least key,
              or NULL if rbt is empty.

     RB_TREE_MAX(rbt)
              Return the last node in rbt, i.e. the node with the greatest
              key, or NULL if rbt is empty.

     RB_TREE_FOREACH(rb, rbt)
              RB_TREE_FOREACH is a macro to be used in the place of a for
              header preceding a statement to traverse the nodes in rbt from
              least to greatest, assigning rb to each node in turn and execut-
              ing the statement.

     RB_TREE_FOREACH_REVERSE(rb, rbt)
              RB_TREE_FOREACH_REVERSE is a macro to be used in the place of a
              for header preceding a statement to traverse the nodes in rbt
              from greatest to least, assigning rb to each node in turn and
              executing the statement.

CODE REFERENCES
     The rbtree interface is implemented in common/lib/libc/gen/rb.c.

SEE ALSO
     queue(3), tree(3)

HISTORY
     The rbtree interface first appeared in NetBSD 6.0.

AUTHORS
     Matt Thomas <matt@NetBSD.org> wrote rbtree.

     Niels Provos <provos@citi.umich.edu> wrote the tree(3) manual page.  Por-
     tions of this page derive from that page.

NetBSD 8.0                      August 29, 2016                     NetBSD 8.0

You can also request any man page by name and (optionally) by section:

Command: 
Section: 
Architecture: 
Collection: 
 

Use the DEFAULT collection to view manual pages for third-party software.


©1994 Man-cgi 1.15, Panagiotis Christias
©1996-2017 Modified for NetBSD by Kimmo Suominen