| <!-- ##### SECTION Title ##### --> |
| Hash Tables |
| |
| <!-- ##### SECTION Short_Description ##### --> |
| associations between keys and values so that given a key the value |
| can be found quickly. |
| |
| <!-- ##### SECTION Long_Description ##### --> |
| <para> |
| A #GHashTable provides associations between keys and values which |
| is optimized so that given a key, the associated value can be found |
| very quickly. |
| </para> |
| <para> |
| Note that neither keys nor values are copied when inserted into the |
| #GHashTable, so they must exist for the lifetime of the #GHashTable. |
| This means that the use of static strings is OK, but temporary |
| strings (i.e. those created in buffers and those returned by GTK+ widgets) |
| should be copied with g_strdup() before being inserted. |
| </para> |
| <para> |
| If keys or values are dynamically allocated, you must be careful to ensure |
| that they are freed when they are removed from the #GHashTable, and also |
| when they are overwritten by new insertions into the #GHashTable. |
| It is also not advisable to mix static strings and dynamically-allocated |
| strings in a #GHashTable, because it then becomes difficult to determine |
| whether the string should be freed. |
| </para> |
| <para> |
| To create a #GHashTable, use g_hash_table_new(). |
| </para> |
| <para> |
| To insert a key and value into a #GHashTable, use g_hash_table_insert(). |
| </para> |
| <para> |
| To lookup a value corresponding to a given key, use g_hash_table_lookup() |
| and g_hash_table_lookup_extended(). |
| </para> |
| <para> |
| To remove a key and value, use g_hash_table_remove(). |
| </para> |
| <para> |
| To call a function for each key and value pair use g_hash_table_foreach(). |
| </para> |
| <para> |
| To destroy a #GHashTable use g_hash_table_destroy(). |
| </para> |
| |
| <!-- ##### SECTION See_Also ##### --> |
| <para> |
| |
| </para> |
| |
| <!-- ##### STRUCT GHashTable ##### --> |
| <para> |
| The <structname>GHashTable</structname> struct is an opaque data structure to represent a |
| <link linkend="glib-Hash-Tables">Hash Table</link>. |
| It should only be accessed via the following functions. |
| </para> |
| |
| |
| <!-- ##### FUNCTION g_hash_table_new ##### --> |
| <para> |
| |
| </para> |
| |
| @hash_func: |
| @key_equal_func: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_hash_table_new_full ##### --> |
| <para> |
| |
| </para> |
| |
| @hash_func: |
| @key_equal_func: |
| @key_destroy_func: |
| @value_destroy_func: |
| @Returns: |
| |
| |
| <!-- ##### USER_FUNCTION GHashFunc ##### --> |
| <para> |
| Specifies the type of the hash function which is passed to |
| g_hash_table_new() when a #GHashTable is created. |
| </para> |
| <para> |
| The function is passed a key and should return a #guint hash value. |
| The functions g_direct_hash(), g_int_hash() and g_str_hash() provide |
| hash functions which can be used when the key is a #gpointer, #gint, and |
| #gchar* respectively. |
| </para> |
| <para> |
| FIXME: Need more here. |
| The hash values should be evenly distributed over a fairly large range? |
| The modulus is taken with the hash table size (a prime number) |
| to find the 'bucket' to place each key into. |
| The function should also be very fast, since it is called for each key |
| lookup. |
| </para> |
| |
| @key: a key. |
| @Returns: the hash value corresponding to the key. |
| |
| |
| <!-- ##### USER_FUNCTION GEqualFunc ##### --> |
| <para> |
| Specifies the type of a function used to test two values for |
| equality. The function should return %TRUE if both values are equal and |
| %FALSE otherwise. |
| </para> |
| |
| @a: a value. |
| @b: a value to compare with. |
| @Returns: %TRUE if @a = @b; %FALSE otherwise. |
| |
| |
| <!-- ##### FUNCTION g_hash_table_insert ##### --> |
| <para> |
| |
| </para> |
| |
| @hash_table: |
| @key: |
| @value: |
| |
| |
| <!-- ##### FUNCTION g_hash_table_replace ##### --> |
| <para> |
| |
| </para> |
| |
| @hash_table: |
| @key: |
| @value: |
| |
| |
| <!-- ##### FUNCTION g_hash_table_size ##### --> |
| <para> |
| |
| </para> |
| |
| @hash_table: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_hash_table_lookup ##### --> |
| <para> |
| |
| </para> |
| |
| @hash_table: |
| @key: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_hash_table_lookup_extended ##### --> |
| <para> |
| |
| </para> |
| |
| @hash_table: |
| @lookup_key: |
| @orig_key: |
| @value: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_hash_table_foreach ##### --> |
| <para> |
| |
| </para> |
| |
| @hash_table: |
| @func: |
| @user_data: |
| |
| |
| <!-- ##### FUNCTION g_hash_table_find ##### --> |
| <para> |
| |
| </para> |
| |
| @hash_table: |
| @predicate: |
| @user_data: |
| @Returns: |
| |
| |
| <!-- ##### USER_FUNCTION GHFunc ##### --> |
| <para> |
| Specifies the type of the function passed to g_hash_table_foreach(). |
| It is called with each key/value pair, together with the @user_data parameter |
| which is passed to g_hash_table_foreach(). |
| </para> |
| |
| @key: a key. |
| @value: the value corresponding to the key. |
| @user_data: user data passed to g_hash_table_foreach(). |
| |
| |
| <!-- ##### FUNCTION g_hash_table_remove ##### --> |
| <para> |
| |
| </para> |
| |
| @hash_table: |
| @key: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_hash_table_steal ##### --> |
| <para> |
| |
| </para> |
| |
| @hash_table: |
| @key: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_hash_table_foreach_remove ##### --> |
| <para> |
| |
| </para> |
| |
| @hash_table: |
| @func: |
| @user_data: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_hash_table_foreach_steal ##### --> |
| <para> |
| |
| </para> |
| |
| @hash_table: |
| @func: |
| @user_data: |
| @Returns: |
| |
| |
| <!-- ##### USER_FUNCTION GHRFunc ##### --> |
| <para> |
| Specifies the type of the function passed to g_hash_table_foreach_remove(). |
| It is called with each key/value pair, together with the @user_data parameter |
| passed to g_hash_table_foreach_remove(). |
| It should return %TRUE if the key/value pair should be removed from the |
| #GHashTable. |
| </para> |
| |
| @key: a key. |
| @value: the value associated with the key. |
| @user_data: user data passed to g_hash_table_remove(). |
| @Returns: %TRUE if the key/value pair should be removed from the #GHashTable. |
| |
| |
| <!-- ##### MACRO g_hash_table_freeze ##### --> |
| <para> |
| This function is deprecated and will be removed in the next major |
| release of GLib. It does nothing. |
| </para> |
| |
| @hash_table: a #GHashTable |
| |
| |
| <!-- ##### MACRO g_hash_table_thaw ##### --> |
| <para> |
| This function is deprecated and will be removed in the next major |
| release of GLib. It does nothing. |
| </para> |
| |
| @hash_table: a #GHashTable |
| |
| |
| <!-- ##### FUNCTION g_hash_table_destroy ##### --> |
| <para> |
| |
| </para> |
| |
| @hash_table: |
| |
| |
| <!-- ##### FUNCTION g_direct_equal ##### --> |
| <para> |
| Compares two #gpointer arguments and returns %TRUE if they are equal. |
| It can be passed to g_hash_table_new() as the @key_equal_func |
| parameter, when using pointers as keys in a #GHashTable. |
| </para> |
| |
| @v: a key. |
| @v2: a key to compare with @v. |
| @Returns: %TRUE if the two keys match. |
| |
| |
| <!-- ##### FUNCTION g_direct_hash ##### --> |
| <para> |
| Converts a gpointer to a hash value. |
| It can be passed to g_hash_table_new() as the @hash_func parameter, when |
| using pointers as keys in a #GHashTable. |
| </para> |
| |
| @v: a gpointer key. |
| @Returns: a hash value corresponding to the key. |
| |
| |
| <!-- ##### FUNCTION g_int_equal ##### --> |
| <para> |
| Compares the two #gint values being pointed to and returns %TRUE if they are |
| equal. |
| It can be passed to g_hash_table_new() as the @key_equal_func |
| parameter, when using pointers to integers as keys in a #GHashTable. |
| </para> |
| |
| @v: a pointer to a #gint key. |
| @v2: a pointer to a #gint key to compare with @v. |
| @Returns: %TRUE if the two keys match. |
| |
| |
| <!-- ##### FUNCTION g_int_hash ##### --> |
| <para> |
| Converts a pointer to a #gint to a hash value. |
| It can be passed to g_hash_table_new() as the @hash_func parameter, when |
| using pointers to integers values as keys in a #GHashTable. |
| </para> |
| |
| @v: a pointer to a #gint key. |
| @Returns: a hash value corresponding to the key. |
| |
| |
| <!-- ##### FUNCTION g_str_equal ##### --> |
| <para> |
| Compares two strings and returns %TRUE if they are equal. |
| It can be passed to g_hash_table_new() as the @key_equal_func |
| parameter, when using strings as keys in a #GHashTable. |
| </para> |
| |
| @v: a key. |
| @v2: a key to compare with @v. |
| @Returns: %TRUE if the two keys match. |
| |
| |
| <!-- ##### FUNCTION g_str_hash ##### --> |
| <para> |
| Converts a string to a hash value. |
| It can be passed to g_hash_table_new() as the @hash_func parameter, when |
| using strings as keys in a #GHashTable. |
| </para> |
| |
| @v: a string key. |
| @Returns: a hash value corresponding to the key. |
| |
| |