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 <!-- ##### USER_FUNCTION GHRFunc ##### -->
 250 <para>
 251 Specifies the type of the function passed to g_hash_table_foreach_remove().
 252 It is called with each key/value pair, together with the @user_data parameter
 253 passed to g_hash_table_foreach_remove().
 254 It should return %TRUE if the key/value pair should be removed from the
 255 #GHashTable.
 256 </para>
 257
 258 @key: a key.
 259 @value: the value associated with the key.
 260 @user_data: user data passed to g_hash_table_remove().
 261 @Returns: %TRUE if the key/value pair should be removed from the #GHashTable.
 262
 263
 264 <!-- ##### MACRO g_hash_table_freeze ##### -->
 265 <para>
 266 This function is deprecated and will be removed in the next major
 267  release of GLib. It does nothing.
 268 </para>
 269
 270 @hash_table: a #GHashTable
 271
 272
 273 <!-- ##### MACRO g_hash_table_thaw ##### -->
 274 <para>
 275 This function is deprecated and will be removed in the next major
 276  release of GLib. It does nothing.
 277 </para>
 278
 279 @hash_table: a #GHashTable
 280
 281
 282 <!-- ##### FUNCTION g_hash_table_destroy ##### -->
 283 <para>
 284
 285 </para>
 286
 287 @hash_table:
 288
 289
 290 <!-- ##### FUNCTION g_hash_table_ref ##### -->
 291 <para>
 292
 293 </para>
 294
 295 @hash_table:
 296 @Returns:
 297
 298
 299 <!-- ##### FUNCTION g_hash_table_unref ##### -->
 300 <para>
 301
 302 </para>
 303
 304 @hash_table:
 305
 306
 307 <!-- ##### FUNCTION g_direct_equal ##### -->
 308 <para>
 309
 310 </para>
 311
 312 @v1:
 313 @v2:
 314 @Returns:
 315
 316
 317 <!-- ##### FUNCTION g_direct_hash ##### -->
 318 <para>
 319
 320 </para>
 321
 322 @v:
 323 @Returns:
 324
 325
 326 <!-- ##### FUNCTION g_int_equal ##### -->
 327 <para>
 328
 329 </para>
 330
 331 @v1:
 332 @v2:
 333 @Returns:
 334
 335
 336 <!-- ##### FUNCTION g_int_hash ##### -->
 337 <para>
 338
 339 </para>
 340
 341 @v:
 342 @Returns:
 343
 344
 345 <!-- ##### FUNCTION g_str_equal ##### -->
 346 <para>
 347 </para>
 348
 349 @v1:
 350 @v2:
 351 @Returns:
 352
 353
 354 <!-- ##### FUNCTION g_str_hash ##### -->
 355 <para>
 356 </para>
 357
 358 @v:
 359 @Returns:
 360
 361