mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-04-12 02:33:08 +02:00
362 lines
6.4 KiB
Plaintext
362 lines
6.4 KiB
Plaintext
<!-- ##### 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>
|
|
|
|
<!-- ##### SECTION Stability_Level ##### -->
|
|
|
|
|
|
<!-- ##### 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_hash_table_ref ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@hash_table:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_hash_table_unref ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@hash_table:
|
|
|
|
|
|
<!-- ##### FUNCTION g_direct_equal ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@v1:
|
|
@v2:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_direct_hash ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@v:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_int_equal ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@v1:
|
|
@v2:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_int_hash ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@v:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_str_equal ##### -->
|
|
<para>
|
|
</para>
|
|
|
|
@v1:
|
|
@v2:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_str_hash ##### -->
|
|
<para>
|
|
</para>
|
|
|
|
@v:
|
|
@Returns:
|
|
|
|
|