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 ##### -->
<!-- ##### 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>
</para>
@hash_func:
-@key_compare_func:
+@key_equal_func:
@Returns:
-<!-- ##### USER_FUNCTION GHashFunc ##### -->
+<!-- ##### FUNCTION g_hash_table_new_full ##### -->
<para>
</para>
-@key:
+@hash_func:
+@key_equal_func:
+@key_destroy_func:
+@value_destroy_func:
@Returns:
-<!-- ##### USER_FUNCTION GCompareFunc ##### -->
+<!-- ##### 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:
-@b:
-@Returns:
+@a: a value.
+@b: a value to compare with.
+@Returns: %TRUE if @a = @b; %FALSE otherwise.
<!-- ##### FUNCTION g_hash_table_insert ##### -->
@value:
+<!-- ##### FUNCTION g_hash_table_replace ##### -->
+<para>
+
+</para>
+
+@hash_table:
+@key:
+@value:
+
+
<!-- ##### FUNCTION g_hash_table_size ##### -->
<para>
@user_data:
-<!-- ##### USER_FUNCTION GHFunc ##### -->
+<!-- ##### FUNCTION g_hash_table_find ##### -->
<para>
</para>
-@key:
-@value:
+@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 ##### -->
@hash_table:
@key:
+@Returns:
+
+
+<!-- ##### FUNCTION g_hash_table_steal ##### -->
+<para>
+
+</para>
+
+@hash_table:
+@key:
+@Returns:
<!-- ##### FUNCTION g_hash_table_foreach_remove ##### -->
@Returns:
-<!-- ##### USER_FUNCTION GHRFunc ##### -->
+<!-- ##### FUNCTION g_hash_table_foreach_steal ##### -->
<para>
</para>
-@key:
-@value:
+@hash_table:
+@func:
@user_data:
@Returns:
-<!-- ##### FUNCTION g_hash_table_freeze ##### -->
+<!-- ##### 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>
-@hash_table:
+@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.
-<!-- ##### FUNCTION g_hash_table_thaw ##### -->
+<!-- ##### 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:
+@hash_table: a #GHashTable
<!-- ##### FUNCTION g_hash_table_destroy ##### -->
<!-- ##### 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:
-@v2:
-@Returns:
+@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:
-@Returns:
+@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:
-@v2:
-@Returns:
+@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:
-@Returns:
+@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:
-@v2:
-@Returns:
+@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:
-@Returns:
+@v: a string key.
+@Returns: a hash value corresponding to the key.
projects / platform / upstream / glib.git / blobdiff