docs/reference/glib/tmpl/hash_tables.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Hash Tables
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 associations between keys and values so that given a key the value
   6 can be found quickly.
   7
   8 <!-- ##### SECTION Long_Description ##### -->
   9 <para>
  10 A #GHashTable provides associations between keys and values which
  11 is optimized so that given a key, the associated value can be found
  12 very quickly.
  13 </para>
  14 <para>
  15 Note that neither keys nor values are copied when inserted into the
  16 #GHashTable, so they must exist for the lifetime of the #GHashTable.
  17 This means that the use of static strings is OK, but temporary
  18 strings (i.e. those created in buffers and those returned by GTK widgets)
  19 should be copied with g_strdup() before being inserted.
  20 </para>
  21 <para>
  22 If keys or values are dynamically allocated, you must be careful to ensure
  23 that they are freed when they are removed from the #GHashTable, and also
  24 when they are overwritten by new insertions into the #GHashTable.
  25 It is also not advisable to mix static strings and dynamically-allocated
  26 strings in a #GHashTable, because it then becomes difficult to determine
  27 whether the string should be freed.
  28 </para>
  29 <para>
  30 To create a #GHashTable, use g_hash_table_new().
  31 </para>
  32 <para>
  33 To insert a key and value into a #GHashTable, use g_hash_table_insert().
  34 </para>
  35 <para>
  36 To lookup a value corresponding to a given key, use g_hash_table_lookup()
  37 and g_hash_table_lookup_extended().
  38 </para>
  39 <para>
  40 To remove a key and value, use g_hash_table_remove().
  41 </para>
  42 <para>
  43 To call a function for each key and value pair use g_hash_table_foreach().
  44 </para>
  45 <para>
  46 To destroy a #GHashTable use g_hash_table_destroy().
  47 </para>
  48
  49 <!-- ##### SECTION See_Also ##### -->
  50 <para>
  51
  52 </para>
  53
  54 <!-- ##### STRUCT GHashTable ##### -->
  55 <para>
  56 The #GHashTable struct is an opaque data structure to represent a
  57 <link linkend="glib-Hash-Tables">Hash Table</link>.
  58 It should only be accessed via the following functions.
  59 </para>
  60
  61
  62 <!-- ##### FUNCTION g_hash_table_new ##### -->
  63 <para>
  64 Creates a new #GHashTable.
  65 </para>
  66
  67 @hash_func: a function to create a hash value from a key.
  68 Hash values are used to determine where keys are stored within the
  69 #GHashTable data structure.
  70 The g_direct_hash(), g_int_hash() and g_str_hash() functions are provided for
  71 some common types of keys. If hash_func is NULL, g_direct_hash() is used.
  72 @key_compare_func: a function to compare two keys to see if they are equal.
  73 This is used when looking up keys in the #GHashTable.
  74 The g_direct_equal(), g_int_equal() and g_str_equal() functions are provided
  75 for the most common types of keys. If compare_func is NULL, keys are compared
  76 directly in a similar fashion to g_direct_equal(), but without the overhead
  77 of a function call.
  78 @Returns: a new #GHashTable.
  79
  80
  81 <!-- ##### USER_FUNCTION GHashFunc ##### -->
  82 <para>
  83 Specifies the type of the hash function which is passed to
  84 g_hash_table_new() when a #GHashTable is created.
  85 </para>
  86 <para>
  87 The function is passed a key and should return a guint hash value.
  88 The functions g_direct_hash(), g_int_hash() and g_str_hash() provide
  89 hash functions which can be used when the key is a #gpointer, #gint, and
  90 #gchar* respectively.
  91 </para>
  92 <para>
  93 FIXME: Need more here.
  94 The hash values should be evenly distributed over a fairly large range?
  95 The modulus is taken with the hash table size (a prime number)
  96 to find the 'bucket' to place each key into.
  97 The function should also be very fast, since it is called for each key
  98 lookup.
  99 </para>
 100
 101 @key: a key.
 102 @Returns: the hash value corresponding to the key.
 103
 104
 105 <!-- ##### USER_FUNCTION GCompareFunc ##### -->
 106 <para>
 107 Specifies the type of a comparison function used to compare two values.
 108 The value which should be returned depends on the context in which the
 109 #GCompareFunc is used.
 110 </para>
 111 <para>
 112 In g_hash_table_new(), g_cache_new(), and g_relation_index() the function
 113 should return TRUE if the two parameters are equal, or FALSE if they are not.
 114 </para>
 115 <para>
 116 In g_list_find_custom() and g_slist_find_custom() the function should return
 117 0 if the two parameters are equal.
 118 </para>
 119 <para>
 120 In g_list_insert_sorted(), g_list_sort(), g_slist_insert_sorted(),
 121 g_slist_sort() and g_tree_new()  the function should return a negative integer
 122 if the first value comes before the second, 0 if they are equal, or a positive
 123 integer if the first value comes after the second.
 124 </para>
 125
 126 @a: a value.
 127 @b: a value to compare with.
 128 @Returns: TRUE if the two values are equivalent.
 129
 130
 131 <!-- ##### FUNCTION g_hash_table_insert ##### -->
 132 <para>
 133 Inserts a new key and value into a #GHashTable.
 134 If the key already exists in the #GHashTable its current value is replaced
 135 with the new value.
 136 </para>
 137 <note>
 138 <para>
 139 If the keys or values use dynamically allocated memory, then you should
 140 first check if the key already exists in the GHashTable. If it does,
 141 you should free the existing key and/or value before inserting the
 142 new key and value.
 143 </para>
 144 </note>
 145
 146 @hash_table: a #GHashTable.
 147 @key: a key to insert.
 148 @value: the value to associate with the key.
 149
 150
 151 <!-- ##### FUNCTION g_hash_table_size ##### -->
 152 <para>
 153 Returns the number of key/value pairs in a #GHashTable.
 154 </para>
 155
 156 @hash_table: a #GHashTable.
 157 @Returns: the number of key/value pairs in the #GHashTable.
 158
 159
 160 <!-- ##### FUNCTION g_hash_table_lookup ##### -->
 161 <para>
 162 Looks up a key in the #GHashTable, returning the associated value or NULL
 163 if the key is not found.
 164 </para>
 165
 166 @hash_table: a #GHashTable.
 167 @key: the key to look up.
 168 @Returns: the associated value, or NULL if the key is not found.
 169
 170
 171 <!-- ##### FUNCTION g_hash_table_lookup_extended ##### -->
 172 <para>
 173 Looks up a key in the #GHashTable, returning the original key and the
 174 associated value and a gboolean which is TRUE if the key was found.
 175 This is useful if you need to free the memory allocated for the
 176 original key, for example before calling g_hash_table_remove().
 177 </para>
 178
 179 @hash_table: a #GHashTable.
 180 @lookup_key: the key to look up.
 181 @orig_key: returns the original key.
 182 @value: returns the value associated with the key.
 183 @Returns: TRUE if the key was found in the #GHashTable.
 184
 185
 186 <!-- ##### FUNCTION g_hash_table_foreach ##### -->
 187 <para>
 188 Calls the given function for each of the key/value pairs in the #GHashTable.
 189 The function is passed the key and value of each pair, and the given
 190 @user_data parameter.
 191 </para>
 192
 193 @hash_table: a #GHashTable.
 194 @func: the function to call for each key/value pair.
 195 @user_data: use data to pass to the function.
 196
 197
 198 <!-- ##### USER_FUNCTION GHFunc ##### -->
 199 <para>
 200 Specifies the type of the function passed to g_hash_table_foreach().
 201 It is called with each key/value pair, together with the @user_data parameter
 202 which is passed to g_hash_table_foreach().
 203 </para>
 204
 205 @key: a key.
 206 @value: the value corresponding to the key.
 207 @user_data: user data passed to g_hash_table_foreach().
 208
 209
 210 <!-- ##### FUNCTION g_hash_table_remove ##### -->
 211 <para>
 212 Removes a key and its associated value from a #GHashTable.
 213 </para>
 214 <note>
 215 <para>
 216 As with g_hash_table_insert(), you should make sure that any dynamically
 217 allocated values are freed yourself.
 218 </para>
 219 </note>
 220
 221 @hash_table: a #GHashTable.
 222 @key: the key to remove.
 223
 224
 225 <!-- ##### FUNCTION g_hash_table_foreach_remove ##### -->
 226 <para>
 227 Calls the given function for each key/value pair in the #GHashTable.
 228 If the function returns TRUE, then the key/value pair is removed from the
 229 #GHashTable.
 230 </para>
 231
 232 @hash_table: a #GHashTable.
 233 @func: the function to call for each key/value pair.
 234 @user_data: user data to pass to the function.
 235 @Returns: the number of key/value paris removed.
 236
 237
 238 <!-- ##### USER_FUNCTION GHRFunc ##### -->
 239 <para>
 240 Specifies the type of the function passed to g_hash_table_foreach_remove().
 241 It is called with each key/value pair, together with the @user_data parameter
 242 passed to g_hash_table_foreach_remove().
 243 It should return TRUE if the key/value pair should be removed from the
 244 #GHashTable.
 245 </para>
 246
 247 @key: a key.
 248 @value: the value associated with the key.
 249 @user_data: user data passed to g_hash_table_remove().
 250 @Returns: TRUE if the key/value pair should be removed from the #GHashTable.
 251
 252
 253 <!-- ##### FUNCTION g_hash_table_freeze ##### -->
 254 <para>
 255 This function is deprecated and will be removed in the next major
 256 release of GLib. It does nothing.
 257 </para>
 258
 259 @hash_table:
 260
 261
 262 <!-- ##### FUNCTION g_hash_table_thaw ##### -->
 263 <para>
 264 This function is deprecated and will be removed in the next major
 265 release of GLib. It does nothing.
 266 </para>
 267
 268 @hash_table:
 269
 270
 271 <!-- ##### FUNCTION g_hash_table_destroy ##### -->
 272 <para>
 273 Destroys the #GHashTable.
 274 </para>
 275 <note>
 276 <para>
 277 If keys and/or values are dynamically allocated, you should free them
 278 first.
 279 </para>
 280 </note>
 281
 282 @hash_table: a #GHashTable.
 283
 284
 285 <!-- ##### FUNCTION g_direct_equal ##### -->
 286 <para>
 287 Compares two #gpointer arguments and returns TRUE if they are equal.
 288 It can be passed to g_hash_table_new() as the @key_compare_func
 289 parameter, when using pointers as keys in a #GHashTable.
 290 </para>
 291
 292 @v: a key.
 293 @v2: a key to compare with @v.
 294 @Returns: TRUE if the two keys match.
 295
 296
 297 <!-- ##### FUNCTION g_direct_hash ##### -->
 298 <para>
 299 Converts a gpointer to a hash value.
 300 It can be passed to g_hash_table_new() as the @hash_func parameter, when
 301 using gpointer values as keys in a #GHashTable.
 302 </para>
 303
 304 @v: a gpointer key.
 305 @Returns: a hash value corresponding to the key.
 306
 307
 308 <!-- ##### FUNCTION g_int_equal ##### -->
 309 <para>
 310 Compares the two #gint values being pointed to and returns TRUE if they are
 311 equal.
 312 It can be passed to g_hash_table_new() as the @key_compare_func
 313 parameter, when using pointers to integers as keys in a #GHashTable.
 314 </para>
 315
 316 @v: a pointer to a #gint key.
 317 @v2: a pointer to a #gint key to compare with @v.
 318 @Returns: TRUE if the two keys match.
 319
 320
 321 <!-- ##### FUNCTION g_int_hash ##### -->
 322 <para>
 323 Converts a pointer to a #gint to a hash value.
 324 It can be passed to g_hash_table_new() as the @hash_func parameter, when
 325 using pointers to gint values as keys in a #GHashTable.
 326 </para>
 327
 328 @v: a pointer to a #gint key.
 329 @Returns: a hash value corresponding to the key.
 330
 331
 332 <!-- ##### FUNCTION g_str_equal ##### -->
 333 <para>
 334 Compares two strings and returns TRUE if they are equal.
 335 It can be passed to g_hash_table_new() as the @key_compare_func
 336 parameter, when using strings as keys in a #GHashTable.
 337 </para>
 338
 339 @v: a key.
 340 @v2: a key to compare with @v.
 341 @Returns: TRUE if the two keys match.
 342
 343
 344 <!-- ##### FUNCTION g_str_hash ##### -->
 345 <para>
 346 Converts a string to a hash value.
 347 It can be passed to g_hash_table_new() as the @hash_func parameter, when
 348 using strings as keys in a #GHashTable.
 349 </para>
 350
 351 @v: a string key.
 352 @Returns: a hash value corresponding to the key.
 353
 354