void *cp_hashlist_get(cp_hashlist *list, void *key);
void *cp_hashlist_get_head(cp_hashlist *list);
void *cp_hashlist_get_tail(cp_hashlist *list);
cp_hashlist_get looks up the value stored under key. If COLLECTION_MODE_MULTIPLE_VALUES is set, a cp_list containing all matches for the requested key is returned. Unless COLLECTION_MODE_LIST_ORDER is set, the items in the result list are ordered by insertion order rather than the order in which they appear in the list, since this ordering is typically much faster.
The result list is created with the same mode and the same copy and
finalization functions as list. This can easily lead to unwanted
results - for example, if
is set but
isn't, or vice versa. Assume an application where the finalization functions
for the master list release the memory associated with entry values. In the
first case, the finalization functions for the matching entries will be called
when the result list is released, leaving pointers to unallocated memory in the
master list. Furthermore, if the application attempts to release the master
list, the finalization functions are called to release the same memory again.
In the other case, items are duplicated and not necessarily released, thereby creating a memory leak. Other interesting phenomena may emerge in a multithreaded environment as a result of the common synchronization of result list and master list. With hashlists, COLLECTION_MODE_MULTIPLE_VALUES should be used with utmost caution and only if necessary.
This document was created by
using the manual pages.
Time: 18:37:21 GMT, December 27, 2005