GHashTable: be more clear what g_int_hash wants

Using g_int_hash, g_int_equal with keys like GINT_TO_POINTER (n) seems to
be a reasonably common GLib-novice mistake. It doesn't help that the
documentation for GHashFunc was ambiguous about this.

Bug: https://bugzilla.gnome.org/show_bug.cgi?id=592715
Signed-off-by: Simon McVittie <simon.mcvittie@collabora.co.uk>
Reviewed-by: Colin Walters <walters@verbum.org>
This commit is contained in:
Simon McVittie 2011-10-04 09:42:28 +01:00
parent 5bed8317ea
commit 06c96ab1e5

View File

@ -142,9 +142,12 @@
*
* 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,
* hash functions which can be used when the key is a #gpointer, #gint*,
* and #gchar* respectively.
*
* g_direct_hash() is also the appropriate hash function for keys
* of the form <literal>GINT_TO_POINTER (n)</literal> (or similar macros).
*
* <!-- 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
@ -1697,6 +1700,10 @@ g_direct_equal (gconstpointer v1,
* It can be passed to g_hash_table_new() as the @key_equal_func
* parameter, when using pointers to integers as keys in a #HashTable.
*
* Note that this function acts on pointers to #gint, not on #gint directly:
* if your hash table's keys are of the form
* <literal>GINT_TO_POINTER (n)</literal>, use g_direct_equal() instead.
*
* Returns: %TRUE if the two keys match.
*/
gboolean
@ -1714,6 +1721,10 @@ g_int_equal (gconstpointer v1,
* 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.
*
* Note that this function acts on pointers to #gint, not on #gint directly:
* if your hash table's keys are of the form
* <literal>GINT_TO_POINTER (n)</literal>, use g_direct_hash() instead.
*
* Returns: a hash value corresponding to the key.
*/
guint