cp_avltree

Section: libcprops - cp_avltree (3)
Updated: MAY 2006
Index Return to Main Contents
 

NAME

cp_avltree_insert, cp_avltree_get, cp_avltree_delete, cp_avltree_contains, cp_avltree_callback, cp_avltree_count - AVL tree operations

 

SYNOPSIS

#include <cprops/avl.h>
#include <cprops/vector.h>

void *cp_avltree_insert(cp_avltree *tree, void *key, void *value);
void *cp_avltree_get(cp_avltree *tree, void *key);
void *cp_avltree_delete(cp_avltree *tree, void *key);
int cp_avltree_contains(cp_avltree *tree, void *key);
int cp_avltree_callback(cp_avltree *tree, void *key);
long cp_avltree_count(cp_avltree *tree);

 

DESCRIPTION

cp_avltree_insert adds a mapping for the given key to the given value. If a mapping for the given key already exists and COLLECTION_MODE_MULTIPLE_VALUES is not set, the current mapping is replaced, and, if COLLECTION_MODE_DEEP is set, the old mapping key and value are destroyed. If COLLECTION_MODE_MULTIPLE_VALUES is set, the new value is added to the existing values mapped to the given key. By default COLLECTION_MODE_MULTIPLE_VALUES is not set.
If COLLECTION_MODE_COPY is set, the given key and value parameters are copied before being inserted. Unless COLLECTION_MODE_NOSYNC is set, the insert function will write-lock the tree before performing the insertion.

cp_avltree_get returns the current mapping for the requested key or NULL if none exists. Unless COLLECTION_MODE_NOSYNC is set, the tree is read-locked. If COLLECTION_MODE_MULTIPLE_VALUES is set, the returned value is a cp_vector(3) object containing all values for the given key.

cp_avltree_delete removes the current mapping for the given key and returns the value associated to it or NULL if there was no mapping for the given key. The return value is usable to indicate that a deletion has taken place. Note that the returned pointer may be invalid if COLLECTION_MODE_DEEP is set and the tree has a non-null value destructor function set. Unless COLLECTION_MODE_NOSYNC is set, the deletion function write-locks the tree.

cp_avltree_contains returns non-zero if the tree contains a mapping for the given key or zero if not.

cp_avltree_callback performs an in-order scan of the tree, invoking the given callback function with each mapping and the given parameter. The callback iteration is terminated if the callback function returns non-zero. The prototype for the callback function is as follows:

int callback_fn(void *entry, void *client_prm);

The callback function is invoked iteratively with entry pointing of the current tree node. Here is an example callback function implementation, which prints the key and value addresses for each mapping:

int callback(void *entry, void *prm)
{
        cp_avlnode *node = entry;
        printf("key %p, value %p, node->key, node->value);
        return 0;
}

cp_avltree_count returns the number of mappings currently stored in a tree.

 

RETURN VALUE

cp_avltree_insert and cp_avltree_delete return the affected value on success or NULL on failure. cp_avltree_get returns the value mapped to the requested key or NULL on failure or if no such mapping exists.

Note that these functions may fail if locking fails. This means that for a synchronized table (ie COLLECTION_MODE_NOSYNC not set), cp_avltree_get could return NULL although a mapping actually exists. Applications should check errno to determine whether no mapping was found (errno not set) or locking has failed (errno will be set to EBUSY, EINVAL or EDEADLK).

cp_avltree_contains returns non-zero if the tree contains a mapping for the requested key or zero if no mapping was found or on locking errors - see above.

cp_avltree_callback returns 0 if the iteration completes successfully, -1 on locking error, or the non-zero value returned by the callback function causing the iteration to abort.

cp_avltree_count returns the number of mappings currently stored.  

SEE ALSO

cp_avltree_lock(3), cp_avltree_set_mode(3), cp_vector(3) errno(3)


 

Index

NAME
SYNOPSIS
DESCRIPTION
RETURN VALUE
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 17:58:11 GMT, September 08, 2006
SourceForge.net Logo