NAME

cp_sorted_hash - an ordered hash table implementation

DESCRIPTION

cp_sorted_hash is an ordered hash table implementation. Simillarly to cp_hashlist, an iteration order is conserved, but whereas in cp_hashlist the insertion order is maintained, here the ordering is determined by a user defined comparison function. Internally a hash table is used to store mappings by key, and these mappings are held in a red-black tree structure. In effect items are indexed by one key for the hash table lookup, and by another key for the ordered access.

This requires two compare functions - one for hash table operations, as described under cp_hashtable (3), and another for ordering. The ordering function function should match the following prototype:

int compare_function(cp_mapping *n, cp_mapping *m);

cp_mapping is a wrapper defined as

typedef struct _cp_mapping
{
	void *key;
	void *value;
} cp_mapping;

The macros

void *cp_mapping_key(cp_mapping *mapping);
void *cp_mapping_value(cp_mapping *mapping);

may be used to access mapped keys and values.

As a special case, when instantiated with a NULL mapping comparison function, the ordering comparison is determined using the hash comparison function.

INTERFACE

the following is a summary of functions provided by <cprops/sorted_hash.h>.

cp_sorted_hash *cp_sorted_hash_create(cp_hashfunction hash, cp_compare_fn cmp_key, cp_mapping_cmp_fn cmp_mapping);
cp_sorted_hash * cp_sorted_hash_create_by_option(int mode, unsigned long size_hint, cp_hashfunction hash, cp_compare_fn cmp_key, cp_mapping_cmp_fn cmp_mapping, cp_copy_fn key_copy, cp_destructor_fn key_dtr, cp_copy_fn val_copy, cp_destructor_fn val_dtr);

void cp_sorted_hash_destroy(cp_sorted_hash *table);
void cp_sorted_hash_destroy_custom(cp_sorted_hash *table, cp_destructor_fn key_dtr, cp_destructor_fn val_dtr);

void *cp_sorted_hash_insert(cp_sorted_hash *table, void *key, void *value);
void *cp_sorted_hash_delete(cp_sorted_hash *table, void *key);
void *cp_sorted_hash_get(cp_sorted_hash *table, void *key);
int cp_sorted_hash_contains(cp_sorted_hash *table, void *key);

int cp_sorted_hash_callback_preorder(cp_sorted_hash *table, cp_callback_fn callback, void *prm);
int cp_sorted_hash_callback(cp_sorted_hash *table, cp_callback_fn callback, void *prm);
int cp_sorted_hash_callback_postorder(cp_sorted_hash *table, cp_callback_fn callback, void *prm);

int cp_sorted_hash_count(cp_sorted_hash *table);

int cp_sorted_hash_lock(cp_sorted_hash *table, int type);
int cp_sorted_hash_rdlock(cp_sorted_hash *table);
int cp_sorted_hash_wrlock(cp_sorted_hash *table);
int cp_sorted_hash_unlock(cp_sorted_hash *table);

int cp_sorted_hash_get_mode(cp_sorted_hash *table);
int cp_sorted_hash_set_mode(cp_sorted_hash *table, int mode);
int cp_sorted_hash_unset_mode(cp_sorted_hash *table, int mode);

SEE ALSO

cp_hashtable(3), cp_sorted_hash_create(3), cp_sorted_hash_destroy(3), cp_sorted_hash_insert(3), cp_sorted_hash_delete(3), cp_sorted_hash_callback(3), cp_sorted_hash_set_mode(3), cp_sorted_hash_lock(3), cp_sorted_hash_count(3)