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 * Conversion parameters: 26 * inFile = glib-Hash-Tables.html 27 * outPack = glib 28 * outFile = HashTable 29 * strct = GHashTable 30 * realStrct= 31 * ctorStrct= 32 * clss = HashTable 33 * interf = 34 * class Code: No 35 * interface Code: No 36 * template for: 37 * extend = 38 * implements: 39 * prefixes: 40 * - g_hash_table_ 41 * omit structs: 42 * omit prefixes: 43 * - g_hash_table_iter_ 44 * omit code: 45 * omit signals: 46 * imports: 47 * - glib.HashTableIter 48 * - glib.ListG 49 * structWrap: 50 * - GHashTable* -> HashTable 51 * - GHashTableIter* -> HashTableIter 52 * - GList* -> ListG 53 * module aliases: 54 * local aliases: 55 * overrides: 56 */ 57 58 module glib.HashTable; 59 60 public import gtkc.glibtypes; 61 62 private import gtkc.glib; 63 private import glib.ConstructionException; 64 65 66 private import glib.HashTableIter; 67 private import glib.ListG; 68 69 70 71 72 /** 73 * Description 74 * A GHashTable provides associations between keys and values which is 75 * optimized so that given a key, the associated value can be found 76 * very quickly. 77 * Note that neither keys nor values are copied when inserted into the 78 * GHashTable, so they must exist for the lifetime of the GHashTable. 79 * This means that the use of static strings is OK, but temporary 80 * strings (i.e. those created in buffers and those returned by GTK+ 81 * widgets) should be copied with g_strdup() before being inserted. 82 * If keys or values are dynamically allocated, you must be careful to 83 * ensure that they are freed when they are removed from the 84 * GHashTable, and also when they are overwritten by new insertions 85 * into the GHashTable. It is also not advisable to mix static strings 86 * and dynamically-allocated strings in a GHashTable, because it then 87 * becomes difficult to determine whether the string should be freed. 88 * To create a GHashTable, use g_hash_table_new(). 89 * To insert a key and value into a GHashTable, use 90 * g_hash_table_insert(). 91 * To lookup a value corresponding to a given key, use 92 * g_hash_table_lookup() and g_hash_table_lookup_extended(). 93 * To remove a key and value, use g_hash_table_remove(). 94 * To call a function for each key and value pair use 95 * g_hash_table_foreach() or use a iterator to iterate over the 96 * key/value pairs in the hash table, see GHashTableIter. 97 * To destroy a GHashTable use g_hash_table_destroy(). 98 */ 99 public class HashTable 100 { 101 102 /** the main Gtk struct */ 103 protected GHashTable* gHashTable; 104 105 106 public GHashTable* getHashTableStruct() 107 { 108 return gHashTable; 109 } 110 111 112 /** the main Gtk struct as a void* */ 113 protected void* getStruct() 114 { 115 return cast(void*)gHashTable; 116 } 117 118 /** 119 * Sets our main struct and passes it to the parent class 120 */ 121 public this (GHashTable* gHashTable) 122 { 123 this.gHashTable = gHashTable; 124 } 125 126 /** 127 */ 128 129 /** 130 * Creates a new GHashTable with a reference count of 1. 131 * Params: 132 * hashFunc = a function to create a hash value from a key. 133 * Hash values are used to determine where keys are stored within the 134 * GHashTable data structure. The g_direct_hash(), g_int_hash(), 135 * g_int64_hash(), g_double_hash() and g_str_hash() functions are provided 136 * for some common types of keys. 137 * If hash_func is NULL, g_direct_hash() is used. 138 * keyEqualFunc = a function to check two keys for equality. This is 139 * used when looking up keys in the GHashTable. The g_direct_equal(), 140 * g_int_equal(), g_int64_equal(), g_double_equal() and g_str_equal() 141 * functions are provided for the most common types of keys. 142 * If key_equal_func is NULL, keys are compared directly in a similar 143 * fashion to g_direct_equal(), but without the overhead of a function call. 144 * Throws: ConstructionException GTK+ fails to create the object. 145 */ 146 public this (GHashFunc hashFunc, GEqualFunc keyEqualFunc) 147 { 148 // GHashTable * g_hash_table_new (GHashFunc hash_func, GEqualFunc key_equal_func); 149 auto p = g_hash_table_new(hashFunc, keyEqualFunc); 150 if(p is null) 151 { 152 throw new ConstructionException("null returned by g_hash_table_new(hashFunc, keyEqualFunc)"); 153 } 154 this(cast(GHashTable*) p); 155 } 156 157 /** 158 * Creates a new GHashTable like g_hash_table_new() with a reference count 159 * of 1 and allows to specify functions to free the memory allocated for the 160 * key and value that get called when removing the entry from the GHashTable. 161 * Params: 162 * hashFunc = a function to create a hash value from a key. 163 * keyEqualFunc = a function to check two keys for equality. 164 * keyDestroyFunc = a function to free the memory allocated for the key 165 * used when removing the entry from the GHashTable or NULL if you 166 * don't want to supply such a function. 167 * valueDestroyFunc = a function to free the memory allocated for the 168 * value used when removing the entry from the GHashTable or NULL if 169 * you don't want to supply such a function. 170 * Throws: ConstructionException GTK+ fails to create the object. 171 */ 172 public this (GHashFunc hashFunc, GEqualFunc keyEqualFunc, GDestroyNotify keyDestroyFunc, GDestroyNotify valueDestroyFunc) 173 { 174 // GHashTable * g_hash_table_new_full (GHashFunc hash_func, GEqualFunc key_equal_func, GDestroyNotify key_destroy_func, GDestroyNotify value_destroy_func); 175 auto p = g_hash_table_new_full(hashFunc, keyEqualFunc, keyDestroyFunc, valueDestroyFunc); 176 if(p is null) 177 { 178 throw new ConstructionException("null returned by g_hash_table_new_full(hashFunc, keyEqualFunc, keyDestroyFunc, valueDestroyFunc)"); 179 } 180 this(cast(GHashTable*) p); 181 } 182 183 /** 184 * Inserts a new key and value into a GHashTable. 185 * If the key already exists in the GHashTable its current value is replaced 186 * with the new value. If you supplied a value_destroy_func when creating the 187 * GHashTable, the old value is freed using that function. If you supplied 188 * a key_destroy_func when creating the GHashTable, the passed key is freed 189 * using that function. 190 * Params: 191 * key = a key to insert. 192 * value = the value to associate with the key. 193 */ 194 public void insert(void* key, void* value) 195 { 196 // void g_hash_table_insert (GHashTable *hash_table, gpointer key, gpointer value); 197 g_hash_table_insert(gHashTable, key, value); 198 } 199 200 /** 201 * Inserts a new key and value into a GHashTable similar to 202 * g_hash_table_insert(). The difference is that if the key already exists 203 * in the GHashTable, it gets replaced by the new key. If you supplied a 204 * value_destroy_func when creating the GHashTable, the old value is freed 205 * using that function. If you supplied a key_destroy_func when creating the 206 * GHashTable, the old key is freed using that function. 207 * Params: 208 * key = a key to insert. 209 * value = the value to associate with the key. 210 */ 211 public void replace(void* key, void* value) 212 { 213 // void g_hash_table_replace (GHashTable *hash_table, gpointer key, gpointer value); 214 g_hash_table_replace(gHashTable, key, value); 215 } 216 217 /** 218 * Returns the number of elements contained in the GHashTable. 219 * Returns: the number of key/value pairs in the GHashTable. 220 */ 221 public uint size() 222 { 223 // guint g_hash_table_size (GHashTable *hash_table); 224 return g_hash_table_size(gHashTable); 225 } 226 227 /** 228 * Looks up a key in a GHashTable. Note that this function cannot 229 * distinguish between a key that is not present and one which is present 230 * and has the value NULL. If you need this distinction, use 231 * g_hash_table_lookup_extended(). 232 * Params: 233 * key = the key to look up. 234 * Returns: the associated value, or NULL if the key is not found. 235 */ 236 public void* lookup(void* key) 237 { 238 // gpointer g_hash_table_lookup (GHashTable *hash_table, gconstpointer key); 239 return g_hash_table_lookup(gHashTable, key); 240 } 241 242 /** 243 * Looks up a key in the GHashTable, returning the original key and the 244 * associated value and a gboolean which is TRUE if the key was found. This 245 * is useful if you need to free the memory allocated for the original key, 246 * for example before calling g_hash_table_remove(). 247 * You can actually pass NULL for lookup_key to test 248 * whether the NULL key exists, provided the hash and equal functions 249 * of hash_table are NULL-safe. 250 * Params: 251 * lookupKey = the key to look up 252 * origKey = return location for the original key, or NULL 253 * value = return location for the value associated with the key, or NULL 254 * Returns: TRUE if the key was found in the GHashTable. 255 */ 256 public int lookupExtended(void* lookupKey, void** origKey, void** value) 257 { 258 // gboolean g_hash_table_lookup_extended (GHashTable *hash_table, gconstpointer lookup_key, gpointer *orig_key, gpointer *value); 259 return g_hash_table_lookup_extended(gHashTable, lookupKey, origKey, value); 260 } 261 262 /** 263 * Calls the given function for each of the key/value pairs in the 264 * GHashTable. The function is passed the key and value of each 265 * pair, and the given user_data parameter. The hash table may not 266 * be modified while iterating over it (you can't add/remove 267 * items). To remove all items matching a predicate, use 268 * g_hash_table_foreach_remove(). 269 * See g_hash_table_find() for performance caveats for linear 270 * order searches in contrast to g_hash_table_lookup(). 271 * Params: 272 * func = the function to call for each key/value pair. 273 * userData = user data to pass to the function. 274 */ 275 public void foreac(GHFunc func, void* userData) 276 { 277 // void g_hash_table_foreach (GHashTable *hash_table, GHFunc func, gpointer user_data); 278 g_hash_table_foreach(gHashTable, func, userData); 279 } 280 281 /** 282 * Calls the given function for key/value pairs in the GHashTable until 283 * predicate returns TRUE. The function is passed the key and value of 284 * each pair, and the given user_data parameter. The hash table may not 285 * be modified while iterating over it (you can't add/remove items). 286 * Note, that hash tables are really only optimized for forward lookups, 287 * i.e. g_hash_table_lookup(). 288 * So code that frequently issues g_hash_table_find() or 289 * g_hash_table_foreach() (e.g. in the order of once per every entry in a 290 * hash table) should probably be reworked to use additional or different 291 * data structures for reverse lookups (keep in mind that an O(n) find/foreach 292 * operation issued for all n values in a hash table ends up needing O(n*n) 293 * operations). 294 * Since 2.4 295 * Params: 296 * predicate = function to test the key/value pairs for a certain property. 297 * userData = user data to pass to the function. 298 * Returns: The value of the first key/value pair is returned, for which func evaluates to TRUE. If no pair with the requested property is found, NULL is returned. 299 */ 300 public void* find(GHRFunc predicate, void* userData) 301 { 302 // gpointer g_hash_table_find (GHashTable *hash_table, GHRFunc predicate, gpointer user_data); 303 return g_hash_table_find(gHashTable, predicate, userData); 304 } 305 306 /** 307 * Removes a key and its associated value from a GHashTable. 308 * If the GHashTable was created using g_hash_table_new_full(), the 309 * key and value are freed using the supplied destroy functions, otherwise 310 * you have to make sure that any dynamically allocated values are freed 311 * yourself. 312 * Params: 313 * key = the key to remove. 314 * Returns: TRUE if the key was found and removed from the GHashTable. 315 */ 316 public int remove(void* key) 317 { 318 // gboolean g_hash_table_remove (GHashTable *hash_table, gconstpointer key); 319 return g_hash_table_remove(gHashTable, key); 320 } 321 322 /** 323 * Removes a key and its associated value from a GHashTable without 324 * calling the key and value destroy functions. 325 * Params: 326 * key = the key to remove. 327 * Returns: TRUE if the key was found and removed from the GHashTable. 328 */ 329 public int steal(void* key) 330 { 331 // gboolean g_hash_table_steal (GHashTable *hash_table, gconstpointer key); 332 return g_hash_table_steal(gHashTable, key); 333 } 334 335 /** 336 * Calls the given function for each key/value pair in the GHashTable. 337 * If the function returns TRUE, then the key/value pair is removed from the 338 * GHashTable. If you supplied key or value destroy functions when creating 339 * the GHashTable, they are used to free the memory allocated for the removed 340 * keys and values. 341 * See GHashTableIter for an alternative way to loop over the 342 * key/value pairs in the hash table. 343 * Params: 344 * func = the function to call for each key/value pair. 345 * userData = user data to pass to the function. 346 * Returns: the number of key/value pairs removed. 347 */ 348 public uint foreachRemove(GHRFunc func, void* userData) 349 { 350 // guint g_hash_table_foreach_remove (GHashTable *hash_table, GHRFunc func, gpointer user_data); 351 return g_hash_table_foreach_remove(gHashTable, func, userData); 352 } 353 354 /** 355 * Calls the given function for each key/value pair in the GHashTable. 356 * If the function returns TRUE, then the key/value pair is removed from the 357 * GHashTable, but no key or value destroy functions are called. 358 * See GHashTableIter for an alternative way to loop over the 359 * key/value pairs in the hash table. 360 * Params: 361 * func = the function to call for each key/value pair. 362 * userData = user data to pass to the function. 363 * Returns: the number of key/value pairs removed. 364 */ 365 public uint foreachSteal(GHRFunc func, void* userData) 366 { 367 // guint g_hash_table_foreach_steal (GHashTable *hash_table, GHRFunc func, gpointer user_data); 368 return g_hash_table_foreach_steal(gHashTable, func, userData); 369 } 370 371 /** 372 * Removes all keys and their associated values from a GHashTable. 373 * If the GHashTable was created using g_hash_table_new_full(), the keys 374 * and values are freed using the supplied destroy functions, otherwise you 375 * have to make sure that any dynamically allocated values are freed 376 * yourself. 377 * Since 2.12 378 */ 379 public void removeAll() 380 { 381 // void g_hash_table_remove_all (GHashTable *hash_table); 382 g_hash_table_remove_all(gHashTable); 383 } 384 385 /** 386 * Removes all keys and their associated values from a GHashTable 387 * without calling the key and value destroy functions. 388 * Since 2.12 389 */ 390 public void stealAll() 391 { 392 // void g_hash_table_steal_all (GHashTable *hash_table); 393 g_hash_table_steal_all(gHashTable); 394 } 395 396 /** 397 * Retrieves every key inside hash_table. The returned data is valid 398 * until hash_table is modified. 399 * Since 2.14 400 * Returns: a GList containing all the keys inside the hash table. The content of the list is owned by the hash table and should not be modified or freed. Use g_list_free() when done using the list. 401 */ 402 public ListG getKeys() 403 { 404 // GList * g_hash_table_get_keys (GHashTable *hash_table); 405 auto p = g_hash_table_get_keys(gHashTable); 406 407 if(p is null) 408 { 409 return null; 410 } 411 412 return new ListG(cast(GList*) p); 413 } 414 415 /** 416 * Retrieves every value inside hash_table. The returned data is 417 * valid until hash_table is modified. 418 * Since 2.14 419 * Returns: a GList containing all the values inside the hash table. The content of the list is owned by the hash table and should not be modified or freed. Use g_list_free() when done using the list. 420 */ 421 public ListG getValues() 422 { 423 // GList * g_hash_table_get_values (GHashTable *hash_table); 424 auto p = g_hash_table_get_values(gHashTable); 425 426 if(p is null) 427 { 428 return null; 429 } 430 431 return new ListG(cast(GList*) p); 432 } 433 434 /** 435 * Destroys all keys and values in the GHashTable and decrements its 436 * reference count by 1. If keys and/or values are dynamically allocated, 437 * you should either free them first or create the GHashTable with destroy 438 * notifiers using g_hash_table_new_full(). In the latter case the destroy 439 * functions you supplied will be called on all keys and values during the 440 * destruction phase. 441 */ 442 public void destroy() 443 { 444 // void g_hash_table_destroy (GHashTable *hash_table); 445 g_hash_table_destroy(gHashTable); 446 } 447 448 /** 449 * Atomically increments the reference count of hash_table by one. 450 * This function is MT-safe and may be called from any thread. 451 * Since 2.10 452 * Returns: the passed in GHashTable. 453 */ 454 public HashTable doref() 455 { 456 // GHashTable * g_hash_table_ref (GHashTable *hash_table); 457 auto p = g_hash_table_ref(gHashTable); 458 459 if(p is null) 460 { 461 return null; 462 } 463 464 return new HashTable(cast(GHashTable*) p); 465 } 466 467 /** 468 * Atomically decrements the reference count of hash_table by one. 469 * If the reference count drops to 0, all keys and values will be 470 * destroyed, and all memory allocated by the hash table is released. 471 * This function is MT-safe and may be called from any thread. 472 * Since 2.10 473 */ 474 public void unref() 475 { 476 // void g_hash_table_unref (GHashTable *hash_table); 477 g_hash_table_unref(gHashTable); 478 } 479 480 /** 481 * Compares two gpointer arguments and returns TRUE if they are equal. 482 * It can be passed to g_hash_table_new() as the key_equal_func 483 * parameter, when using pointers as keys in a GHashTable. 484 * Params: 485 * v1 = a key. 486 * v2 = a key to compare with v1. 487 * Returns: TRUE if the two keys match. 488 */ 489 public static int gDirectEqual(void* v1, void* v2) 490 { 491 // gboolean g_direct_equal (gconstpointer v1, gconstpointer v2); 492 return g_direct_equal(v1, v2); 493 } 494 495 /** 496 * Converts a gpointer to a hash value. 497 * It can be passed to g_hash_table_new() as the hash_func parameter, 498 * when using pointers as keys in a GHashTable. 499 * Params: 500 * v = a gpointer key 501 * Returns: a hash value corresponding to the key. 502 */ 503 public static uint gDirectHash(void* v) 504 { 505 // guint g_direct_hash (gconstpointer v); 506 return g_direct_hash(v); 507 } 508 509 /** 510 * Compares the two gint values being pointed to and returns 511 * TRUE if they are equal. 512 * It can be passed to g_hash_table_new() as the key_equal_func 513 * parameter, when using pointers to integers as keys in a GHashTable. 514 * Params: 515 * v1 = a pointer to a gint key. 516 * v2 = a pointer to a gint key to compare with v1. 517 * Returns: TRUE if the two keys match. 518 */ 519 public static int gIntEqual(void* v1, void* v2) 520 { 521 // gboolean g_int_equal (gconstpointer v1, gconstpointer v2); 522 return g_int_equal(v1, v2); 523 } 524 525 /** 526 * Converts a pointer to a gint to a hash value. 527 * It can be passed to g_hash_table_new() as the hash_func parameter, 528 * when using pointers to integers values as keys in a GHashTable. 529 * Params: 530 * v = a pointer to a gint key 531 * Returns: a hash value corresponding to the key. 532 */ 533 public static uint gIntHash(void* v) 534 { 535 // guint g_int_hash (gconstpointer v); 536 return g_int_hash(v); 537 } 538 539 /** 540 * Compares the two gint64 values being pointed to and returns 541 * TRUE if they are equal. 542 * It can be passed to g_hash_table_new() as the key_equal_func 543 * parameter, when using pointers to 64-bit integers as keys in a GHashTable. 544 * Since 2.22 545 * Params: 546 * v1 = a pointer to a gint64 key. 547 * v2 = a pointer to a gint64 key to compare with v1. 548 * Returns: TRUE if the two keys match. 549 */ 550 public static int gInt64_Equal(void* v1, void* v2) 551 { 552 // gboolean g_int64_equal (gconstpointer v1, gconstpointer v2); 553 return g_int64_equal(v1, v2); 554 } 555 556 /** 557 * Converts a pointer to a gint64 to a hash value. 558 * It can be passed to g_hash_table_new() as the hash_func parameter, 559 * when using pointers to 64-bit integers values as keys in a GHashTable. 560 * Since 2.22 561 * Params: 562 * v = a pointer to a gint64 key 563 * Returns: a hash value corresponding to the key. 564 */ 565 public static uint gInt64_Hash(void* v) 566 { 567 // guint g_int64_hash (gconstpointer v); 568 return g_int64_hash(v); 569 } 570 571 /** 572 * Compares the two gdouble values being pointed to and returns 573 * TRUE if they are equal. 574 * It can be passed to g_hash_table_new() as the key_equal_func 575 * parameter, when using pointers to doubles as keys in a GHashTable. 576 * Since 2.22 577 * Params: 578 * v1 = a pointer to a gdouble key. 579 * v2 = a pointer to a gdouble key to compare with v1. 580 * Returns: TRUE if the two keys match. 581 */ 582 public static int gDoubleEqual(void* v1, void* v2) 583 { 584 // gboolean g_double_equal (gconstpointer v1, gconstpointer v2); 585 return g_double_equal(v1, v2); 586 } 587 588 /** 589 * Converts a pointer to a gdouble to a hash value. 590 * It can be passed to g_hash_table_new() as the hash_func parameter, 591 * when using pointers to doubles as keys in a GHashTable. 592 * Since 2.22 593 * Params: 594 * v = a pointer to a gdouble key 595 * Returns: a hash value corresponding to the key. 596 */ 597 public static uint gDoubleHash(void* v) 598 { 599 // guint g_double_hash (gconstpointer v); 600 return g_double_hash(v); 601 } 602 603 /** 604 * Compares two strings for byte-by-byte equality and returns TRUE 605 * if they are equal. It can be passed to g_hash_table_new() as the 606 * key_equal_func parameter, when using strings as keys in a GHashTable. 607 * Note that this function is primarily meant as a hash table comparison 608 * function. For a general-purpose, NULL-safe string comparison function, 609 * see g_strcmp0(). 610 * Params: 611 * v1 = a key 612 * v2 = a key to compare with v1 613 * Returns: TRUE if the two keys match 614 */ 615 public static int gStrEqual(void* v1, void* v2) 616 { 617 // gboolean g_str_equal (gconstpointer v1, gconstpointer v2); 618 return g_str_equal(v1, v2); 619 } 620 621 /** 622 * Converts a string to a hash value. 623 * This function implements the widely used "djb" hash apparently posted 624 * by Daniel Bernstein to comp.lang.c some time ago. The 32 bit 625 * unsigned hash value starts at 5381 and for each byte 'c' in the 626 * string, is updated: hash = hash * 33 + c. This 627 * function uses the signed value of each byte. 628 * It can be passed to g_hash_table_new() as the hash_func parameter, 629 * when using strings as keys in a GHashTable. 630 * Params: 631 * v = a string key 632 * Returns: a hash value corresponding to the key 633 */ 634 public static uint gStrHash(void* v) 635 { 636 // guint g_str_hash (gconstpointer v); 637 return g_str_hash(v); 638 } 639 }