cp_multimap

Section: libcprops - cp_multimap (3)
Updated: OCT 2007
Index Return to Main Contents

NAME

cp_multimap_insert, cp_multimap_remove, cp_multimap_remove_by_index - add or remove entries from a multimap

SYNOPSIS

void *cp_multimap_insert(cp_multimap *tree, void *entry, int *err);

void *cp_multimap_remove(cp_multimap *tree, void *entry);
void *cp_multimap_remove_by_index(cp_multimap *map,
cp_index *index,
void *entry);

DESCRIPTION

cp_multimap_insert adds the given entry to a multimap. On error, if err is non-null, the integer it points to is set to one of CP_LOCK_FAILED, CP_UNIQUE_INDEX_VIOLATION or CP_MEMORY_ALLOCATION_FAILURE.

cp_multimap_remove attempts to remove the item described by entry from the mapping. On success the address of the actual item removed is returned. Notice that this address may not be usable if the map has the COLLECTION_MODE_DEEP bit set.

cp_multimap_remove_by_index allows removing multiple items with a single call if index is non-unique.

RETURN VALUE

On success, cp_multimap_insert returns the item inserted to the map, which may be different than the parameter given if the map has the COLLECTION_MODE_COPY mode bit set. A NULL return value indicates an error in the insertion. In this case, if the err parameter is non-null, the integer it points to is set to CP_LOCK_FAILED on locking errors, CP_UNIQUE_INDEX_VIOLATION if a unique index would be violated by the requested insertion, or CP_MEMORY_ALLOCATION_FAILURE on allocation error.

cp_multimap_remove returns the item removed or NULL on error or if the requested item was not found.

cp_multimap_remove_by_index returns the item removed or the wrapping cp_vector for non-unique indices. A return value of NULL indicates an error or that the requested item was not found.