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 or use a iterator to iterate over the key/value pairs in the hash table, see
  45 #GHashTableIter.
  46 </para>
  47 <para>
  48 To destroy a #GHashTable use g_hash_table_destroy().
  49 </para>
  50
  51 <!-- ##### SECTION See_Also ##### -->
  52 <para>
  53
  54 </para>
  55
  56 <!-- ##### SECTION Stability_Level ##### -->
  57
  58
  59 <!-- ##### STRUCT GHashTable ##### -->
  60 <para>
  61 The <structname>GHashTable</structname> struct is an opaque data structure to represent a
  62 <link linkend="glib-Hash-Tables">Hash Table</link>.
  63 It should only be accessed via the following functions.
  64 </para>
  65
  66
  67 <!-- ##### FUNCTION g_hash_table_new ##### -->
  68 <para>
  69
  70 </para>
  71
  72 @hash_func:
  73 @key_equal_func:
  74 @Returns:
  75
  76
  77 <!-- ##### FUNCTION g_hash_table_new_full ##### -->
  78 <para>
  79
  80 </para>
  81
  82 @hash_func:
  83 @key_equal_func:
  84 @key_destroy_func:
  85 @value_destroy_func:
  86 @Returns:
  87
  88
  89 <!-- ##### USER_FUNCTION GHashFunc ##### -->
  90 <para>
  91 Specifies the type of the hash function which is passed to
  92 g_hash_table_new() when a #GHashTable is created.
  93 </para>
  94 <para>
  95 The function is passed a key and should return a #guint hash value.
  96 The functions g_direct_hash(), g_int_hash() and g_str_hash() provide
  97 hash functions which can be used when the key is a #gpointer, #gint, and
  98 #gchar* respectively.
  99 </para>
 100 <para>
 101 <!-- FIXME: Need more here. -->
 102 The hash values should be evenly distributed over a fairly large range?
 103 The modulus is taken with the hash table size (a prime number)
 104 to find the 'bucket' to place each key into.
 105 The function should also be very fast, since it is called for each key
 106 lookup.
 107 </para>
 108
 109 @key: a key.
 110 @Returns: the hash value corresponding to the key.
 111
 112
 113 <!-- ##### USER_FUNCTION GEqualFunc ##### -->
 114 <para>
 115 Specifies the type of a function used to test two values for
 116 equality. The function should return %TRUE if both values are equal and
 117 %FALSE otherwise.
 118 </para>
 119
 120 @a: a value.
 121 @b: a value to compare with.
 122 @Returns: %TRUE if @a = @b; %FALSE otherwise.
 123
 124
 125 <!-- ##### FUNCTION g_hash_table_insert ##### -->
 126 <para>
 127
 128 </para>
 129
 130 @hash_table:
 131 @key:
 132 @value:
 133
 134
 135 <!-- ##### FUNCTION g_hash_table_replace ##### -->
 136 <para>
 137
 138 </para>
 139
 140 @hash_table:
 141 @key:
 142 @value:
 143
 144
 145 <!-- ##### FUNCTION g_hash_table_size ##### -->
 146 <para>
 147
 148 </para>
 149
 150 @hash_table:
 151 @Returns:
 152
 153
 154 <!-- ##### FUNCTION g_hash_table_lookup ##### -->
 155 <para>
 156
 157 </para>
 158
 159 @hash_table:
 160 @key:
 161 @Returns:
 162
 163
 164 <!-- ##### FUNCTION g_hash_table_lookup_extended ##### -->
 165 <para>
 166
 167 </para>
 168
 169 @hash_table:
 170 @lookup_key:
 171 @orig_key:
 172 @value:
 173 @Returns:
 174
 175
 176 <!-- ##### FUNCTION g_hash_table_foreach ##### -->
 177 <para>
 178
 179 </para>
 180
 181 @hash_table:
 182 @func:
 183 @user_data:
 184
 185
 186 <!-- ##### FUNCTION g_hash_table_find ##### -->
 187 <para>
 188
 189 </para>
 190
 191 @hash_table:
 192 @predicate:
 193 @user_data:
 194 @Returns:
 195
 196
 197 <!-- ##### USER_FUNCTION GHFunc ##### -->
 198 <para>
 199 Specifies the type of the function passed to g_hash_table_foreach().
 200 It is called with each key/value pair, together with the @user_data parameter
 201 which is passed to g_hash_table_foreach().
 202 </para>
 203
 204 @key: a key.
 205 @value: the value corresponding to the key.
 206 @user_data: user data passed to g_hash_table_foreach().
 207
 208
 209 <!-- ##### FUNCTION g_hash_table_remove ##### -->
 210 <para>
 211
 212 </para>
 213
 214 @hash_table:
 215 @key:
 216 @Returns:
 217
 218
 219 <!-- ##### FUNCTION g_hash_table_steal ##### -->
 220 <para>
 221
 222 </para>
 223
 224 @hash_table:
 225 @key:
 226 @Returns:
 227
 228
 229 <!-- ##### FUNCTION g_hash_table_foreach_remove ##### -->
 230 <para>
 231
 232 </para>
 233
 234 @hash_table:
 235 @func:
 236 @user_data:
 237 @Returns:
 238
 239
 240 <!-- ##### FUNCTION g_hash_table_foreach_steal ##### -->
 241 <para>
 242
 243 </para>
 244
 245 @hash_table:
 246 @func:
 247 @user_data:
 248 @Returns:
 249
 250
 251 <!-- ##### FUNCTION g_hash_table_remove_all ##### -->
 252 <para>
 253
 254 </para>
 255
 256 @hash_table:
 257
 258
 259 <!-- ##### FUNCTION g_hash_table_steal_all ##### -->
 260 <para>
 261
 262 </para>
 263
 264 @hash_table:
 265
 266
 267 <!-- ##### FUNCTION g_hash_table_get_keys ##### -->
 268 <para>
 269
 270 </para>
 271
 272 @hash_table:
 273 @Returns:
 274
 275
 276 <!-- ##### FUNCTION g_hash_table_get_values ##### -->
 277 <para>
 278
 279 </para>
 280
 281 @hash_table:
 282 @Returns:
 283
 284
 285 <!-- ##### USER_FUNCTION GHRFunc ##### -->
 286 <para>
 287 Specifies the type of the function passed to g_hash_table_foreach_remove().
 288 It is called with each key/value pair, together with the @user_data parameter
 289 passed to g_hash_table_foreach_remove().
 290 It should return %TRUE if the key/value pair should be removed from the
 291 #GHashTable.
 292 </para>
 293
 294 @key: a key.
 295 @value: the value associated with the key.
 296 @user_data: user data passed to g_hash_table_remove().
 297 @Returns: %TRUE if the key/value pair should be removed from the #GHashTable.
 298
 299
 300 <!-- ##### MACRO g_hash_table_freeze ##### -->
 301 <para>
 302 This function is deprecated and will be removed in the next major
 303  release of GLib. It does nothing.
 304 </para>
 305
 306 @hash_table: a #GHashTable
 307
 308
 309 <!-- ##### MACRO g_hash_table_thaw ##### -->
 310 <para>
 311 This function is deprecated and will be removed in the next major
 312  release of GLib. It does nothing.
 313 </para>
 314
 315 @hash_table: a #GHashTable
 316
 317
 318 <!-- ##### FUNCTION g_hash_table_destroy ##### -->
 319 <para>
 320
 321 </para>
 322
 323 @hash_table:
 324
 325
 326 <!-- ##### FUNCTION g_hash_table_ref ##### -->
 327 <para>
 328
 329 </para>
 330
 331 @hash_table:
 332 @Returns:
 333
 334
 335 <!-- ##### FUNCTION g_hash_table_unref ##### -->
 336 <para>
 337
 338 </para>
 339
 340 @hash_table:
 341
 342
 343 <!-- ##### STRUCT GHashTableIter ##### -->
 344 <para>
 345 A GHashTableIter structure represents an iterator that can be
 346 used to iterate over the elements of a #GHashTable. GHashTableIter
 347 structures are typically allocated on the stack and then initialized
 348 with g_hash_table_iter_init().
 349 </para>
 350
 351
 352 <!-- ##### FUNCTION g_hash_table_iter_init ##### -->
 353 <para>
 354
 355 </para>
 356
 357 @iter:
 358 @hash_table:
 359
 360
 361 <!-- ##### FUNCTION g_hash_table_iter_next ##### -->
 362 <para>
 363
 364 </para>
 365
 366 @iter:
 367 @key:
 368 @value:
 369 @Returns:
 370
 371
 372 <!-- ##### FUNCTION g_hash_table_iter_get_hash_table ##### -->
 373 <para>
 374
 375 </para>
 376
 377 @iter:
 378 @Returns:
 379
 380
 381 <!-- ##### FUNCTION g_hash_table_iter_remove ##### -->
 382 <para>
 383
 384 </para>
 385
 386 @iter:
 387
 388
 389 <!-- ##### FUNCTION g_hash_table_iter_steal ##### -->
 390 <para>
 391
 392 </para>
 393
 394 @iter:
 395
 396
 397 <!-- ##### FUNCTION g_direct_equal ##### -->
 398 <para>
 399
 400 </para>
 401
 402 @v1:
 403 @v2:
 404 @Returns:
 405
 406
 407 <!-- ##### FUNCTION g_direct_hash ##### -->
 408 <para>
 409
 410 </para>
 411
 412 @v:
 413 @Returns:
 414
 415
 416 <!-- ##### FUNCTION g_int_equal ##### -->
 417 <para>
 418
 419 </para>
 420
 421 @v1:
 422 @v2:
 423 @Returns:
 424
 425
 426 <!-- ##### FUNCTION g_int_hash ##### -->
 427 <para>
 428
 429 </para>
 430
 431 @v:
 432 @Returns:
 433
 434
 435 <!-- ##### FUNCTION g_int64_equal ##### -->
 436 <para>
 437
 438 </para>
 439
 440 @v1:
 441 @v2:
 442 @Returns:
 443
 444
 445 <!-- ##### FUNCTION g_int64_hash ##### -->
 446 <para>
 447
 448 </para>
 449
 450 @v:
 451 @Returns:
 452
 453
 454 <!-- ##### FUNCTION g_double_equal ##### -->
 455 <para>
 456
 457 </para>
 458
 459 @v1:
 460 @v2:
 461 @Returns:
 462
 463
 464 <!-- ##### FUNCTION g_double_hash ##### -->
 465 <para>
 466
 467 </para>
 468
 469 @v:
 470 @Returns:
 471
 472
 473 <!-- ##### FUNCTION g_str_equal ##### -->
 474 <para>
 475 </para>
 476
 477 @v1:
 478 @v2:
 479 @Returns:
 480
 481
 482 <!-- ##### FUNCTION g_str_hash ##### -->
 483 <para>
 484 </para>
 485
 486 @v:
 487 @Returns:
 488
 489