NAME
tsearch, tfind, tdelete, twalk —
manipulate binary search trees
SYNOPSIS
#include <search.h>
void *
tdelete(
const
void * restrict key,
void
** restrict rootp,
int
(*compar) (const void *, const void *));
void *
tfind(
const void
*key,
const void * const
*rootp,
int (*compar)
(const void *, const void *));
void *
tsearch(
const
void *key,
void
**rootp,
int (*compar)
(const void *, const void *));
void
twalk(
const void
*root,
void (*action)
(const void *, VISIT, int));
DESCRIPTION
The
tdelete(),
tfind(),
tsearch(), and
twalk() functions manage
binary search trees based on algorithms T and D from Knuth (6.2.2). The
comparison function passed in by the user has the same style of return values
as
strcmp(3).
tfind() searches for the datum matched by the argument
key in the binary tree rooted at
rootp, returning a pointer to the datum if it is found
and NULL if it is not.
tsearch() is identical to
tfind() except
that if no match is found,
key is inserted into the tree
and a pointer to it is returned. If
rootp points to a
NULL value a new binary search tree is created.
tdelete() deletes a node from the specified binary search tree
and returns a pointer to the parent of the node to be deleted. It takes the
same arguments as
tfind() and
tsearch().
If the node to be deleted is the root of the binary search tree,
rootp will be adjusted.
twalk() walks the binary search tree rooted in
root and calls the function
action
on each node.
Action is called with three arguments: a
pointer to the current node, a value from the enum
typedef enum
{ preorder, postorder, endorder, leaf } VISIT; specifying the traversal
type, and a node level (where level zero is the root of the tree).
RETURN VALUES
The
tsearch() function returns NULL if allocation of a new
node fails (usually due to a lack of free memory).
tfind(),
tsearch(), and
tdelete() return NULL if
rootp is NULL
or the datum cannot be found.
The
twalk() function returns no value.
SEE ALSO
bsearch(3),
hsearch(3),
lsearch(3)
STANDARDS
These functions conform to
IEEE Std 1003.1-2001
(“POSIX.1”).
CAVEATS
The
IEEE Std 1003.1-2001 (“POSIX.1”)
standard does not specify what value should be returned when deleting the root
node. Since implementations vary, user of
tdelete() should
not rely on any specific behaviour. The
IEEE Std 1003.1-2008
(“POSIX.1”) revision tried to clarify the issue with the
following wording: “the
tdelete() function shall
return a pointer to the parent of the deleted node, or an unspecified non-NULL
pointer if the deleted node was the root node, or a
NULL
pointer if the node is not found”.