Hash Table

Hash Table — Hash table.

Synopsis


#include <libhrel/relation.h>


            HHashTable;
guint       (*HHashFunc)                    (gconstpointer key,
                                             gpointer user_data);
guint       (*HEqualFunc)                   (gconstpointer key1,
                                             gconstpointer key2,
                                             gpointer user_data);
gboolean    (*HHFunc)                       (gpointer key,
                                             gpointer value,
                                             gpointer user_data);
HHashTable* h_hash_table_new                (HHashFunc hash_func,
                                             gpointer hash_func_data,
                                             HEqualFunc key_equal_func,
                                             gpointer key_equal_func_data);
HHashTable* h_hash_table_new_full           (HHashFunc hash_func,
                                             gpointer hash_func_data,
                                             HEqualFunc key_equal_func,
                                             gpointer key_equal_func_data,
                                             GDestroyNotify key_destroy_func,
                                             GDestroyNotify value_destroy_func);
void        h_hash_table_destroy            (HHashTable *hash_table);
guint       h_hash_table_size               (HHashTable *hash_table);
void        h_hash_table_insert             (HHashTable *hash_table,
                                             gpointer key,
                                             gpointer value);
gboolean    h_hash_table_remove             (HHashTable *hash_table,
                                             gconstpointer key);
gpointer    h_hash_table_lookup             (HHashTable *hash_table,
                                             gconstpointer key);
void        h_hash_table_foreach            (HHashTable *hash_table,
                                             HHFunc func,
                                             gpointer user_data);

Description

HHashTable is an adaptation of GHashTable accepting additional arguments for the hash and comparison functions.

Details

HHashTable

typedef struct _HHashTable HHashTable;


HHashFunc ()

guint       (*HHashFunc)                    (gconstpointer key,
                                             gpointer user_data);

key :
user_data :
Returns :

HEqualFunc ()

guint       (*HEqualFunc)                   (gconstpointer key1,
                                             gconstpointer key2,
                                             gpointer user_data);

key1 :
key2 :
user_data :
Returns :

HHFunc ()

gboolean    (*HHFunc)                       (gpointer key,
                                             gpointer value,
                                             gpointer user_data);

key :
value :
user_data :
Returns :

h_hash_table_new ()

HHashTable* h_hash_table_new                (HHashFunc hash_func,
                                             gpointer hash_func_data,
                                             HEqualFunc key_equal_func,
                                             gpointer key_equal_func_data);

Creates a new HHashTable.

hash_func : a function to create a hash value from a key. Hash values are used to determine where keys are stored within the HHashTable data structure.
hash_func_data : user data passed to hash_func.
key_equal_func : a function to check two keys for equality. This is used when looking up keys in the HHashTable.
key_equal_func_data : user data passed to key_equal_func.
Returns : a new HHashTable.

h_hash_table_new_full ()

HHashTable* h_hash_table_new_full           (HHashFunc hash_func,
                                             gpointer hash_func_data,
                                             HEqualFunc key_equal_func,
                                             gpointer key_equal_func_data,
                                             GDestroyNotify key_destroy_func,
                                             GDestroyNotify value_destroy_func);

Creates a new HHashTable like h_hash_table_new() and allows to specify functions to free the memory allocated for the key and value that get called when removing the entry from the HHashTable.

hash_func : a function to create a hash value from a key.
hash_func_data : user data passed to hash_func.
key_equal_func : a function to check two keys for equality.
key_equal_func_data : user data passed to key_equal_func.
key_destroy_func : a function to free the memory allocated for the key used when removing the entry from the HHashTable or NULL if you don't want to supply such a function.
value_destroy_func : a function to free the memory allocated for the value used when removing the entry from the HHashTable or NULL if you don't want to supply such a function.
Returns : a new HHashTable.

h_hash_table_destroy ()

void        h_hash_table_destroy            (HHashTable *hash_table);

Destroys the HHashTable. If keys and/or values are dynamically allocated, you should either free them first or create the HHashTable using h_hash_table_new_full(). In the latter case the destroy functions you supplied will be called on all keys and values before destroying the HHashTable.

hash_table : a HHashTable.

h_hash_table_size ()

guint       h_hash_table_size               (HHashTable *hash_table);

Returns the number of elements contained in the HHashTable.

hash_table : a HHashTable.
Returns : the number of key/value pairs in the HHashTable.

h_hash_table_insert ()

void        h_hash_table_insert             (HHashTable *hash_table,
                                             gpointer key,
                                             gpointer value);

Inserts a new key and value into a HHashTable.

If the key already exists in the HHashTable its current value is replaced with the new value. If you supplied a value_destroy_func when creating the HHashTable, the old value is freed using that function. If you supplied a key_destroy_func when creating the HHashTable, the passed key is freed using that function.

hash_table : a HHashTable.
key : a key to insert.
value : the value to associate with the key.

h_hash_table_remove ()

gboolean    h_hash_table_remove             (HHashTable *hash_table,
                                             gconstpointer key);

Removes a key and its associated value from a HHashTable.

If the HHashTable was created using h_hash_table_new_full(), the key and value are freed using the supplied destroy functions, otherwise you have to make sure that any dynamically allocated values are freed yourself.

hash_table : a HHashTable.
key : the key to remove.
Returns : TRUE if the key was found and removed from the HHashTable.

h_hash_table_lookup ()

gpointer    h_hash_table_lookup             (HHashTable *hash_table,
                                             gconstpointer key);

Looks up a key in a HHashTable. Note that this function cannot distinguish between a key that is not present and one which is present and has the value NULL. If you need this distinction, use h_hash_table_lookup_extended().

hash_table : a HHashTable.
key : the key to look up.
Returns : the associated value, or NULL if the key is not found.

h_hash_table_foreach ()

void        h_hash_table_foreach            (HHashTable *hash_table,
                                             HHFunc func,
                                             gpointer user_data);

Calls the given function for each of the key/value pairs in the HHashTable. The function is passed the key and value of each pair, and the given user_data parameter. The hash table may not be modified while iterating over it (you can't add/remove items). To remove all items matching a predicate, use h_hash_table_foreach_remove().

hash_table : a HHashTable.
func : the function to call for each key/value pair.
user_data : user data to pass to the function.