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 <!-- ##### SECTION Stability_Level ##### -->
  55
  56
  57 <!-- ##### STRUCT GHashTable ##### -->
  58 <para>
  59 The <structname>GHashTable</structname> struct is an opaque data structure to represent a
  60 <link linkend="glib-Hash-Tables">Hash Table</link>.
  61 It should only be accessed via the following functions.
  62 </para>
  63
  64
  65 <!-- ##### FUNCTION g_hash_table_new ##### -->
  66 <para>
  67
  68 </para>
  69
  70 @hash_func:
  71 @key_equal_func:
  72 @Returns:
  73
  74
  75 <!-- ##### FUNCTION g_hash_table_new_full ##### -->
  76 <para>
  77
  78 </para>
  79
  80 @hash_func:
  81 @key_equal_func:
  82 @key_destroy_func:
  83 @value_destroy_func:
  84 @Returns:
  85
  86
  87 <!-- ##### USER_FUNCTION GHashFunc ##### -->
  88 <para>
  89 Specifies the type of the hash function which is passed to
  90 g_hash_table_new() when a #GHashTable is created.
  91 </para>
  92 <para>
  93 The function is passed a key and should return a #guint hash value.
  94 The functions g_direct_hash(), g_int_hash() and g_str_hash() provide
  95 hash functions which can be used when the key is a #gpointer, #gint, and
  96 #gchar* respectively.
  97 </para>
  98 <para>
  99 FIXME: Need more here.
 100 The hash values should be evenly distributed over a fairly large range?
 101 The modulus is taken with the hash table size (a prime number)
 102 to find the 'bucket' to place each key into.
 103 The function should also be very fast, since it is called for each key
 104 lookup.
 105 </para>
 106
 107 @key: a key.
 108 @Returns: the hash value corresponding to the key.
 109
 110
 111 <!-- ##### USER_FUNCTION GEqualFunc ##### -->
 112 <para>
 113 Specifies the type of a function used to test two values for
 114 equality. The function should return %TRUE if both values are equal and
 115 %FALSE otherwise.
 116 </para>
 117
 118 @a: a value.
 119 @b: a value to compare with.
 120 @Returns: %TRUE if @a = @b; %FALSE otherwise.
 121
 122
 123 <!-- ##### FUNCTION g_hash_table_insert ##### -->
 124 <para>
 125
 126 </para>
 127
 128 @hash_table:
 129 @key:
 130 @value:
 131
 132
 133 <!-- ##### FUNCTION g_hash_table_replace ##### -->
 134 <para>
 135
 136 </para>
 137
 138 @hash_table:
 139 @key:
 140 @value:
 141
 142
 143 <!-- ##### FUNCTION g_hash_table_size ##### -->
 144 <para>
 145
 146 </para>
 147
 148 @hash_table:
 149 @Returns:
 150
 151
 152 <!-- ##### FUNCTION g_hash_table_lookup ##### -->
 153 <para>
 154
 155 </para>
 156
 157 @hash_table:
 158 @key:
 159 @Returns:
 160
 161
 162 <!-- ##### FUNCTION g_hash_table_lookup_extended ##### -->
 163 <para>
 164
 165 </para>
 166
 167 @hash_table:
 168 @lookup_key:
 169 @orig_key:
 170 @value:
 171 @Returns:
 172
 173
 174 <!-- ##### FUNCTION g_hash_table_foreach ##### -->
 175 <para>
 176
 177 </para>
 178
 179 @hash_table:
 180 @func:
 181 @user_data:
 182
 183
 184 <!-- ##### FUNCTION g_hash_table_find ##### -->
 185 <para>
 186
 187 </para>
 188
 189 @hash_table:
 190 @predicate:
 191 @user_data:
 192 @Returns:
 193
 194
 195 <!-- ##### USER_FUNCTION GHFunc ##### -->
 196 <para>
 197 Specifies the type of the function passed to g_hash_table_foreach().
 198 It is called with each key/value pair, together with the @user_data parameter
 199 which is passed to g_hash_table_foreach().
 200 </para>
 201
 202 @key: a key.
 203 @value: the value corresponding to the key.
 204 @user_data: user data passed to g_hash_table_foreach().
 205
 206
 207 <!-- ##### FUNCTION g_hash_table_remove ##### -->
 208 <para>
 209
 210 </para>
 211
 212 @hash_table:
 213 @key:
 214 @Returns:
 215
 216
 217 <!-- ##### FUNCTION g_hash_table_steal ##### -->
 218 <para>
 219
 220 </para>
 221
 222 @hash_table:
 223 @key:
 224 @Returns:
 225
 226
 227 <!-- ##### FUNCTION g_hash_table_foreach_remove ##### -->
 228 <para>
 229
 230 </para>
 231
 232 @hash_table:
 233 @func:
 234 @user_data:
 235 @Returns:
 236
 237
 238 <!-- ##### FUNCTION g_hash_table_foreach_steal ##### -->
 239 <para>
 240
 241 </para>
 242
 243 @hash_table:
 244 @func:
 245 @user_data:
 246 @Returns:
 247
 248
 249 <!-- ##### FUNCTION g_hash_table_remove_all ##### -->
 250 <para>
 251
 252 </para>
 253
 254 @hash_table:
 255
 256
 257 <!-- ##### FUNCTION g_hash_table_steal_all ##### -->
 258 <para>
 259
 260 </para>
 261
 262 @hash_table:
 263
 264
 265 <!-- ##### USER_FUNCTION GHRFunc ##### -->
 266 <para>
 267 Specifies the type of the function passed to g_hash_table_foreach_remove().
 268 It is called with each key/value pair, together with the @user_data parameter
 269 passed to g_hash_table_foreach_remove().
 270 It should return %TRUE if the key/value pair should be removed from the
 271 #GHashTable.
 272 </para>
 273
 274 @key: a key.
 275 @value: the value associated with the key.
 276 @user_data: user data passed to g_hash_table_remove().
 277 @Returns: %TRUE if the key/value pair should be removed from the #GHashTable.
 278
 279
 280 <!-- ##### MACRO g_hash_table_freeze ##### -->
 281 <para>
 282 This function is deprecated and will be removed in the next major
 283  release of GLib. It does nothing.
 284 </para>
 285
 286 @hash_table: a #GHashTable
 287
 288
 289 <!-- ##### MACRO g_hash_table_thaw ##### -->
 290 <para>
 291 This function is deprecated and will be removed in the next major
 292  release of GLib. It does nothing.
 293 </para>
 294
 295 @hash_table: a #GHashTable
 296
 297
 298 <!-- ##### FUNCTION g_hash_table_destroy ##### -->
 299 <para>
 300
 301 </para>
 302
 303 @hash_table:
 304
 305
 306 <!-- ##### FUNCTION g_hash_table_ref ##### -->
 307 <para>
 308
 309 </para>
 310
 311 @hash_table:
 312 @Returns:
 313
 314
 315 <!-- ##### FUNCTION g_hash_table_unref ##### -->
 316 <para>
 317
 318 </para>
 319
 320 @hash_table:
 321
 322
 323 <!-- ##### FUNCTION g_direct_equal ##### -->
 324 <para>
 325
 326 </para>
 327
 328 @v1:
 329 @v2:
 330 @Returns:
 331
 332
 333 <!-- ##### FUNCTION g_direct_hash ##### -->
 334 <para>
 335
 336 </para>
 337
 338 @v:
 339 @Returns:
 340
 341
 342 <!-- ##### FUNCTION g_int_equal ##### -->
 343 <para>
 344
 345 </para>
 346
 347 @v1:
 348 @v2:
 349 @Returns:
 350
 351
 352 <!-- ##### FUNCTION g_int_hash ##### -->
 353 <para>
 354
 355 </para>
 356
 357 @v:
 358 @Returns:
 359
 360
 361 <!-- ##### FUNCTION g_str_equal ##### -->
 362 <para>
 363 </para>
 364
 365 @v1:
 366 @v2:
 367 @Returns:
 368
 369
 370 <!-- ##### FUNCTION g_str_hash ##### -->
 371 <para>
 372 </para>
 373
 374 @v:
 375 @Returns:
 376
 377