luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-12-27 07:56:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

GHash: Cosmetic changes

Browse Source
This commit is contained in:
Matthias Clasen 2011-10-02 00:08:13 -04:00
parent ed325b1879
commit e7ca67f20c
2 changed files with 277 additions and 273 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

412
glib/ghash.c
View File

@ -44,7 +44,7 @@
* SECTION:hash_tables * SECTION:hash_tables
* @title: Hash Tables * @title: Hash Tables
* @short_description: associations between keys and values so that * @short_description: associations between keys and values so that
* given a key the value can be found quickly * given a key the value can be found quickly
* *
* A #GHashTable provides associations between keys and values which is * A #GHashTable provides associations between keys and values which is
* optimized so that given a key, the associated value can be found * optimized so that given a key, the associated value can be found
@ -131,12 +131,11 @@
* The #GHashTable struct is an opaque data structure to represent a * The #GHashTable struct is an opaque data structure to represent a
* <link linkend="glib-Hash-Tables">Hash Table</link>. It should only be * <link linkend="glib-Hash-Tables">Hash Table</link>. It should only be
* accessed via the following functions. * accessed via the following functions.
**/ */
/** /**
* GHashFunc: * GHashFunc:
* @key: a key. * @key: a key
* @Returns: the hash value corresponding to the key.
* *
* Specifies the type of the hash function which is passed to * Specifies the type of the hash function which is passed to
* g_hash_table_new() when a #GHashTable is created. * g_hash_table_new() when a #GHashTable is created.
@ -151,44 +150,48 @@
* hash table size (a prime number) to find the 'bucket' to place each * 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 * key into. The function should also be very fast, since it is called
* for each key lookup. * for each key lookup.
**/ *
* Returns: the hash value corresponding to the key
*/
/** /**
* GHFunc: * GHFunc:
* @key: a key. * @key: a key
* @value: the value corresponding to the key. * @value: the value corresponding to the key
* @user_data: user data passed to g_hash_table_foreach(). * @user_data: user data passed to g_hash_table_foreach()
* *
* Specifies the type of the function passed to g_hash_table_foreach(). * 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 * It is called with each key/value pair, together with the @user_data
* parameter which is passed to g_hash_table_foreach(). * parameter which is passed to g_hash_table_foreach().
**/ */
/** /**
* GHRFunc: * GHRFunc:
* @key: a key. * @key: a key
* @value: the value associated with the key. * @value: the value associated with the key
* @user_data: user data passed to g_hash_table_remove(). * @user_data: user data passed to g_hash_table_remove()
* @Returns: %TRUE if the key/value pair should be removed from the
* #GHashTable.
* *
* Specifies the type of the function passed to * Specifies the type of the function passed to
* g_hash_table_foreach_remove(). It is called with each key/value * g_hash_table_foreach_remove(). It is called with each key/value
* pair, together with the @user_data parameter passed to * pair, together with the @user_data parameter passed to
* g_hash_table_foreach_remove(). It should return %TRUE if the * g_hash_table_foreach_remove(). It should return %TRUE if the
* key/value pair should be removed from the #GHashTable. * key/value pair should be removed from the #GHashTable.
**/ *
* Returns: %TRUE if the key/value pair should be removed from the
* #GHashTable
*/
/** /**
* GEqualFunc: * GEqualFunc:
* @a: a value. * @a: a value
* @b: a value to compare with. * @b: a value to compare with
* @Returns: %TRUE if @a = @b; %FALSE otherwise.
* *
* Specifies the type of a function used to test two values for * Specifies the type of a function used to test two values for
* equality. The function should return %TRUE if both values are equal * equality. The function should return %TRUE if both values are equal
* and %FALSE otherwise. * and %FALSE otherwise.
**/ *
* Returns: %TRUE if @a = @b; %FALSE otherwise
*/
/** /**
* GHashTableIter: * GHashTableIter:
@ -197,7 +200,23 @@
* to iterate over the elements of a #GHashTable. GHashTableIter * to iterate over the elements of a #GHashTable. GHashTableIter
* structures are typically allocated on the stack and then initialized * structures are typically allocated on the stack and then initialized
* with g_hash_table_iter_init(). * with g_hash_table_iter_init().
**/ */
/**
* g_hash_table_freeze:
* @hash_table: a #GHashTable
*
* This function is deprecated and will be removed in the next major
* release of GLib. It does nothing.
*/
/**
* g_hash_table_thaw:
* @hash_table: a #GHashTable
*
* This function is deprecated and will be removed in the next major
* release of GLib. It does nothing.
*/
#define HASH_TABLE_MIN_SHIFT 3 /* 1 << 3 == 8 buckets */ #define HASH_TABLE_MIN_SHIFT 3 /* 1 << 3 == 8 buckets */
@ -247,7 +266,8 @@ typedef struct
/* Each table size has an associated prime modulo (the first prime /* Each table size has an associated prime modulo (the first prime
* lower than the table size) used to find the initial bucket. Probing * lower than the table size) used to find the initial bucket. Probing
* then works modulo 2^n. The prime modulo is necessary to get a * then works modulo 2^n. The prime modulo is necessary to get a
* good distribution with poor hash functions. */ * good distribution with poor hash functions.
*/
static const gint prime_mod [] = static const gint prime_mod [] =
{ {
1, /* For 1 << 0 */ 1, /* For 1 << 0 */
@ -329,7 +349,6 @@ g_hash_table_set_shift_from_size (GHashTable *hash_table, gint size)
* @hash_table: our #GHashTable * @hash_table: our #GHashTable
* @key: the key to lookup against * @key: the key to lookup against
* @hash_return: key hash return location * @hash_return: key hash return location
* Return value: index of the described node
* *
* Performs a lookup in the hash table, preserving extra information * Performs a lookup in the hash table, preserving extra information
* usually needed for insertion. * usually needed for insertion.
@ -345,6 +364,8 @@ g_hash_table_set_shift_from_size (GHashTable *hash_table, gint size)
* The computed hash value is returned in the variable pointed to * The computed hash value is returned in the variable pointed to
* by @hash_return. This is to save insertions from having to compute * by @hash_return. This is to save insertions from having to compute
* the hash record again for the new record. * the hash record again for the new record.
*
* Returns: index of the described node
*/ */
static inline guint static inline guint
g_hash_table_lookup_node (GHashTable *hash_table, g_hash_table_lookup_node (GHashTable *hash_table,
@ -419,7 +440,7 @@ g_hash_table_lookup_node (GHashTable *hash_table,
*/ */
static void static void
g_hash_table_remove_node (GHashTable *hash_table, g_hash_table_remove_node (GHashTable *hash_table,
int i, gint i,
gboolean notify) gboolean notify)
{ {
gpointer key; gpointer key;
@ -507,9 +528,9 @@ g_hash_table_remove_all_nodes (GHashTable *hash_table,
* @hash_table: our #GHashTable * @hash_table: our #GHashTable
* *
* Resizes the hash table to the optimal size based on the number of * Resizes the hash table to the optimal size based on the number of
* nodes currently held. If you call this function then a resize will * nodes currently held. If you call this function then a resize will
* occur, even if one does not need to occur. Use * occur, even if one does not need to occur.
* g_hash_table_maybe_resize() instead. * Use g_hash_table_maybe_resize() instead.
* *
* This function may "resize" the hash table to its current size, with * This function may "resize" the hash table to its current size, with
* the side effect of cleaning up tombstones and otherwise optimizing * the side effect of cleaning up tombstones and otherwise optimizing
@ -592,26 +613,29 @@ g_hash_table_maybe_resize (GHashTable *hash_table)
/** /**
* g_hash_table_new: * g_hash_table_new:
* @hash_func: a function to create a hash value from a key. * @hash_func: a function to create a hash value from a key
* Hash values are used to determine where keys are stored within the * @key_equal_func: a function to check two keys for equality
* #GHashTable data structure. The g_direct_hash(), g_int_hash(),
* g_int64_hash(), g_double_hash() and g_str_hash() functions are provided
* for some common types of keys.
* If hash_func is %NULL, g_direct_hash() is used.
* @key_equal_func: a function to check two keys for equality. This is
* used when looking up keys in the #GHashTable. The g_direct_equal(),
* g_int_equal(), g_int64_equal(), g_double_equal() and g_str_equal()
* functions are provided for the most common types of keys.
* If @key_equal_func is %NULL, keys are compared directly in a similar
* fashion to g_direct_equal(), but without the overhead of a function call.
* *
* Creates a new #GHashTable with a reference count of 1. * Creates a new #GHashTable with a reference count of 1.
* *
* Return value: a new #GHashTable. * Hash values returned by @hash_func are used to determine where keys
**/ * are stored within the #GHashTable data structure. The g_direct_hash(),
GHashTable* * g_int_hash(), g_int64_hash(), g_double_hash() and g_str_hash()
g_hash_table_new (GHashFunc hash_func, * functions are provided for some common types of keys.
GEqualFunc key_equal_func) * If @hash_func is %NULL, g_direct_hash() is used.
*
* @key_equal_func is used when looking up keys in the #GHashTable.
* The g_direct_equal(), g_int_equal(), g_int64_equal(), g_double_equal()
* and g_str_equal() functions are provided for the most common types
* of keys. If @key_equal_func is %NULL, keys are compared directly in
* a similar fashion to g_direct_equal(), but without the overhead of
* a function call.
*
* Return value: a new #GHashTable
*/
GHashTable *
g_hash_table_new (GHashFunc hash_func,
GEqualFunc key_equal_func)
{ {
return g_hash_table_new_full (hash_func, key_equal_func, NULL, NULL); return g_hash_table_new_full (hash_func, key_equal_func, NULL, NULL);
} }
@ -619,26 +643,27 @@ g_hash_table_new (GHashFunc hash_func,
/** /**
* g_hash_table_new_full: * g_hash_table_new_full:
* @hash_func: a function to create a hash value from a key. * @hash_func: a function to create a hash value from a key
* @key_equal_func: a function to check two keys for equality. * @key_equal_func: a function to check two keys for equality
* @key_destroy_func: a function to free the memory allocated for the key * @key_destroy_func: a function to free the memory allocated for the key
* used when removing the entry from the #GHashTable or %NULL if you * used when removing the entry from the #GHashTable, or %NULL
* don't want to supply such a function. * if you don't want to supply such a function.
* @value_destroy_func: a function to free the memory allocated for the * @value_destroy_func: a function to free the memory allocated for the
* value used when removing the entry from the #GHashTable or %NULL if * value used when removing the entry from the #GHashTable, or %NULL
* you don't want to supply such a function. * if you don't want to supply such a function.
* *
* Creates a new #GHashTable like g_hash_table_new() with a reference count * Creates a new #GHashTable like g_hash_table_new() with a reference
* of 1 and allows to specify functions to free the memory allocated for the * count of 1 and allows to specify functions to free the memory
* key and value that get called when removing the entry from the #GHashTable. * allocated for the key and value that get called when removing the
* entry from the #GHashTable.
* *
* Return value: a new #GHashTable. * Return value: a new #GHashTable
**/ */
GHashTable* GHashTable *
g_hash_table_new_full (GHashFunc hash_func, g_hash_table_new_full (GHashFunc hash_func,
GEqualFunc key_equal_func, GEqualFunc key_equal_func,
GDestroyNotify key_destroy_func, GDestroyNotify key_destroy_func,
GDestroyNotify value_destroy_func) GDestroyNotify value_destroy_func)
{ {
GHashTable *hash_table; GHashTable *hash_table;
@ -663,8 +688,8 @@ g_hash_table_new_full (GHashFunc hash_func,
/** /**
* g_hash_table_iter_init: * g_hash_table_iter_init:
* @iter: an uninitialized #GHashTableIter. * @iter: an uninitialized #GHashTableIter
* @hash_table: a #GHashTable. * @hash_table: a #GHashTable
* *
* Initializes a key/value pair iterator and associates it with * Initializes a key/value pair iterator and associates it with
* @hash_table. Modifying the hash table after calling this function * @hash_table. Modifying the hash table after calling this function
@ -681,7 +706,7 @@ g_hash_table_new_full (GHashFunc hash_func,
* ]| * ]|
* *
* Since: 2.16 * Since: 2.16
**/ */
void void
g_hash_table_iter_init (GHashTableIter *iter, g_hash_table_iter_init (GHashTableIter *iter,
GHashTable *hash_table) GHashTable *hash_table)
@ -700,9 +725,9 @@ g_hash_table_iter_init (GHashTableIter *iter,
/** /**
* g_hash_table_iter_next: * g_hash_table_iter_next:
* @iter: an initialized #GHashTableIter. * @iter: an initialized #GHashTableIter
* @key: a location to store the key, or %NULL. * @key: a location to store the key, or %NULL
* @value: a location to store the value, or %NULL. * @value: a location to store the value, or %NULL
* *
* Advances @iter and retrieves the key and/or value that are now * Advances @iter and retrieves the key and/or value that are now
* pointed to as a result of this advancement. If %FALSE is returned, * pointed to as a result of this advancement. If %FALSE is returned,
@ -711,7 +736,7 @@ g_hash_table_iter_init (GHashTableIter *iter,
* Return value: %FALSE if the end of the #GHashTable has been reached. * Return value: %FALSE if the end of the #GHashTable has been reached.
* *
* Since: 2.16 * Since: 2.16
**/ */
gboolean gboolean
g_hash_table_iter_next (GHashTableIter *iter, g_hash_table_iter_next (GHashTableIter *iter,
gpointer *key, gpointer *key,
@ -750,14 +775,14 @@ g_hash_table_iter_next (GHashTableIter *iter,
/** /**
* g_hash_table_iter_get_hash_table: * g_hash_table_iter_get_hash_table:
* @iter: an initialized #GHashTableIter. * @iter: an initialized #GHashTableIter
* *
* Returns the #GHashTable associated with @iter. * Returns the #GHashTable associated with @iter.
* *
* Return value: the #GHashTable associated with @iter. * Return value: the #GHashTable associated with @iter.
* *
* Since: 2.16 * Since: 2.16
**/ */
GHashTable * GHashTable *
g_hash_table_iter_get_hash_table (GHashTableIter *iter) g_hash_table_iter_get_hash_table (GHashTableIter *iter)
{ {
@ -786,20 +811,20 @@ iter_remove_or_steal (RealIter *ri, gboolean notify)
/** /**
* g_hash_table_iter_remove: * g_hash_table_iter_remove:
* @iter: an initialized #GHashTableIter. * @iter: an initialized #GHashTableIter
* *
* Removes the key/value pair currently pointed to by the iterator * Removes the key/value pair currently pointed to by the iterator
* from its associated #GHashTable. Can only be called after * from its associated #GHashTable. Can only be called after
* g_hash_table_iter_next() returned %TRUE, and cannot be called more * g_hash_table_iter_next() returned %TRUE, and cannot be called
* than once for the same key/value pair. * more than once for the same key/value pair.
* *
* If the #GHashTable was created using g_hash_table_new_full(), the * If the #GHashTable was created using g_hash_table_new_full(),
* key and value are freed using the supplied destroy functions, otherwise * the key and value are freed using the supplied destroy functions,
* you have to make sure that any dynamically allocated values are freed * otherwise you have to make sure that any dynamically allocated
* yourself. * values are freed yourself.
* *
* Since: 2.16 * Since: 2.16
**/ */
void void
g_hash_table_iter_remove (GHashTableIter *iter) g_hash_table_iter_remove (GHashTableIter *iter)
{ {
@ -872,18 +897,18 @@ g_hash_table_insert_node (GHashTable *hash_table,
/** /**
* g_hash_table_iter_replace: * g_hash_table_iter_replace:
* @iter: an initialized #GHashTableIter. * @iter: an initialized #GHashTableIter
* @value: the value to replace with * @value: the value to replace with
* *
* Replaces the value currently pointed to by the iterator * Replaces the value currently pointed to by the iterator
* from its associated #GHashTable. Can only be called after * from its associated #GHashTable. Can only be called after
* g_hash_table_iter_next() returned %TRUE. * g_hash_table_iter_next() returned %TRUE.
* *
* If you supplied a @value_destroy_func when creating the #GHashTable, * If you supplied a @value_destroy_func when creating the
* the old value is freed using that function. * #GHashTable, the old value is freed using that function.
* *
* Since: 2.29.9 * Since: 2.30
**/ */
void void
g_hash_table_iter_replace (GHashTableIter *iter, g_hash_table_iter_replace (GHashTableIter *iter,
gpointer value) gpointer value)
@ -914,16 +939,16 @@ g_hash_table_iter_replace (GHashTableIter *iter,
/** /**
* g_hash_table_iter_steal: * g_hash_table_iter_steal:
* @iter: an initialized #GHashTableIter. * @iter: an initialized #GHashTableIter
* *
* Removes the key/value pair currently pointed to by the iterator * Removes the key/value pair currently pointed to by the
* from its associated #GHashTable, without calling the key and value * iterator from its associated #GHashTable, without calling
* destroy functions. Can only be called after * the key and value destroy functions. Can only be called
* g_hash_table_iter_next() returned %TRUE, and cannot be called more * after g_hash_table_iter_next() returned %TRUE, and cannot
* than once for the same key/value pair. * be called more than once for the same key/value pair.
* *
* Since: 2.16 * Since: 2.16
**/ */
void void
g_hash_table_iter_steal (GHashTableIter *iter) g_hash_table_iter_steal (GHashTableIter *iter)
{ {
@ -933,16 +958,16 @@ g_hash_table_iter_steal (GHashTableIter *iter)
/** /**
* g_hash_table_ref: * g_hash_table_ref:
* @hash_table: a valid #GHashTable. * @hash_table: a valid #GHashTable
* *
* Atomically increments the reference count of @hash_table by one. * Atomically increments the reference count of @hash_table by one.
* This function is MT-safe and may be called from any thread. * This function is MT-safe and may be called from any thread.
* *
* Return value: the passed in #GHashTable. * Return value: the passed in #GHashTable
* *
* Since: 2.10 * Since: 2.10
**/ */
GHashTable* GHashTable *
g_hash_table_ref (GHashTable *hash_table) g_hash_table_ref (GHashTable *hash_table)
{ {
g_return_val_if_fail (hash_table != NULL, NULL); g_return_val_if_fail (hash_table != NULL, NULL);
@ -954,7 +979,7 @@ g_hash_table_ref (GHashTable *hash_table)
/** /**
* g_hash_table_unref: * g_hash_table_unref:
* @hash_table: a valid #GHashTable. * @hash_table: a valid #GHashTable
* *
* Atomically decrements the reference count of @hash_table by one. * Atomically decrements the reference count of @hash_table by one.
* If the reference count drops to 0, all keys and values will be * If the reference count drops to 0, all keys and values will be
@ -962,7 +987,7 @@ g_hash_table_ref (GHashTable *hash_table)
* This function is MT-safe and may be called from any thread. * This function is MT-safe and may be called from any thread.
* *
* Since: 2.10 * Since: 2.10
**/ */
void void
g_hash_table_unref (GHashTable *hash_table) g_hash_table_unref (GHashTable *hash_table)
{ {
@ -981,7 +1006,7 @@ g_hash_table_unref (GHashTable *hash_table)
/** /**
* g_hash_table_destroy: * g_hash_table_destroy:
* @hash_table: a #GHashTable. * @hash_table: a #GHashTable
* *
* Destroys all keys and values in the #GHashTable and decrements its * Destroys all keys and values in the #GHashTable and decrements its
* reference count by 1. If keys and/or values are dynamically allocated, * reference count by 1. If keys and/or values are dynamically allocated,
@ -989,7 +1014,7 @@ g_hash_table_unref (GHashTable *hash_table)
* notifiers using g_hash_table_new_full(). In the latter case the destroy * notifiers using g_hash_table_new_full(). In the latter case the destroy
* functions you supplied will be called on all keys and values during the * functions you supplied will be called on all keys and values during the
* destruction phase. * destruction phase.
**/ */
void void
g_hash_table_destroy (GHashTable *hash_table) g_hash_table_destroy (GHashTable *hash_table)
{ {
@ -1001,19 +1026,19 @@ g_hash_table_destroy (GHashTable *hash_table)
/** /**
* g_hash_table_lookup: * g_hash_table_lookup:
* @hash_table: a #GHashTable. * @hash_table: a #GHashTable
* @key: the key to look up. * @key: the key to look up
* *
* Looks up a key in a #GHashTable. Note that this function cannot * Looks up a key in a #GHashTable. Note that this function cannot
* distinguish between a key that is not present and one which is present * distinguish between a key that is not present and one which is present
* and has the value %NULL. If you need this distinction, use * and has the value %NULL. If you need this distinction, use
* g_hash_table_lookup_extended(). * g_hash_table_lookup_extended().
* *
* Return value: the associated value, or %NULL if the key is not found. * Return value: the associated value, or %NULL if the key is not found
**/ */
gpointer gpointer
g_hash_table_lookup (GHashTable *hash_table, g_hash_table_lookup (GHashTable *hash_table,
gconstpointer key) gconstpointer key)
{ {
guint node_index; guint node_index;
guint node_hash; guint node_hash;
@ -1043,8 +1068,8 @@ g_hash_table_lookup (GHashTable *hash_table,
* whether the %NULL key exists, provided the hash and equal functions * whether the %NULL key exists, provided the hash and equal functions
* of @hash_table are %NULL-safe. * of @hash_table are %NULL-safe.
* *
* Return value: %TRUE if the key was found in the #GHashTable. * Return value: %TRUE if the key was found in the #GHashTable
**/ */
gboolean gboolean
g_hash_table_lookup_extended (GHashTable *hash_table, g_hash_table_lookup_extended (GHashTable *hash_table,
gconstpointer lookup_key, gconstpointer lookup_key,
@ -1082,9 +1107,9 @@ g_hash_table_lookup_extended (GHashTable *hash_table,
* Implements the common logic for the g_hash_table_insert() and * Implements the common logic for the g_hash_table_insert() and
* g_hash_table_replace() functions. * g_hash_table_replace() functions.
* *
* Do a lookup of @key. If it is found, replace it with the new * Do a lookup of @key. If it is found, replace it with the new
* @value (and perhaps the new @key). If it is not found, create a * @value (and perhaps the new @key). If it is not found, create
* new node. * a new node.
*/ */
static void static void
g_hash_table_insert_internal (GHashTable *hash_table, g_hash_table_insert_internal (GHashTable *hash_table,
@ -1104,18 +1129,19 @@ g_hash_table_insert_internal (GHashTable *hash_table,
/** /**
* g_hash_table_insert: * g_hash_table_insert:
* @hash_table: a #GHashTable. * @hash_table: a #GHashTable
* @key: a key to insert. * @key: a key to insert
* @value: the value to associate with the key. * @value: the value to associate with the key
* *
* Inserts a new key and value into a #GHashTable. * Inserts a new key and value into a #GHashTable.
* *
* If the key already exists in the #GHashTable its current value is replaced * If the key already exists in the #GHashTable its current
* with the new value. If you supplied a @value_destroy_func when creating the * value is replaced with the new value. If you supplied a
* #GHashTable, the old value is freed using that function. If you supplied * @value_destroy_func when creating the #GHashTable, the old
* a @key_destroy_func when creating the #GHashTable, the passed key is freed * value is freed using that function. If you supplied a
* using that function. * @key_destroy_func when creating the #GHashTable, the passed
**/ * key is freed using that function.
*/
void void
g_hash_table_insert (GHashTable *hash_table, g_hash_table_insert (GHashTable *hash_table,
gpointer key, gpointer key,
@ -1126,17 +1152,18 @@ g_hash_table_insert (GHashTable *hash_table,
/** /**
* g_hash_table_replace: * g_hash_table_replace:
* @hash_table: a #GHashTable. * @hash_table: a #GHashTable
* @key: a key to insert. * @key: a key to insert
* @value: the value to associate with the key. * @value: the value to associate with the key
* *
* Inserts a new key and value into a #GHashTable similar to * Inserts a new key and value into a #GHashTable similar to
* g_hash_table_insert(). The difference is that if the key already exists * g_hash_table_insert(). The difference is that if the key
* in the #GHashTable, it gets replaced by the new key. If you supplied a * already exists in the #GHashTable, it gets replaced by the
* @value_destroy_func when creating the #GHashTable, the old value is freed * new key. If you supplied a @value_destroy_func when creating
* using that function. If you supplied a @key_destroy_func when creating the * the #GHashTable, the old value is freed using that function.
* If you supplied a @key_destroy_func when creating the
* #GHashTable, the old key is freed using that function. * #GHashTable, the old key is freed using that function.
**/ */
void void
g_hash_table_replace (GHashTable *hash_table, g_hash_table_replace (GHashTable *hash_table,
gpointer key, gpointer key,
@ -1185,8 +1212,8 @@ g_hash_table_remove_internal (GHashTable *hash_table,
/** /**
* g_hash_table_remove: * g_hash_table_remove:
* @hash_table: a #GHashTable. * @hash_table: a #GHashTable
* @key: the key to remove. * @key: the key to remove
* *
* Removes a key and its associated value from a #GHashTable. * Removes a key and its associated value from a #GHashTable.
* *
@ -1195,8 +1222,8 @@ g_hash_table_remove_internal (GHashTable *hash_table,
* you have to make sure that any dynamically allocated values are freed * you have to make sure that any dynamically allocated values are freed
* yourself. * yourself.
* *
* Return value: %TRUE if the key was found and removed from the #GHashTable. * Returns: %TRUE if the key was found and removed from the #GHashTable
**/ */
gboolean gboolean
g_hash_table_remove (GHashTable *hash_table, g_hash_table_remove (GHashTable *hash_table,
gconstpointer key) gconstpointer key)
@ -1206,14 +1233,14 @@ g_hash_table_remove (GHashTable *hash_table,
/** /**
* g_hash_table_steal: * g_hash_table_steal:
* @hash_table: a #GHashTable. * @hash_table: a #GHashTable
* @key: the key to remove. * @key: the key to remove
* *
* Removes a key and its associated value from a #GHashTable without * Removes a key and its associated value from a #GHashTable without
* calling the key and value destroy functions. * calling the key and value destroy functions.
* *
* Return value: %TRUE if the key was found and removed from the #GHashTable. * Returns: %TRUE if the key was found and removed from the #GHashTable
**/ */
gboolean gboolean
g_hash_table_steal (GHashTable *hash_table, g_hash_table_steal (GHashTable *hash_table,
gconstpointer key) gconstpointer key)
@ -1227,13 +1254,13 @@ g_hash_table_steal (GHashTable *hash_table,
* *
* Removes all keys and their associated values from a #GHashTable. * Removes all keys and their associated values from a #GHashTable.
* *
* If the #GHashTable was created using g_hash_table_new_full(), the keys * If the #GHashTable was created using g_hash_table_new_full(),
* and values are freed using the supplied destroy functions, otherwise you * the keys and values are freed using the supplied destroy functions,
* have to make sure that any dynamically allocated values are freed * otherwise you have to make sure that any dynamically allocated
* yourself. * values are freed yourself.
* *
* Since: 2.12 * Since: 2.12
**/ */
void void
g_hash_table_remove_all (GHashTable *hash_table) g_hash_table_remove_all (GHashTable *hash_table)
{ {
@ -1250,13 +1277,13 @@ g_hash_table_remove_all (GHashTable *hash_table)
/** /**
* g_hash_table_steal_all: * g_hash_table_steal_all:
* @hash_table: a #GHashTable. * @hash_table: a #GHashTable
* *
* Removes all keys and their associated values from a #GHashTable * Removes all keys and their associated values from a #GHashTable
* without calling the key and value destroy functions. * without calling the key and value destroy functions.
* *
* Since: 2.12 * Since: 2.12
**/ */
void void
g_hash_table_steal_all (GHashTable *hash_table) g_hash_table_steal_all (GHashTable *hash_table)
{ {
@ -1273,16 +1300,16 @@ g_hash_table_steal_all (GHashTable *hash_table)
/* /*
* g_hash_table_foreach_remove_or_steal: * g_hash_table_foreach_remove_or_steal:
* @hash_table: our #GHashTable * @hash_table: a #GHashTable
* @func: the user's callback function * @func: the user's callback function
* @user_data: data for @func * @user_data: data for @func
* @notify: %TRUE if the destroy notify handlers are to be called * @notify: %TRUE if the destroy notify handlers are to be called
* *
* Implements the common logic for g_hash_table_foreach_remove() and * Implements the common logic for g_hash_table_foreach_remove()
* g_hash_table_foreach_steal(). * and g_hash_table_foreach_steal().
* *
* Iterates over every node in the table, calling @func with the key * Iterates over every node in the table, calling @func with the key
* and value of the node (and @user_data). If @func returns %TRUE the * and value of the node (and @user_data). If @func returns %TRUE the
* node is removed from the table. * node is removed from the table.
* *
* If @notify is true then the destroy notify handlers will be called * If @notify is true then the destroy notify handlers will be called
@ -1330,21 +1357,21 @@ g_hash_table_foreach_remove_or_steal (GHashTable *hash_table,
/** /**
* g_hash_table_foreach_remove: * g_hash_table_foreach_remove:
* @hash_table: a #GHashTable. * @hash_table: a #GHashTable
* @func: the function to call for each key/value pair. * @func: the function to call for each key/value pair
* @user_data: user data to pass to the function. * @user_data: user data to pass to the function
* *
* Calls the given function for each key/value pair in the #GHashTable. * Calls the given function for each key/value pair in the
* If the function returns %TRUE, then the key/value pair is removed from the * #GHashTable. If the function returns %TRUE, then the key/value
* #GHashTable. If you supplied key or value destroy functions when creating * pair is removed from the #GHashTable. If you supplied key or
* the #GHashTable, they are used to free the memory allocated for the removed * value destroy functions when creating the #GHashTable, they are
* keys and values. * used to free the memory allocated for the removed keys and values.
* *
* See #GHashTableIter for an alternative way to loop over the * See #GHashTableIter for an alternative way to loop over the
* key/value pairs in the hash table. * key/value pairs in the hash table.
* *
* Return value: the number of key/value pairs removed. * Return value: the number of key/value pairs removed
**/ */
guint guint
g_hash_table_foreach_remove (GHashTable *hash_table, g_hash_table_foreach_remove (GHashTable *hash_table,
GHRFunc func, GHRFunc func,
@ -1358,19 +1385,20 @@ g_hash_table_foreach_remove (GHashTable *hash_table,
/** /**
* g_hash_table_foreach_steal: * g_hash_table_foreach_steal:
* @hash_table: a #GHashTable. * @hash_table: a #GHashTable
* @func: the function to call for each key/value pair. * @func: the function to call for each key/value pair
* @user_data: user data to pass to the function. * @user_data: user data to pass to the function
* *
* Calls the given function for each key/value pair in the #GHashTable. * Calls the given function for each key/value pair in the
* If the function returns %TRUE, then the key/value pair is removed from the * #GHashTable. If the function returns %TRUE, then the key/value
* #GHashTable, but no key or value destroy functions are called. * pair is removed from the #GHashTable, but no key or value
* destroy functions are called.
* *
* See #GHashTableIter for an alternative way to loop over the * See #GHashTableIter for an alternative way to loop over the
* key/value pairs in the hash table. * key/value pairs in the hash table.
* *
* Return value: the number of key/value pairs removed. * Return value: the number of key/value pairs removed.
**/ */
guint guint
g_hash_table_foreach_steal (GHashTable *hash_table, g_hash_table_foreach_steal (GHashTable *hash_table,
GHRFunc func, GHRFunc func,
@ -1384,9 +1412,9 @@ g_hash_table_foreach_steal (GHashTable *hash_table,
/** /**
* g_hash_table_foreach: * g_hash_table_foreach:
* @hash_table: a #GHashTable. * @hash_table: a #GHashTable
* @func: the function to call for each key/value pair. * @func: the function to call for each key/value pair
* @user_data: user data to pass to the function. * @user_data: user data to pass to the function
* *
* Calls the given function for each of the key/value pairs in the * Calls the given function for each of the key/value pairs in the
* #GHashTable. The function is passed the key and value of each * #GHashTable. The function is passed the key and value of each
@ -1397,7 +1425,7 @@ g_hash_table_foreach_steal (GHashTable *hash_table,
* *
* See g_hash_table_find() for performance caveats for linear * See g_hash_table_find() for performance caveats for linear
* order searches in contrast to g_hash_table_lookup(). * order searches in contrast to g_hash_table_lookup().
**/ */
void void
g_hash_table_foreach (GHashTable *hash_table, g_hash_table_foreach (GHashTable *hash_table,
GHFunc func, GHFunc func,
@ -1428,30 +1456,30 @@ g_hash_table_foreach (GHashTable *hash_table,
/** /**
* g_hash_table_find: * g_hash_table_find:
* @hash_table: a #GHashTable. * @hash_table: a #GHashTable
* @predicate: function to test the key/value pairs for a certain property. * @predicate: function to test the key/value pairs for a certain property
* @user_data: user data to pass to the function. * @user_data: user data to pass to the function
* *
* Calls the given function for key/value pairs in the #GHashTable until * Calls the given function for key/value pairs in the #GHashTable
* @predicate returns %TRUE. The function is passed the key and value of * until @predicate returns %TRUE. The function is passed the key
* each pair, and the given @user_data parameter. The hash table may not * and value of each pair, and the given @user_data parameter. The
* be modified while iterating over it (you can't add/remove items). * hash table may not be modified while iterating over it (you can't
* add/remove items).
* *
* Note, that hash tables are really only optimized for forward lookups, * Note, that hash tables are really only optimized for forward
* i.e. g_hash_table_lookup(). * lookups, i.e. g_hash_table_lookup(). So code that frequently issues
* So code that frequently issues g_hash_table_find() or * g_hash_table_find() or g_hash_table_foreach() (e.g. in the order of
* g_hash_table_foreach() (e.g. in the order of once per every entry in a * once per every entry in a hash table) should probably be reworked
* hash table) should probably be reworked to use additional or different * to use additional or different data structures for reverse lookups
* data structures for reverse lookups (keep in mind that an O(n) find/foreach * (keep in mind that an O(n) find/foreach operation issued for all n
* operation issued for all n values in a hash table ends up needing O(n*n) * values in a hash table ends up needing O(n*n) operations).
* operations).
* *
* Return value: The value of the first key/value pair is returned, * Return value: The value of the first key/value pair is returned,
* for which @predicate evaluates to %TRUE. If no pair with the * for which @predicate evaluates to %TRUE. If no pair with the
* requested property is found, %NULL is returned. * requested property is found, %NULL is returned.
* *
* Since: 2.4 * Since: 2.4
**/ */
gpointer gpointer
g_hash_table_find (GHashTable *hash_table, g_hash_table_find (GHashTable *hash_table,
GHRFunc predicate, GHRFunc predicate,
@ -1490,12 +1518,12 @@ g_hash_table_find (GHashTable *hash_table,
/** /**
* g_hash_table_size: * g_hash_table_size:
* @hash_table: a #GHashTable. * @hash_table: a #GHashTable
* *
* Returns the number of elements contained in the #GHashTable. * Returns the number of elements contained in the #GHashTable.
* *
* Return value: the number of key/value pairs in the #GHashTable. * Return value: the number of key/value pairs in the #GHashTable.
**/ */
guint guint
g_hash_table_size (GHashTable *hash_table) g_hash_table_size (GHashTable *hash_table)
{ {
@ -1508,13 +1536,13 @@ g_hash_table_size (GHashTable *hash_table)
* g_hash_table_get_keys: * g_hash_table_get_keys:
* @hash_table: a #GHashTable * @hash_table: a #GHashTable
* *
* Retrieves every key inside @hash_table. The returned data is valid * Retrieves every key inside @hash_table. The returned data
* until @hash_table is modified. * is valid until @hash_table is modified.
* *
* Return value: a #GList containing all the keys inside the hash * Return value: a #GList containing all the keys inside the hash
* table. The content of the list is owned by the hash table and * table. The content of the list is owned by the hash table and
* should not be modified or freed. Use g_list_free() when done * should not be modified or freed. Use g_list_free() when done
* using the list. * using the list.
* *
* Since: 2.14 * Since: 2.14
*/ */
@ -1540,13 +1568,13 @@ g_hash_table_get_keys (GHashTable *hash_table)
* g_hash_table_get_values: * g_hash_table_get_values:
* @hash_table: a #GHashTable * @hash_table: a #GHashTable
* *
* Retrieves every value inside @hash_table. The returned data is * Retrieves every value inside @hash_table. The returned data
* valid until @hash_table is modified. * is valid until @hash_table is modified.
* *
* Return value: a #GList containing all the values inside the hash * Return value: a #GList containing all the values inside the hash
* table. The content of the list is owned by the hash table and * table. The content of the list is owned by the hash table and
* should not be modified or freed. Use g_list_free() when done * should not be modified or freed. Use g_list_free() when done
* using the list. * using the list.
* *
* Since: 2.14 * Since: 2.14
*/ */

134
glib/ghash.h
View File

@ -8,7 +8,7 @@
* *
* This library is distributed in the hope that it will be useful, * This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of * but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details. * Lesser General Public License for more details.
* *
* You should have received a copy of the GNU Lesser General Public * You should have received a copy of the GNU Lesser General Public
@ -47,118 +47,94 @@ typedef struct _GHashTableIter GHashTableIter;
struct _GHashTableIter struct _GHashTableIter
{ {
/*< private >*/ /*< private >*/
gpointer dummy1; gpointer dummy1;
gpointer dummy2; gpointer dummy2;
gpointer dummy3; gpointer dummy3;
int dummy4; int dummy4;
gboolean dummy5; gboolean dummy5;
gpointer dummy6; gpointer dummy6;
}; };
/* Hash tables GHashTable* g_hash_table_new (GHashFunc hash_func,
*/ GEqualFunc key_equal_func);
GHashTable* g_hash_table_new (GHashFunc hash_func, GHashTable* g_hash_table_new_full (GHashFunc hash_func,
GEqualFunc key_equal_func); GEqualFunc key_equal_func,
GHashTable* g_hash_table_new_full (GHashFunc hash_func, GDestroyNotify key_destroy_func,
GEqualFunc key_equal_func, GDestroyNotify value_destroy_func);
GDestroyNotify key_destroy_func, void g_hash_table_destroy (GHashTable *hash_table);
GDestroyNotify value_destroy_func); void g_hash_table_insert (GHashTable *hash_table,
void g_hash_table_destroy (GHashTable *hash_table); gpointer key,
void g_hash_table_insert (GHashTable *hash_table, gpointer value);
gpointer key,
gpointer value);
void g_hash_table_replace (GHashTable *hash_table, void g_hash_table_replace (GHashTable *hash_table,
gpointer key, gpointer key,
gpointer value); gpointer value);
gboolean g_hash_table_remove (GHashTable *hash_table, gboolean g_hash_table_remove (GHashTable *hash_table,
gconstpointer key); gconstpointer key);
void g_hash_table_remove_all (GHashTable *hash_table); void g_hash_table_remove_all (GHashTable *hash_table);
gboolean g_hash_table_steal (GHashTable *hash_table, gboolean g_hash_table_steal (GHashTable *hash_table,
gconstpointer key); gconstpointer key);
void g_hash_table_steal_all (GHashTable *hash_table); void g_hash_table_steal_all (GHashTable *hash_table);
gpointer g_hash_table_lookup (GHashTable *hash_table, gpointer g_hash_table_lookup (GHashTable *hash_table,
gconstpointer key); gconstpointer key);
gboolean g_hash_table_lookup_extended (GHashTable *hash_table, gboolean g_hash_table_lookup_extended (GHashTable *hash_table,
gconstpointer lookup_key, gconstpointer lookup_key,
gpointer *orig_key, gpointer *orig_key,
gpointer *value); gpointer *value);
void g_hash_table_foreach (GHashTable *hash_table, void g_hash_table_foreach (GHashTable *hash_table,
GHFunc func, GHFunc func,
gpointer user_data); gpointer user_data);
gpointer g_hash_table_find (GHashTable *hash_table, gpointer g_hash_table_find (GHashTable *hash_table,
GHRFunc predicate, GHRFunc predicate,
gpointer user_data); gpointer user_data);
guint g_hash_table_foreach_remove (GHashTable *hash_table, guint g_hash_table_foreach_remove (GHashTable *hash_table,
GHRFunc func, GHRFunc func,
gpointer user_data); gpointer user_data);
guint g_hash_table_foreach_steal (GHashTable *hash_table, guint g_hash_table_foreach_steal (GHashTable *hash_table,
GHRFunc func, GHRFunc func,
gpointer user_data); gpointer user_data);
guint g_hash_table_size (GHashTable *hash_table); guint g_hash_table_size (GHashTable *hash_table);
GList * g_hash_table_get_keys (GHashTable *hash_table); GList * g_hash_table_get_keys (GHashTable *hash_table);
GList * g_hash_table_get_values (GHashTable *hash_table); GList * g_hash_table_get_values (GHashTable *hash_table);
void g_hash_table_iter_init (GHashTableIter *iter, void g_hash_table_iter_init (GHashTableIter *iter,
GHashTable *hash_table); GHashTable *hash_table);
gboolean g_hash_table_iter_next (GHashTableIter *iter, gboolean g_hash_table_iter_next (GHashTableIter *iter,
gpointer *key, gpointer *key,
gpointer *value); gpointer *value);
GHashTable* g_hash_table_iter_get_hash_table (GHashTableIter *iter); GHashTable* g_hash_table_iter_get_hash_table (GHashTableIter *iter);
void g_hash_table_iter_remove (GHashTableIter *iter); void g_hash_table_iter_remove (GHashTableIter *iter);
void g_hash_table_iter_replace (GHashTableIter *iter, void g_hash_table_iter_replace (GHashTableIter *iter,
gpointer value); gpointer value);
void g_hash_table_iter_steal (GHashTableIter *iter); void g_hash_table_iter_steal (GHashTableIter *iter);
/* keeping hash tables alive */ GHashTable* g_hash_table_ref (GHashTable *hash_table);
GHashTable* g_hash_table_ref (GHashTable *hash_table);
void g_hash_table_unref (GHashTable *hash_table); void g_hash_table_unref (GHashTable *hash_table);
#ifndef G_DISABLE_DEPRECATED #ifndef G_DISABLE_DEPRECATED
/**
* g_hash_table_freeze:
* @hash_table: a #GHashTable
*
* This function is deprecated and will be removed in the next major
* release of GLib. It does nothing.
**/
#define g_hash_table_freeze(hash_table) ((void)0) #define g_hash_table_freeze(hash_table) ((void)0)
/**
* g_hash_table_thaw:
* @hash_table: a #GHashTable
*
* This function is deprecated and will be removed in the next major
* release of GLib. It does nothing.
**/
#define g_hash_table_thaw(hash_table) ((void)0) #define g_hash_table_thaw(hash_table) ((void)0)
#endif /* G_DISABLE_DEPRECATED */ #endif /* G_DISABLE_DEPRECATED */
/* Hash Functions /* Hash Functions
*/ */
gboolean g_str_equal (gconstpointer v1, gboolean g_str_equal (gconstpointer v1,
gconstpointer v2); gconstpointer v2);
guint g_str_hash (gconstpointer v); guint g_str_hash (gconstpointer v);
gboolean g_int_equal (gconstpointer v1, gboolean g_int_equal (gconstpointer v1,
gconstpointer v2); gconstpointer v2);
guint g_int_hash (gconstpointer v); guint g_int_hash (gconstpointer v);
gboolean g_int64_equal (gconstpointer v1, gboolean g_int64_equal (gconstpointer v1,
gconstpointer v2); gconstpointer v2);
guint g_int64_hash (gconstpointer v); guint g_int64_hash (gconstpointer v);
gboolean g_double_equal (gconstpointer v1, gboolean g_double_equal (gconstpointer v1,
gconstpointer v2); gconstpointer v2);
guint g_double_hash (gconstpointer v); guint g_double_hash (gconstpointer v);
/* This "hash" function will just return the key's address as an
* unsigned integer. Useful for hashing on plain addresses or
* simple integer values.
* Passing NULL into g_hash_table_new() as GHashFunc has the
* same effect as passing g_direct_hash().
*/
guint g_direct_hash (gconstpointer v) G_GNUC_CONST; guint g_direct_hash (gconstpointer v) G_GNUC_CONST;
gboolean g_direct_equal (gconstpointer v1, gboolean g_direct_equal (gconstpointer v1,
gconstpointer v2) G_GNUC_CONST; gconstpointer v2) G_GNUC_CONST;