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_str_equal ##### --> 436 <para> 437 </para> 438 439 @v1: 440 @v2: 441 @Returns: 442 443 444 <!-- ##### FUNCTION g_str_hash ##### --> 445 <para> 446 </para> 447 448 @v: 449 @Returns: 450 451 452
