Synopsis
KitHash;
uint32_t (*KitHashFunc) (const void *key);
kit_bool_t (*KitEqualFunc) (const void *key1,
const void *key2);
void (*KitFreeFunc) (void *p);
void* (*KitCopyFunc) (const void *p);
kit_bool_t (*KitHashForeachFunc) (KitHash *hash,
void *key,
void *value,
void *user_data);
KitHash* kit_hash_new (KitHashFunc hash_func,
KitEqualFunc key_equal_func,
KitCopyFunc key_copy_func,
KitCopyFunc value_copy_func,
KitFreeFunc key_destroy_func,
KitFreeFunc value_destroy_func);
KitHash* kit_hash_ref (KitHash *hash);
void kit_hash_unref (KitHash *hash);
kit_bool_t kit_hash_insert (KitHash *hash,
void *key,
void *value);
void* kit_hash_lookup (KitHash *hash,
void *key,
kit_bool_t *found);
kit_bool_t kit_hash_foreach (KitHash *hash,
KitHashForeachFunc cb,
void *user_data);
size_t kit_hash_foreach_remove (KitHash *hash,
KitHashForeachFunc cb,
void *user_data);
uint32_t kit_hash_direct_hash_func (const void *key);
kit_bool_t kit_hash_direct_equal_func (const void *v1,
const void *v2);
uint32_t kit_hash_str_hash_func (const void *key);
kit_bool_t kit_hash_str_equal_func (const void *v1,
const void *v2);
void* kit_hash_str_copy (const void *p);
Details
KitHash
typedef struct _KitHash KitHash;
The KitHash structure not be accessed directly.
KitHashFunc ()
uint32_t (*KitHashFunc) (const void *key);
The function is passed a key and should return a hash value. The functions kit_hash_direct_hash_func() and kit_hash_str_hash_func() provide hash functions which can be used when the key is a pointer and an char* respectively.
key : | a key |
Returns : | the hash value corresponding to the key |
KitEqualFunc ()
kit_bool_t (*KitEqualFunc) (const void *key1,
const void *key2);
Determines if two keys are equal. The functions kit_hash_direct_equal_func() and kit_hash_str_equal_func() provide equality functions which can be used when the key is a pointer and an char* respectively.
key1 : | first key |
key2 : | second key |
Returns : | TRUE iff the keys are equal |
KitFreeFunc ()
void (*KitFreeFunc) (void *p);
Specifies the type of function which is called when a data element is destroyed. It is passed the pointer to the data element and should free any memory and resources allocated for it. The function p_free() or any of the object unref functions can be passed here.
KitCopyFunc ()
void* (*KitCopyFunc) (const void *p);
Specifies the type of function which is called when a data element is to be cloned or reffed. It is passed the pointer to the data element and should return a new pointer to a reffed or cloned object. The function kit_hash_str_copy() or any of the object ref functions can be passed here.
p : | pointer |
Returns : | A copy or ref of the object in question |
KitHashForeachFunc ()
kit_bool_t (*KitHashForeachFunc) (KitHash *hash,
void *key,
void *value,
void *user_data);
Type signature for callback function used in kit_hash_foreach().
hash : | the hash table |
key : | key |
value : | value |
user_data : | user data passed to kit_hash_foreach() |
Returns : | Return TRUE to short-circuit, e.g. stop the iteration. |
kit_hash_new ()
KitHash* kit_hash_new (KitHashFunc hash_func,
KitEqualFunc key_equal_func,
KitCopyFunc key_copy_func,
KitCopyFunc value_copy_func,
KitFreeFunc key_destroy_func,
KitFreeFunc value_destroy_func);
Creates a new Hash Table.
hash_func : | The hash function to use |
key_equal_func : | The function used to determine key equality |
key_copy_func : | Function for copying keys or NULL |
value_copy_func : | Function for copying values or NULL |
key_destroy_func : | Function for freeing keys or NULL |
value_destroy_func : | Function for freeing values or NULL |
Returns : | The new hash table. Returns NULL on OOM. |
kit_hash_ref ()
KitHash* kit_hash_ref (KitHash *hash);
Increase reference count.
hash : | the hash table |
Returns : | the hash table |
kit_hash_unref ()
void kit_hash_unref (KitHash *hash);
Decrease reference count. If reference count drop to zero the hash table is freed.
kit_hash_insert ()
kit_bool_t kit_hash_insert (KitHash *hash,
void *key,
void *value);
Inserts a new key and value into a hash table. If the key already exists in the hash table it's current value is replaced with the new value.
hash : | the hash table |
key : | key to insert |
value : | value to insert |
Returns : | TRUE unless OOM |
kit_hash_lookup ()
void* kit_hash_lookup (KitHash *hash,
void *key,
kit_bool_t *found);
Look up a value in the hash table.
hash : | the hash table |
key : | key to look up |
found : | if not NULL, will return TRUE only if the key was found in the hash table |
Returns : | the value; caller shall not free/unref this value |
kit_hash_foreach ()
kit_bool_t kit_hash_foreach (KitHash *hash,
KitHashForeachFunc cb,
void *user_data);
Iterate over all elements in a hash table
hash : | the hash table |
cb : | callback function |
user_data : | user data |
Returns : | TRUE only if the callback short-circuited the iteration |
kit_hash_foreach_remove ()
size_t kit_hash_foreach_remove (KitHash *hash,
KitHashForeachFunc cb,
void *user_data);
Iterate over all elements in a hash table. If cb returns TRUE, the element will be removed.
hash : | the hash table |
cb : | callback function |
user_data : | user data |
Returns : | Number of key/value pairs removed |
kit_hash_direct_hash_func ()
uint32_t kit_hash_direct_hash_func (const void *key);
Converts a pointer to a hash value.
key : | the key |
Returns : | a hash value corresponding to the key |
kit_hash_direct_equal_func ()
kit_bool_t kit_hash_direct_equal_func (const void *v1,
const void *v2);
Compares two pointers and return TRUE if they are equal (same address).
v1 : | first value |
v2 : | second value |
Returns : | TRUE only if the values are equal |
kit_hash_str_hash_func ()
uint32_t kit_hash_str_hash_func (const void *key);
Converts a string to a hash value.
key : | the key |
Returns : | a hash value corresponding to the key |
kit_hash_str_equal_func ()
kit_bool_t kit_hash_str_equal_func (const void *v1,
const void *v2);
Compares two strings and return TRUE if they are equal.
v1 : | first value |
v2 : | second value |
Returns : | TRUE only if the values are equal |
kit_hash_str_copy ()
void* kit_hash_str_copy (const*p);
Similar to kit_strdup() except for types.
p : | void pointer to string |
Returns : | a void pointer to a copy or NULL on OOM |
