From c73d2818432956aaedb12886ea0011847b7d030e Mon Sep 17 00:00:00 2001 From: Ryan Lortie Date: Thu, 28 Jan 2010 22:36:48 -0500 Subject: [PATCH] GHash: move docs from tmpl to inline comments --- docs/reference/glib/tmpl/.gitignore | 1 + docs/reference/glib/tmpl/hash_tables.sgml | 489 ------------------------------ glib/ghash.c | 114 +++++++ glib/ghash.h | 17 +- 4 files changed, 130 insertions(+), 491 deletions(-) delete mode 100644 docs/reference/glib/tmpl/hash_tables.sgml diff --git a/docs/reference/glib/tmpl/.gitignore b/docs/reference/glib/tmpl/.gitignore index ed6b3d2..b95a0a9 100644 --- a/docs/reference/glib/tmpl/.gitignore +++ b/docs/reference/glib/tmpl/.gitignore @@ -2,4 +2,5 @@ base64.sgml ghostutils.sgml gurifuncs.sgml gvarianttype.sgml +hash_tables.sgml option.sgml diff --git a/docs/reference/glib/tmpl/hash_tables.sgml b/docs/reference/glib/tmpl/hash_tables.sgml deleted file mode 100644 index 2fa2c86..0000000 --- a/docs/reference/glib/tmpl/hash_tables.sgml +++ /dev/null @@ -1,489 +0,0 @@ - -Hash Tables - - -associations between keys and values so that given a key the value -can be found quickly - - - -A #GHashTable provides associations between keys and values which -is optimized so that given a key, the associated value can be found -very quickly. - - -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. - - -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. - - -To create a #GHashTable, use g_hash_table_new(). - - -To insert a key and value into a #GHashTable, use g_hash_table_insert(). - - -To lookup a value corresponding to a given key, use g_hash_table_lookup() -and g_hash_table_lookup_extended(). - - -To remove a key and value, use g_hash_table_remove(). - - -To call a function for each key and value pair use g_hash_table_foreach() -or use a iterator to iterate over the key/value pairs in the hash table, see -#GHashTableIter. - - -To destroy a #GHashTable use g_hash_table_destroy(). - - - - - - - - - - - - -The GHashTable struct is an opaque data structure to represent a -Hash Table. -It should only be accessed via the following functions. - - - - - - - - -@hash_func: -@key_equal_func: -@Returns: - - - - - - - -@hash_func: -@key_equal_func: -@key_destroy_func: -@value_destroy_func: -@Returns: - - - - -Specifies the type of the hash function which is passed to -g_hash_table_new() when a #GHashTable is created. - - -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. - - - -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. - - -@key: a key. -@Returns: the hash value corresponding to the key. - - - - -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. - - -@a: a value. -@b: a value to compare with. -@Returns: %TRUE if @a = @b; %FALSE otherwise. - - - - - - - -@hash_table: -@key: -@value: - - - - - - - -@hash_table: -@key: -@value: - - - - - - - -@hash_table: -@Returns: - - - - - - - -@hash_table: -@key: -@Returns: - - - - - - - -@hash_table: -@lookup_key: -@orig_key: -@value: -@Returns: - - - - - - - -@hash_table: -@func: -@user_data: - - - - - - - -@hash_table: -@predicate: -@user_data: -@Returns: - - - - -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(). - - -@key: a key. -@value: the value corresponding to the key. -@user_data: user data passed to g_hash_table_foreach(). - - - - - - - -@hash_table: -@key: -@Returns: - - - - - - - -@hash_table: -@key: -@Returns: - - - - - - - -@hash_table: -@func: -@user_data: -@Returns: - - - - - - - -@hash_table: -@func: -@user_data: -@Returns: - - - - - - - -@hash_table: - - - - - - - -@hash_table: - - - - - - - -@hash_table: -@Returns: - - - - - - - -@hash_table: -@Returns: - - - - -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. - - -@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. - - - - -This function is deprecated and will be removed in the next major - release of GLib. It does nothing. - - -@hash_table: a #GHashTable - - - - -This function is deprecated and will be removed in the next major - release of GLib. It does nothing. - - -@hash_table: a #GHashTable - - - - - - - -@hash_table: - - - - - - - -@hash_table: -@Returns: - - - - - - - -@hash_table: - - - - -A GHashTableIter structure represents an iterator that can be -used to iterate over the elements of a #GHashTable. GHashTableIter -structures are typically allocated on the stack and then initialized -with g_hash_table_iter_init(). - - - - - - - - -@iter: -@hash_table: - - - - - - - -@iter: -@key: -@value: -@Returns: - - - - - - - -@iter: -@Returns: - - - - - - - -@iter: - - - - - - - -@iter: - - - - - - - -@v1: -@v2: -@Returns: - - - - - - - -@v: -@Returns: - - - - - - - -@v1: -@v2: -@Returns: - - - - - - - -@v: -@Returns: - - - - - - - -@v1: -@v2: -@Returns: - - - - - - - -@v: -@Returns: - - - - - - - -@v1: -@v2: -@Returns: - - - - - - - -@v: -@Returns: - - - - - - -@v1: -@v2: -@Returns: - - - - - - -@v: -@Returns: - - diff --git a/glib/ghash.c b/glib/ghash.c index 820d095..f8c2936 100644 --- a/glib/ghash.c +++ b/glib/ghash.c @@ -35,6 +35,120 @@ #include "glib.h" #include "galias.h" +/** + * SECTION: hash_tables + * @title: Hash Tables + * @short_description: associations between keys and values so that + * given a key the value can be found quickly + * + * A #GHashTable provides associations between keys and values which is + * optimized so that given a key, the associated value can be found + * very quickly. + * + * 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. + * + * 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. + * + * To create a #GHashTable, use g_hash_table_new(). + * + * To insert a key and value into a #GHashTable, use + * g_hash_table_insert(). + * + * To lookup a value corresponding to a given key, use + * g_hash_table_lookup() and g_hash_table_lookup_extended(). + * + * To remove a key and value, use g_hash_table_remove(). + * + * To call a function for each key and value pair use + * g_hash_table_foreach() or use a iterator to iterate over the + * key/value pairs in the hash table, see #GHashTableIter. + * + * To destroy a #GHashTable use g_hash_table_destroy(). + **/ + +/** + * GHashTable: + * + * The #GHashTable struct is an opaque data structure to represent a + * Hash Table. It should only be + * accessed via the following functions. + **/ + +/** + * GHashFunc: + * @key: a key. + * @Returns: the hash value corresponding to the key. + * + * Specifies the type of the hash function which is passed to + * g_hash_table_new() when a #GHashTable is created. + * + * 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. + * + * 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. + **/ + +/** + * GHFunc: + * @key: a key. + * @value: the value corresponding to the key. + * @user_data: user data 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 + * parameter which is passed to g_hash_table_foreach(). + **/ + +/** + * GHRFunc: + * @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. + * + * 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. + **/ + +/** + * GEqualFunc: + * @a: a value. + * @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 + * equality. The function should return %TRUE if both values are equal + * and %FALSE otherwise. + **/ + +/** + * GHashTableIter: + * + * A GHashTableIter structure represents an iterator that can be used + * to iterate over the elements of a #GHashTable. GHashTableIter + * structures are typically allocated on the stack and then initialized + * with g_hash_table_iter_init(). + **/ + #define HASH_TABLE_MIN_SHIFT 3 /* 1 << 3 == 8 buckets */ typedef struct _GHashNode GHashNode; diff --git a/glib/ghash.h b/glib/ghash.h index 7f1e79e..9128721 100644 --- a/glib/ghash.h +++ b/glib/ghash.h @@ -113,9 +113,22 @@ void g_hash_table_unref (GHashTable *hash_table); #ifndef G_DISABLE_DEPRECATED -/* The following two functions are deprecated and will be removed in - * the next major release. They do no good. */ +/** + * 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) + +/** + * 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) #endif /* G_DISABLE_DEPRECATED */ -- 2.7.4