TSEARCH(3)

TSEARCH(3) | Library Functions Manual | TSEARCH(3)

# 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”.

April 30, 2010 | NetBSD 9.0