1 /* 2 * This file is part of gtkD. 3 * 4 * gtkD is free software; you can redistribute it and/or modify 5 * it under the terms of the GNU Lesser General Public License 6 * as published by the Free Software Foundation; either version 3 7 * of the License, or (at your option) any later version, with 8 * some exceptions, please read the COPYING file. 9 * 10 * gtkD is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 * GNU Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General Public License 16 * along with gtkD; if not, write to the Free Software 17 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA 18 */ 19 20 // generated automatically - do not change 21 // find conversion definition on APILookup.txt 22 // implement new conversion functionalities on the wrap.utils pakage 23 24 25 module glib.HashTable; 26 27 private import glib.ConstructionException; 28 private import glib.ListG; 29 private import gtkc.glib; 30 public import gtkc.glibtypes; 31 32 33 /** 34 * The #GHashTable struct is an opaque data structure to represent a 35 * [Hash Table][glib-Hash-Tables]. It should only be accessed via the 36 * following functions. 37 */ 38 public class HashTable 39 { 40 /** the main Gtk struct */ 41 protected GHashTable* gHashTable; 42 protected bool ownedRef; 43 44 /** Get the main Gtk struct */ 45 public GHashTable* getHashTableStruct(bool transferOwnership = false) 46 { 47 if (transferOwnership) 48 ownedRef = false; 49 return gHashTable; 50 } 51 52 /** the main Gtk struct as a void* */ 53 protected void* getStruct() 54 { 55 return cast(void*)gHashTable; 56 } 57 58 /** 59 * Sets our main struct and passes it to the parent class. 60 */ 61 public this (GHashTable* gHashTable, bool ownedRef = false) 62 { 63 this.gHashTable = gHashTable; 64 this.ownedRef = ownedRef; 65 } 66 67 68 /** 69 * This is a convenience function for using a #GHashTable as a set. It 70 * is equivalent to calling g_hash_table_replace() with @key as both the 71 * key and the value. 72 * 73 * When a hash table only ever contains keys that have themselves as the 74 * corresponding value it is able to be stored more efficiently. See 75 * the discussion in the section description. 76 * 77 * Params: 78 * key = a key to insert 79 * 80 * Returns: %TRUE if the key did not exist yet 81 * 82 * Since: 2.32 83 */ 84 public bool add(void* key) 85 { 86 return g_hash_table_add(gHashTable, key) != 0; 87 } 88 89 /** 90 * Checks if @key is in @hash_table. 91 * 92 * Params: 93 * key = a key to check 94 * 95 * Returns: %TRUE if @key is in @hash_table, %FALSE otherwise. 96 * 97 * Since: 2.32 98 */ 99 public bool contains(void* key) 100 { 101 return g_hash_table_contains(gHashTable, key) != 0; 102 } 103 104 /** 105 * Destroys all keys and values in the #GHashTable and decrements its 106 * reference count by 1. If keys and/or values are dynamically allocated, 107 * you should either free them first or create the #GHashTable with destroy 108 * notifiers using g_hash_table_new_full(). In the latter case the destroy 109 * functions you supplied will be called on all keys and values during the 110 * destruction phase. 111 */ 112 public void destroy() 113 { 114 g_hash_table_destroy(gHashTable); 115 } 116 117 /** 118 * Calls the given function for key/value pairs in the #GHashTable 119 * until @predicate returns %TRUE. The function is passed the key 120 * and value of each pair, and the given @user_data parameter. The 121 * hash table may not be modified while iterating over it (you can't 122 * add/remove items). 123 * 124 * Note, that hash tables are really only optimized for forward 125 * lookups, i.e. g_hash_table_lookup(). So code that frequently issues 126 * g_hash_table_find() or g_hash_table_foreach() (e.g. in the order of 127 * once per every entry in a hash table) should probably be reworked 128 * to use additional or different data structures for reverse lookups 129 * (keep in mind that an O(n) find/foreach operation issued for all n 130 * values in a hash table ends up needing O(n*n) operations). 131 * 132 * Params: 133 * predicate = function to test the key/value pairs for a certain property 134 * userData = user data to pass to the function 135 * 136 * Returns: The value of the first key/value pair is returned, 137 * for which @predicate evaluates to %TRUE. If no pair with the 138 * requested property is found, %NULL is returned. 139 * 140 * Since: 2.4 141 */ 142 public void* find(GHRFunc predicate, void* userData) 143 { 144 return g_hash_table_find(gHashTable, predicate, userData); 145 } 146 147 /** 148 * Calls the given function for each of the key/value pairs in the 149 * #GHashTable. The function is passed the key and value of each 150 * pair, and the given @user_data parameter. The hash table may not 151 * be modified while iterating over it (you can't add/remove 152 * items). To remove all items matching a predicate, use 153 * g_hash_table_foreach_remove(). 154 * 155 * See g_hash_table_find() for performance caveats for linear 156 * order searches in contrast to g_hash_table_lookup(). 157 * 158 * Params: 159 * func = the function to call for each key/value pair 160 * userData = user data to pass to the function 161 */ 162 public void foreac(GHFunc func, void* userData) 163 { 164 g_hash_table_foreach(gHashTable, func, userData); 165 } 166 167 /** 168 * Calls the given function for each key/value pair in the 169 * #GHashTable. If the function returns %TRUE, then the key/value 170 * pair is removed from the #GHashTable. If you supplied key or 171 * value destroy functions when creating the #GHashTable, they are 172 * used to free the memory allocated for the removed keys and values. 173 * 174 * See #GHashTableIter for an alternative way to loop over the 175 * key/value pairs in the hash table. 176 * 177 * Params: 178 * func = the function to call for each key/value pair 179 * userData = user data to pass to the function 180 * 181 * Returns: the number of key/value pairs removed 182 */ 183 public uint foreachRemove(GHRFunc func, void* userData) 184 { 185 return g_hash_table_foreach_remove(gHashTable, func, userData); 186 } 187 188 /** 189 * Calls the given function for each key/value pair in the 190 * #GHashTable. If the function returns %TRUE, then the key/value 191 * pair is removed from the #GHashTable, but no key or value 192 * destroy functions are called. 193 * 194 * See #GHashTableIter for an alternative way to loop over the 195 * key/value pairs in the hash table. 196 * 197 * Params: 198 * func = the function to call for each key/value pair 199 * userData = user data to pass to the function 200 * 201 * Returns: the number of key/value pairs removed. 202 */ 203 public uint foreachSteal(GHRFunc func, void* userData) 204 { 205 return g_hash_table_foreach_steal(gHashTable, func, userData); 206 } 207 208 /** 209 * Retrieves every key inside @hash_table. The returned data is valid 210 * until changes to the hash release those keys. 211 * 212 * This iterates over every entry in the hash table to build its return value. 213 * To iterate over the entries in a #GHashTable more efficiently, use a 214 * #GHashTableIter. 215 * 216 * Returns: a #GList containing all the keys 217 * inside the hash table. The content of the list is owned by the 218 * hash table and should not be modified or freed. Use g_list_free() 219 * when done using the list. 220 * 221 * Since: 2.14 222 */ 223 public ListG getKeys() 224 { 225 auto p = g_hash_table_get_keys(gHashTable); 226 227 if(p is null) 228 { 229 return null; 230 } 231 232 return new ListG(cast(GList*) p); 233 } 234 235 /** 236 * Retrieves every key inside @hash_table, as an array. 237 * 238 * The returned array is %NULL-terminated but may contain %NULL as a 239 * key. Use @length to determine the true length if it's possible that 240 * %NULL was used as the value for a key. 241 * 242 * Note: in the common case of a string-keyed #GHashTable, the return 243 * value of this function can be conveniently cast to (const gchar **). 244 * 245 * This iterates over every entry in the hash table to build its return value. 246 * To iterate over the entries in a #GHashTable more efficiently, use a 247 * #GHashTableIter. 248 * 249 * You should always free the return result with g_free(). In the 250 * above-mentioned case of a string-keyed hash table, it may be 251 * appropriate to use g_strfreev() if you call g_hash_table_steal_all() 252 * first to transfer ownership of the keys. 253 * 254 * Returns: a 255 * %NULL-terminated array containing each key from the table. 256 * 257 * Since: 2.40 258 */ 259 public void*[] getKeysAsArray() 260 { 261 uint length; 262 263 auto p = g_hash_table_get_keys_as_array(gHashTable, &length); 264 265 return p[0 .. length]; 266 } 267 268 /** 269 * Retrieves every value inside @hash_table. The returned data 270 * is valid until @hash_table is modified. 271 * 272 * This iterates over every entry in the hash table to build its return value. 273 * To iterate over the entries in a #GHashTable more efficiently, use a 274 * #GHashTableIter. 275 * 276 * Returns: a #GList containing all the values 277 * inside the hash table. The content of the list is owned by the 278 * hash table and should not be modified or freed. Use g_list_free() 279 * when done using the list. 280 * 281 * Since: 2.14 282 */ 283 public ListG getValues() 284 { 285 auto p = g_hash_table_get_values(gHashTable); 286 287 if(p is null) 288 { 289 return null; 290 } 291 292 return new ListG(cast(GList*) p); 293 } 294 295 /** 296 * Inserts a new key and value into a #GHashTable. 297 * 298 * If the key already exists in the #GHashTable its current 299 * value is replaced with the new value. If you supplied a 300 * @value_destroy_func when creating the #GHashTable, the old 301 * value is freed using that function. If you supplied a 302 * @key_destroy_func when creating the #GHashTable, the passed 303 * key is freed using that function. 304 * 305 * Params: 306 * key = a key to insert 307 * value = the value to associate with the key 308 * 309 * Returns: %TRUE if the key did not exist yet 310 */ 311 public bool insert(void* key, void* value) 312 { 313 return g_hash_table_insert(gHashTable, key, value) != 0; 314 } 315 316 /** 317 * Looks up a key in a #GHashTable. Note that this function cannot 318 * distinguish between a key that is not present and one which is present 319 * and has the value %NULL. If you need this distinction, use 320 * g_hash_table_lookup_extended(). 321 * 322 * Params: 323 * key = the key to look up 324 * 325 * Returns: the associated value, or %NULL if the key is not found 326 */ 327 public void* lookup(void* key) 328 { 329 return g_hash_table_lookup(gHashTable, key); 330 } 331 332 /** 333 * Looks up a key in the #GHashTable, returning the original key and the 334 * associated value and a #gboolean which is %TRUE if the key was found. This 335 * is useful if you need to free the memory allocated for the original key, 336 * for example before calling g_hash_table_remove(). 337 * 338 * You can actually pass %NULL for @lookup_key to test 339 * whether the %NULL key exists, provided the hash and equal functions 340 * of @hash_table are %NULL-safe. 341 * 342 * Params: 343 * lookupKey = the key to look up 344 * origKey = return location for the original key 345 * value = return location for the value associated 346 * with the key 347 * 348 * Returns: %TRUE if the key was found in the #GHashTable 349 */ 350 public bool lookupExtended(void* lookupKey, out void* origKey, out void* value) 351 { 352 return g_hash_table_lookup_extended(gHashTable, lookupKey, &origKey, &value) != 0; 353 } 354 355 /** 356 * Creates a new #GHashTable with a reference count of 1. 357 * 358 * Hash values returned by @hash_func are used to determine where keys 359 * are stored within the #GHashTable data structure. The g_direct_hash(), 360 * g_int_hash(), g_int64_hash(), g_double_hash() and g_str_hash() 361 * functions are provided for some common types of keys. 362 * If @hash_func is %NULL, g_direct_hash() is used. 363 * 364 * @key_equal_func is used when looking up keys in the #GHashTable. 365 * The g_direct_equal(), g_int_equal(), g_int64_equal(), g_double_equal() 366 * and g_str_equal() functions are provided for the most common types 367 * of keys. If @key_equal_func is %NULL, keys are compared directly in 368 * a similar fashion to g_direct_equal(), but without the overhead of 369 * a function call. @key_equal_func is called with the key from the hash table 370 * as its first parameter, and the user-provided key to check against as 371 * its second. 372 * 373 * Params: 374 * hashFunc = a function to create a hash value from a key 375 * keyEqualFunc = a function to check two keys for equality 376 * 377 * Returns: a new #GHashTable 378 * 379 * Throws: ConstructionException GTK+ fails to create the object. 380 */ 381 public this(GHashFunc hashFunc, GEqualFunc keyEqualFunc) 382 { 383 auto p = g_hash_table_new(hashFunc, keyEqualFunc); 384 385 if(p is null) 386 { 387 throw new ConstructionException("null returned by new"); 388 } 389 390 this(cast(GHashTable*) p); 391 } 392 393 /** 394 * Creates a new #GHashTable like g_hash_table_new() with a reference 395 * count of 1 and allows to specify functions to free the memory 396 * allocated for the key and value that get called when removing the 397 * entry from the #GHashTable. 398 * 399 * Since version 2.42 it is permissible for destroy notify functions to 400 * recursively remove further items from the hash table. This is only 401 * permissible if the application still holds a reference to the hash table. 402 * This means that you may need to ensure that the hash table is empty by 403 * calling g_hash_table_remove_all() before releasing the last reference using 404 * g_hash_table_unref(). 405 * 406 * Params: 407 * hashFunc = a function to create a hash value from a key 408 * keyEqualFunc = a function to check two keys for equality 409 * keyDestroyFunc = a function to free the memory allocated for the key 410 * used when removing the entry from the #GHashTable, or %NULL 411 * if you don't want to supply such a function. 412 * valueDestroyFunc = a function to free the memory allocated for the 413 * value used when removing the entry from the #GHashTable, or %NULL 414 * if you don't want to supply such a function. 415 * 416 * Returns: a new #GHashTable 417 * 418 * Throws: ConstructionException GTK+ fails to create the object. 419 */ 420 public this(GHashFunc hashFunc, GEqualFunc keyEqualFunc, GDestroyNotify keyDestroyFunc, GDestroyNotify valueDestroyFunc) 421 { 422 auto p = g_hash_table_new_full(hashFunc, keyEqualFunc, keyDestroyFunc, valueDestroyFunc); 423 424 if(p is null) 425 { 426 throw new ConstructionException("null returned by new_full"); 427 } 428 429 this(cast(GHashTable*) p); 430 } 431 432 /** 433 * Atomically increments the reference count of @hash_table by one. 434 * This function is MT-safe and may be called from any thread. 435 * 436 * Returns: the passed in #GHashTable 437 * 438 * Since: 2.10 439 */ 440 public HashTable doref() 441 { 442 auto p = g_hash_table_ref(gHashTable); 443 444 if(p is null) 445 { 446 return null; 447 } 448 449 return new HashTable(cast(GHashTable*) p); 450 } 451 452 /** 453 * Removes a key and its associated value from a #GHashTable. 454 * 455 * If the #GHashTable was created using g_hash_table_new_full(), the 456 * key and value are freed using the supplied destroy functions, otherwise 457 * you have to make sure that any dynamically allocated values are freed 458 * yourself. 459 * 460 * Params: 461 * key = the key to remove 462 * 463 * Returns: %TRUE if the key was found and removed from the #GHashTable 464 */ 465 public bool remove(void* key) 466 { 467 return g_hash_table_remove(gHashTable, key) != 0; 468 } 469 470 /** 471 * Removes all keys and their associated values from a #GHashTable. 472 * 473 * If the #GHashTable was created using g_hash_table_new_full(), 474 * the keys and values are freed using the supplied destroy functions, 475 * otherwise you have to make sure that any dynamically allocated 476 * values are freed yourself. 477 * 478 * Since: 2.12 479 */ 480 public void removeAll() 481 { 482 g_hash_table_remove_all(gHashTable); 483 } 484 485 /** 486 * Inserts a new key and value into a #GHashTable similar to 487 * g_hash_table_insert(). The difference is that if the key 488 * already exists in the #GHashTable, it gets replaced by the 489 * new key. If you supplied a @value_destroy_func when creating 490 * the #GHashTable, the old value is freed using that function. 491 * If you supplied a @key_destroy_func when creating the 492 * #GHashTable, the old key is freed using that function. 493 * 494 * Params: 495 * key = a key to insert 496 * value = the value to associate with the key 497 * 498 * Returns: %TRUE if the key did not exist yet 499 */ 500 public bool replace(void* key, void* value) 501 { 502 return g_hash_table_replace(gHashTable, key, value) != 0; 503 } 504 505 /** 506 * Returns the number of elements contained in the #GHashTable. 507 * 508 * Returns: the number of key/value pairs in the #GHashTable. 509 */ 510 public uint size() 511 { 512 return g_hash_table_size(gHashTable); 513 } 514 515 /** 516 * Removes a key and its associated value from a #GHashTable without 517 * calling the key and value destroy functions. 518 * 519 * Params: 520 * key = the key to remove 521 * 522 * Returns: %TRUE if the key was found and removed from the #GHashTable 523 */ 524 public bool steal(void* key) 525 { 526 return g_hash_table_steal(gHashTable, key) != 0; 527 } 528 529 /** 530 * Removes all keys and their associated values from a #GHashTable 531 * without calling the key and value destroy functions. 532 * 533 * Since: 2.12 534 */ 535 public void stealAll() 536 { 537 g_hash_table_steal_all(gHashTable); 538 } 539 540 /** 541 * Atomically decrements the reference count of @hash_table by one. 542 * If the reference count drops to 0, all keys and values will be 543 * destroyed, and all memory allocated by the hash table is released. 544 * This function is MT-safe and may be called from any thread. 545 * 546 * Since: 2.10 547 */ 548 public void unref() 549 { 550 g_hash_table_unref(gHashTable); 551 } 552 553 /** 554 * Compares two #gpointer arguments and returns %TRUE if they are equal. 555 * It can be passed to g_hash_table_new() as the @key_equal_func 556 * parameter, when using opaque pointers compared by pointer value as 557 * keys in a #GHashTable. 558 * 559 * This equality function is also appropriate for keys that are integers 560 * stored in pointers, such as `GINT_TO_POINTER (n)`. 561 * 562 * Params: 563 * v1 = a key 564 * v2 = a key to compare with @v1 565 * 566 * Returns: %TRUE if the two keys match. 567 */ 568 public static bool directEqual(void* v1, void* v2) 569 { 570 return g_direct_equal(v1, v2) != 0; 571 } 572 573 /** 574 * Converts a gpointer to a hash value. 575 * It can be passed to g_hash_table_new() as the @hash_func parameter, 576 * when using opaque pointers compared by pointer value as keys in a 577 * #GHashTable. 578 * 579 * This hash function is also appropriate for keys that are integers 580 * stored in pointers, such as `GINT_TO_POINTER (n)`. 581 * 582 * Params: 583 * v = a #gpointer key 584 * 585 * Returns: a hash value corresponding to the key. 586 */ 587 public static uint directHash(void* v) 588 { 589 return g_direct_hash(v); 590 } 591 592 /** 593 * Compares the two #gdouble values being pointed to and returns 594 * %TRUE if they are equal. 595 * It can be passed to g_hash_table_new() as the @key_equal_func 596 * parameter, when using non-%NULL pointers to doubles as keys in a 597 * #GHashTable. 598 * 599 * Params: 600 * v1 = a pointer to a #gdouble key 601 * v2 = a pointer to a #gdouble key to compare with @v1 602 * 603 * Returns: %TRUE if the two keys match. 604 * 605 * Since: 2.22 606 */ 607 public static bool doubleEqual(void* v1, void* v2) 608 { 609 return g_double_equal(v1, v2) != 0; 610 } 611 612 /** 613 * Converts a pointer to a #gdouble to a hash value. 614 * It can be passed to g_hash_table_new() as the @hash_func parameter, 615 * It can be passed to g_hash_table_new() as the @hash_func parameter, 616 * when using non-%NULL pointers to doubles as keys in a #GHashTable. 617 * 618 * Params: 619 * v = a pointer to a #gdouble key 620 * 621 * Returns: a hash value corresponding to the key. 622 * 623 * Since: 2.22 624 */ 625 public static uint doubleHash(void* v) 626 { 627 return g_double_hash(v); 628 } 629 630 /** 631 * Compares the two #gint64 values being pointed to and returns 632 * %TRUE if they are equal. 633 * It can be passed to g_hash_table_new() as the @key_equal_func 634 * parameter, when using non-%NULL pointers to 64-bit integers as keys in a 635 * #GHashTable. 636 * 637 * Params: 638 * v1 = a pointer to a #gint64 key 639 * v2 = a pointer to a #gint64 key to compare with @v1 640 * 641 * Returns: %TRUE if the two keys match. 642 * 643 * Since: 2.22 644 */ 645 public static bool int64Equal(void* v1, void* v2) 646 { 647 return g_int64_equal(v1, v2) != 0; 648 } 649 650 /** 651 * Converts a pointer to a #gint64 to a hash value. 652 * 653 * It can be passed to g_hash_table_new() as the @hash_func parameter, 654 * when using non-%NULL pointers to 64-bit integer values as keys in a 655 * #GHashTable. 656 * 657 * Params: 658 * v = a pointer to a #gint64 key 659 * 660 * Returns: a hash value corresponding to the key. 661 * 662 * Since: 2.22 663 */ 664 public static uint int64Hash(void* v) 665 { 666 return g_int64_hash(v); 667 } 668 669 /** 670 * Compares the two #gint values being pointed to and returns 671 * %TRUE if they are equal. 672 * It can be passed to g_hash_table_new() as the @key_equal_func 673 * parameter, when using non-%NULL pointers to integers as keys in a 674 * #GHashTable. 675 * 676 * Note that this function acts on pointers to #gint, not on #gint 677 * directly: if your hash table's keys are of the form 678 * `GINT_TO_POINTER (n)`, use g_direct_equal() instead. 679 * 680 * Params: 681 * v1 = a pointer to a #gint key 682 * v2 = a pointer to a #gint key to compare with @v1 683 * 684 * Returns: %TRUE if the two keys match. 685 */ 686 public static bool intEqual(void* v1, void* v2) 687 { 688 return g_int_equal(v1, v2) != 0; 689 } 690 691 /** 692 * Converts a pointer to a #gint to a hash value. 693 * It can be passed to g_hash_table_new() as the @hash_func parameter, 694 * when using non-%NULL pointers to integer values as keys in a #GHashTable. 695 * 696 * Note that this function acts on pointers to #gint, not on #gint 697 * directly: if your hash table's keys are of the form 698 * `GINT_TO_POINTER (n)`, use g_direct_hash() instead. 699 * 700 * Params: 701 * v = a pointer to a #gint key 702 * 703 * Returns: a hash value corresponding to the key. 704 */ 705 public static uint intHash(void* v) 706 { 707 return g_int_hash(v); 708 } 709 710 /** 711 * Compares two strings for byte-by-byte equality and returns %TRUE 712 * if they are equal. It can be passed to g_hash_table_new() as the 713 * @key_equal_func parameter, when using non-%NULL strings as keys in a 714 * #GHashTable. 715 * 716 * Note that this function is primarily meant as a hash table comparison 717 * function. For a general-purpose, %NULL-safe string comparison function, 718 * see g_strcmp0(). 719 * 720 * Params: 721 * v1 = a key 722 * v2 = a key to compare with @v1 723 * 724 * Returns: %TRUE if the two keys match 725 */ 726 public static bool strEqual(void* v1, void* v2) 727 { 728 return g_str_equal(v1, v2) != 0; 729 } 730 731 /** 732 * Converts a string to a hash value. 733 * 734 * This function implements the widely used "djb" hash apparently 735 * posted by Daniel Bernstein to comp.lang.c some time ago. The 32 736 * bit unsigned hash value starts at 5381 and for each byte 'c' in 737 * the string, is updated: `hash = hash * 33 + c`. This function 738 * uses the signed value of each byte. 739 * 740 * It can be passed to g_hash_table_new() as the @hash_func parameter, 741 * when using non-%NULL strings as keys in a #GHashTable. 742 * 743 * Note that this function may not be a perfect fit for all use cases. 744 * For example, it produces some hash collisions with strings as short 745 * as 2. 746 * 747 * Params: 748 * v = a string key 749 * 750 * Returns: a hash value corresponding to the key 751 */ 752 public static uint strHash(void* v) 753 { 754 return g_str_hash(v); 755 } 756 }