uhash.h (29067B)
1 // © 2016 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 /* 4 ****************************************************************************** 5 * Copyright (C) 1997-2015, International Business Machines 6 * Corporation and others. All Rights Reserved. 7 ****************************************************************************** 8 * Date Name Description 9 * 03/22/00 aliu Adapted from original C++ ICU Hashtable. 10 * 07/06/01 aliu Modified to support int32_t keys on 11 * platforms with sizeof(void*) < 32. 12 ****************************************************************************** 13 */ 14 15 #ifndef UHASH_H 16 #define UHASH_H 17 18 #include "unicode/utypes.h" 19 #include "cmemory.h" 20 #include "uelement.h" 21 #include "unicode/localpointer.h" 22 23 /** 24 * UHashtable stores key-value pairs and does moderately fast lookup 25 * based on keys. It provides a good tradeoff between access time and 26 * storage space. As elements are added to it, it grows to accommodate 27 * them. By default, the table never shrinks, even if all elements 28 * are removed from it. 29 * 30 * Keys and values are stored as void* pointers. These void* pointers 31 * may be actual pointers to strings, objects, or any other structure 32 * in memory, or they may simply be integral values cast to void*. 33 * UHashtable doesn't care and manipulates them via user-supplied 34 * functions. These functions hash keys, compare keys, delete keys, 35 * and delete values. Some function pointers are optional (may be 36 * NULL); others must be supplied. Several prebuilt functions exist 37 * to handle common key types. 38 * 39 * UHashtable ownership of keys and values is flexible, and controlled 40 * by whether or not the key deleter and value deleter functions are 41 * set. If a void* key is actually a pointer to a deletable object, 42 * then UHashtable can be made to delete that object by setting the 43 * key deleter function pointer to a non-NULL value. If this is done, 44 * then keys passed to uhash_put() are owned by the hashtable and will 45 * be deleted by it at some point, either as keys are replaced, or 46 * when uhash_close() is finally called. The same is true of values 47 * and the value deleter function pointer. Keys passed to methods 48 * other than uhash_put() are never owned by the hashtable. 49 * 50 * NULL values are not allowed. uhash_get() returns NULL to indicate 51 * a key that is not in the table, and having a NULL value in the 52 * table would generate an ambiguous result. If a key and a NULL 53 * value is passed to uhash_put(), this has the effect of doing a 54 * uhash_remove() on that key. This keeps uhash_get(), uhash_count(), 55 * and uhash_nextElement() consistent with one another. 56 * 57 * Keys and values can be integers. 58 * Functions that work with an integer key have an "i" prefix. 59 * Functions that work with an integer value have an "i" suffix. 60 * As with putting a NULL value pointer, putting a zero value integer removes the item. 61 * Except, there are pairs of functions that allow setting zero values 62 * and fetching (value, found) pairs. 63 * 64 * To see everything in a hashtable, use uhash_nextElement() to 65 * iterate through its contents. Each call to this function returns a 66 * UHashElement pointer. A hash element contains a key, value, and 67 * hashcode. During iteration an element may be deleted by calling 68 * uhash_removeElement(); iteration may safely continue thereafter. 69 * The uhash_remove() function may also be safely called in 70 * mid-iteration. If uhash_put() is called during iteration, 71 * the iteration is still guaranteed to terminate reasonably, but 72 * there is no guarantee that every element will be returned or that 73 * some won't be returned more than once. 74 * 75 * Under no circumstances should the UHashElement returned by 76 * uhash_nextElement be modified directly. 77 * 78 * By default, the hashtable grows when necessary, but never shrinks, 79 * even if all items are removed. For most applications this is 80 * optimal. However, in a highly dynamic usage where memory is at a 81 * premium, the table can be set to both grow and shrink by calling 82 * uhash_setResizePolicy() with the policy U_GROW_AND_SHRINK. In a 83 * situation where memory is critical and the client wants a table 84 * that does not grow at all, the constant U_FIXED can be used. 85 */ 86 87 /******************************************************************** 88 * Data Structures 89 ********************************************************************/ 90 91 U_CDECL_BEGIN 92 93 /** 94 * A key or value within a UHashtable. 95 * The hashing and comparison functions take a pointer to a 96 * UHashTok, but the deleter receives the void* pointer within it. 97 */ 98 typedef UElement UHashTok; 99 100 /** 101 * This is a single hash element. 102 */ 103 struct UHashElement { 104 /* Reorder these elements to pack nicely if necessary */ 105 int32_t hashcode; 106 UHashTok value; 107 UHashTok key; 108 }; 109 typedef struct UHashElement UHashElement; 110 111 /** 112 * A hashing function. 113 * @param key A key stored in a hashtable 114 * @return A NON-NEGATIVE hash code for parm. 115 */ 116 typedef int32_t U_CALLCONV UHashFunction(const UHashTok key); 117 118 /** 119 * A key equality (boolean) comparison function. 120 */ 121 typedef UElementsAreEqual UKeyComparator; 122 123 /** 124 * A value equality (boolean) comparison function. 125 */ 126 typedef UElementsAreEqual UValueComparator; 127 128 /* see cmemory.h for UObjectDeleter and uprv_deleteUObject() */ 129 130 /** 131 * This specifies whether or not, and how, the hashtable resizes itself. 132 * See uhash_setResizePolicy(). 133 */ 134 enum UHashResizePolicy { 135 U_GROW, /* Grow on demand, do not shrink */ 136 U_GROW_AND_SHRINK, /* Grow and shrink on demand */ 137 U_FIXED /* Never change size */ 138 }; 139 140 /** 141 * The UHashtable struct. Clients should treat this as an opaque data 142 * type and manipulate it only through the uhash_... API. 143 */ 144 struct UHashtable { 145 146 /* Main key-value pair storage array */ 147 148 UHashElement *elements; 149 150 /* Function pointers */ 151 152 UHashFunction *keyHasher; /* Computes hash from key. 153 * Never null. */ 154 UKeyComparator *keyComparator; /* Compares keys for equality. 155 * Never null. */ 156 UValueComparator *valueComparator; /* Compares the values for equality */ 157 158 UObjectDeleter *keyDeleter; /* Deletes keys when required. 159 * If NULL won't do anything */ 160 UObjectDeleter *valueDeleter; /* Deletes values when required. 161 * If NULL won't do anything */ 162 163 /* Size parameters */ 164 165 int32_t count; /* The number of key-value pairs in this table. 166 * 0 <= count <= length. In practice we 167 * never let count == length (see code). */ 168 int32_t length; /* The physical size of the arrays hashes, keys 169 * and values. Must be prime. */ 170 171 /* Rehashing thresholds */ 172 173 int32_t highWaterMark; /* If count > highWaterMark, rehash */ 174 int32_t lowWaterMark; /* If count < lowWaterMark, rehash */ 175 float highWaterRatio; /* 0..1; high water as a fraction of length */ 176 float lowWaterRatio; /* 0..1; low water as a fraction of length */ 177 178 int8_t primeIndex; /* Index into our prime table for length. 179 * length == PRIMES[primeIndex] */ 180 UBool allocated; /* Was this UHashtable allocated? */ 181 }; 182 typedef struct UHashtable UHashtable; 183 184 U_CDECL_END 185 186 /******************************************************************** 187 * API 188 ********************************************************************/ 189 190 /** 191 * Initialize a new UHashtable. 192 * @param keyHash A pointer to the key hashing function. Must not be 193 * NULL. 194 * @param keyComp A pointer to the function that compares keys. Must 195 * not be NULL. 196 * @param status A pointer to an UErrorCode to receive any errors. 197 * @return A pointer to a UHashtable, or 0 if an error occurred. 198 * @see uhash_openSize 199 */ 200 U_CAPI UHashtable* U_EXPORT2 201 uhash_open(UHashFunction *keyHash, 202 UKeyComparator *keyComp, 203 UValueComparator *valueComp, 204 UErrorCode *status); 205 206 /** 207 * Initialize a new UHashtable with a given initial size. 208 * @param keyHash A pointer to the key hashing function. Must not be 209 * NULL. 210 * @param keyComp A pointer to the function that compares keys. Must 211 * not be NULL. 212 * @param size The initial capacity of this hashtable. 213 * @param status A pointer to an UErrorCode to receive any errors. 214 * @return A pointer to a UHashtable, or 0 if an error occurred. 215 * @see uhash_open 216 */ 217 U_CAPI UHashtable* U_EXPORT2 218 uhash_openSize(UHashFunction *keyHash, 219 UKeyComparator *keyComp, 220 UValueComparator *valueComp, 221 int32_t size, 222 UErrorCode *status); 223 224 /** 225 * Initialize an existing UHashtable. 226 * @param keyHash A pointer to the key hashing function. Must not be 227 * NULL. 228 * @param keyComp A pointer to the function that compares keys. Must 229 * not be NULL. 230 * @param status A pointer to an UErrorCode to receive any errors. 231 * @return A pointer to a UHashtable, or 0 if an error occurred. 232 * @see uhash_openSize 233 */ 234 U_CAPI UHashtable* U_EXPORT2 235 uhash_init(UHashtable *hash, 236 UHashFunction *keyHash, 237 UKeyComparator *keyComp, 238 UValueComparator *valueComp, 239 UErrorCode *status); 240 241 /** 242 * Initialize an existing UHashtable. 243 * @param keyHash A pointer to the key hashing function. Must not be 244 * NULL. 245 * @param keyComp A pointer to the function that compares keys. Must 246 * not be NULL. 247 * @param size The initial capacity of this hashtable. 248 * @param status A pointer to an UErrorCode to receive any errors. 249 * @return A pointer to a UHashtable, or 0 if an error occurred. 250 * @see uhash_openSize 251 */ 252 U_CAPI UHashtable* U_EXPORT2 253 uhash_initSize(UHashtable *hash, 254 UHashFunction *keyHash, 255 UKeyComparator *keyComp, 256 UValueComparator *valueComp, 257 int32_t size, 258 UErrorCode *status); 259 260 /** 261 * Close a UHashtable, releasing the memory used. 262 * @param hash The UHashtable to close. If hash is NULL no operation is performed. 263 */ 264 U_CAPI void U_EXPORT2 265 uhash_close(UHashtable *hash); 266 267 268 269 /** 270 * Set the function used to hash keys. 271 * @param hash The UHashtable to set 272 * @param fn the function to be used hash keys; must not be NULL 273 * @return the previous key hasher; non-NULL 274 */ 275 U_CAPI UHashFunction *U_EXPORT2 276 uhash_setKeyHasher(UHashtable *hash, UHashFunction *fn); 277 278 /** 279 * Set the function used to compare keys. The default comparison is a 280 * void* pointer comparison. 281 * @param hash The UHashtable to set 282 * @param fn the function to be used compare keys; must not be NULL 283 * @return the previous key comparator; non-NULL 284 */ 285 U_CAPI UKeyComparator *U_EXPORT2 286 uhash_setKeyComparator(UHashtable *hash, UKeyComparator *fn); 287 288 /** 289 * Set the function used to compare values. The default comparison is a 290 * void* pointer comparison. 291 * @param hash The UHashtable to set 292 * @param fn the function to be used compare keys; must not be NULL 293 * @return the previous key comparator; non-NULL 294 */ 295 U_CAPI UValueComparator *U_EXPORT2 296 uhash_setValueComparator(UHashtable *hash, UValueComparator *fn); 297 298 /** 299 * Set the function used to delete keys. If this function pointer is 300 * NULL, this hashtable does not delete keys. If it is non-NULL, this 301 * hashtable does delete keys. This function should be set once 302 * before any elements are added to the hashtable and should not be 303 * changed thereafter. 304 * @param hash The UHashtable to set 305 * @param fn the function to be used delete keys, or NULL 306 * @return the previous key deleter; may be NULL 307 */ 308 U_CAPI UObjectDeleter *U_EXPORT2 309 uhash_setKeyDeleter(UHashtable *hash, UObjectDeleter *fn); 310 311 /** 312 * Set the function used to delete values. If this function pointer 313 * is NULL, this hashtable does not delete values. If it is non-NULL, 314 * this hashtable does delete values. This function should be set 315 * once before any elements are added to the hashtable and should not 316 * be changed thereafter. 317 * @param hash The UHashtable to set 318 * @param fn the function to be used delete values, or NULL 319 * @return the previous value deleter; may be NULL 320 */ 321 U_CAPI UObjectDeleter *U_EXPORT2 322 uhash_setValueDeleter(UHashtable *hash, UObjectDeleter *fn); 323 324 /** 325 * Specify whether or not, and how, the hashtable resizes itself. 326 * By default, tables grow but do not shrink (policy U_GROW). 327 * See enum UHashResizePolicy. 328 * @param hash The UHashtable to set 329 * @param policy The way the hashtable resizes itself, {U_GROW, U_GROW_AND_SHRINK, U_FIXED} 330 */ 331 U_CAPI void U_EXPORT2 332 uhash_setResizePolicy(UHashtable *hash, enum UHashResizePolicy policy); 333 334 /** 335 * Get the number of key-value pairs stored in a UHashtable. 336 * @param hash The UHashtable to query. 337 * @return The number of key-value pairs stored in hash. 338 */ 339 U_CAPI int32_t U_EXPORT2 340 uhash_count(const UHashtable *hash); 341 342 /** 343 * Put a (key=pointer, value=pointer) item in a UHashtable. If the 344 * keyDeleter is non-NULL, then the hashtable owns 'key' after this 345 * call. If the valueDeleter is non-NULL, then the hashtable owns 346 * 'value' after this call. Storing a NULL value is the same as 347 * calling uhash_remove(). 348 * @param hash The target UHashtable. 349 * @param key The key to store. 350 * @param value The value to store, may be NULL (see above). 351 * @param status A pointer to an UErrorCode to receive any errors. 352 * @return The previous value, or NULL if none. 353 * @see uhash_get 354 */ 355 U_CAPI void* U_EXPORT2 356 uhash_put(UHashtable *hash, 357 void *key, 358 void *value, 359 UErrorCode *status); 360 361 /** 362 * Put a (key=integer, value=pointer) item in a UHashtable. 363 * keyDeleter must be NULL. If the valueDeleter is non-NULL, then the 364 * hashtable owns 'value' after this call. Storing a NULL value is 365 * the same as calling uhash_remove(). 366 * @param hash The target UHashtable. 367 * @param key The integer key to store. 368 * @param value The value to store, may be NULL (see above). 369 * @param status A pointer to an UErrorCode to receive any errors. 370 * @return The previous value, or NULL if none. 371 * @see uhash_get 372 */ 373 U_CAPI void* U_EXPORT2 374 uhash_iput(UHashtable *hash, 375 int32_t key, 376 void* value, 377 UErrorCode *status); 378 379 /** 380 * Put a (key=pointer, value=integer) item in a UHashtable. If the 381 * keyDeleter is non-NULL, then the hashtable owns 'key' after this 382 * call. valueDeleter must be NULL. Storing a 0 value is the same as 383 * calling uhash_remove(). 384 * @param hash The target UHashtable. 385 * @param key The key to store. 386 * @param value The integer value to store. 387 * @param status A pointer to an UErrorCode to receive any errors. 388 * @return The previous value, or 0 if none. 389 * @see uhash_get 390 */ 391 U_CAPI int32_t U_EXPORT2 392 uhash_puti(UHashtable *hash, 393 void* key, 394 int32_t value, 395 UErrorCode *status); 396 397 /** 398 * Put a (key=integer, value=integer) item in a UHashtable. If the 399 * keyDeleter is non-NULL, then the hashtable owns 'key' after this 400 * call. valueDeleter must be NULL. Storing a 0 value is the same as 401 * calling uhash_remove(). 402 * @param hash The target UHashtable. 403 * @param key The key to store. 404 * @param value The integer value to store. 405 * @param status A pointer to an UErrorCode to receive any errors. 406 * @return The previous value, or 0 if none. 407 * @see uhash_get 408 */ 409 U_CAPI int32_t U_EXPORT2 410 uhash_iputi(UHashtable *hash, 411 int32_t key, 412 int32_t value, 413 UErrorCode *status); 414 415 /** 416 * Put a (key=pointer, value=integer) item in a UHashtable. If the 417 * keyDeleter is non-NULL, then the hashtable owns 'key' after this 418 * call. valueDeleter must be NULL. 419 * Storing a 0 value is possible; call uhash_igetiAndFound() to retrieve values including zero. 420 * 421 * @param hash The target UHashtable. 422 * @param key The key to store. 423 * @param value The integer value to store. 424 * @param status A pointer to an UErrorCode to receive any errors. 425 * @return The previous value, or 0 if none. 426 * @see uhash_getiAndFound 427 */ 428 U_CAPI int32_t U_EXPORT2 429 uhash_putiAllowZero(UHashtable *hash, 430 void *key, 431 int32_t value, 432 UErrorCode *status); 433 434 /** 435 * Put a (key=integer, value=integer) item in a UHashtable. If the 436 * keyDeleter is non-NULL, then the hashtable owns 'key' after this 437 * call. valueDeleter must be NULL. 438 * Storing a 0 value is possible; call uhash_igetiAndFound() to retrieve values including zero. 439 * 440 * @param hash The target UHashtable. 441 * @param key The key to store. 442 * @param value The integer value to store. 443 * @param status A pointer to an UErrorCode to receive any errors. 444 * @return The previous value, or 0 if none. 445 * @see uhash_igetiAndFound 446 */ 447 U_CAPI int32_t U_EXPORT2 448 uhash_iputiAllowZero(UHashtable *hash, 449 int32_t key, 450 int32_t value, 451 UErrorCode *status); 452 453 /** 454 * Retrieve a pointer value from a UHashtable using a pointer key, 455 * as previously stored by uhash_put(). 456 * @param hash The target UHashtable. 457 * @param key A pointer key stored in a hashtable 458 * @return The requested item, or NULL if not found. 459 */ 460 U_CAPI void* U_EXPORT2 461 uhash_get(const UHashtable *hash, 462 const void *key); 463 464 /** 465 * Retrieve a pointer value from a UHashtable using a integer key, 466 * as previously stored by uhash_iput(). 467 * @param hash The target UHashtable. 468 * @param key An integer key stored in a hashtable 469 * @return The requested item, or NULL if not found. 470 */ 471 U_CAPI void* U_EXPORT2 472 uhash_iget(const UHashtable *hash, 473 int32_t key); 474 475 /** 476 * Retrieve an integer value from a UHashtable using a pointer key, 477 * as previously stored by uhash_puti(). 478 * @param hash The target UHashtable. 479 * @param key A pointer key stored in a hashtable 480 * @return The requested item, or 0 if not found. 481 */ 482 U_CAPI int32_t U_EXPORT2 483 uhash_geti(const UHashtable *hash, 484 const void* key); 485 /** 486 * Retrieve an integer value from a UHashtable using an integer key, 487 * as previously stored by uhash_iputi(). 488 * @param hash The target UHashtable. 489 * @param key An integer key stored in a hashtable 490 * @return The requested item, or 0 if not found. 491 */ 492 U_CAPI int32_t U_EXPORT2 493 uhash_igeti(const UHashtable *hash, 494 int32_t key); 495 496 /** 497 * Retrieves an integer value from a UHashtable using a pointer key, 498 * as previously stored by uhash_putiAllowZero() or uhash_puti(). 499 * 500 * @param hash The target UHashtable. 501 * @param key A pointer key stored in a hashtable 502 * @param found A pointer to a boolean which will be set for whether the key was found. 503 * @return The requested item, or 0 if not found. 504 */ 505 U_CAPI int32_t U_EXPORT2 506 uhash_getiAndFound(const UHashtable *hash, 507 const void *key, 508 UBool *found); 509 510 /** 511 * Retrieves an integer value from a UHashtable using an integer key, 512 * as previously stored by uhash_iputiAllowZero() or uhash_iputi(). 513 * 514 * @param hash The target UHashtable. 515 * @param key An integer key stored in a hashtable 516 * @param found A pointer to a boolean which will be set for whether the key was found. 517 * @return The requested item, or 0 if not found. 518 */ 519 U_CAPI int32_t U_EXPORT2 520 uhash_igetiAndFound(const UHashtable *hash, 521 int32_t key, 522 UBool *found); 523 524 /** 525 * Remove an item from a UHashtable stored by uhash_put(). 526 * @param hash The target UHashtable. 527 * @param key A key stored in a hashtable 528 * @return The item removed, or NULL if not found. 529 */ 530 U_CAPI void* U_EXPORT2 531 uhash_remove(UHashtable *hash, 532 const void *key); 533 534 /** 535 * Remove an item from a UHashtable stored by uhash_iput(). 536 * @param hash The target UHashtable. 537 * @param key An integer key stored in a hashtable 538 * @return The item removed, or NULL if not found. 539 */ 540 U_CAPI void* U_EXPORT2 541 uhash_iremove(UHashtable *hash, 542 int32_t key); 543 544 /** 545 * Remove an item from a UHashtable stored by uhash_puti(). 546 * @param hash The target UHashtable. 547 * @param key An key stored in a hashtable 548 * @return The item removed, or 0 if not found. 549 */ 550 U_CAPI int32_t U_EXPORT2 551 uhash_removei(UHashtable *hash, 552 const void* key); 553 554 /** 555 * Remove an item from a UHashtable stored by uhash_iputi(). 556 * @param hash The target UHashtable. 557 * @param key An integer key stored in a hashtable 558 * @return The item removed, or 0 if not found. 559 */ 560 U_CAPI int32_t U_EXPORT2 561 uhash_iremovei(UHashtable *hash, 562 int32_t key); 563 564 /** 565 * Remove all items from a UHashtable. 566 * @param hash The target UHashtable. 567 */ 568 U_CAPI void U_EXPORT2 569 uhash_removeAll(UHashtable *hash); 570 571 /** 572 * Returns true if the UHashtable contains an item with this pointer key. 573 * 574 * @param hash The target UHashtable. 575 * @param key A pointer key stored in a hashtable 576 * @return true if the key is found. 577 */ 578 U_CAPI UBool U_EXPORT2 579 uhash_containsKey(const UHashtable *hash, const void *key); 580 581 /** 582 * Returns true if the UHashtable contains an item with this integer key. 583 * 584 * @param hash The target UHashtable. 585 * @param key An integer key stored in a hashtable 586 * @return true if the key is found. 587 */ 588 U_CAPI UBool U_EXPORT2 589 uhash_icontainsKey(const UHashtable *hash, int32_t key); 590 591 /** 592 * Locate an element of a UHashtable. The caller must not modify the 593 * returned object. The primary use of this function is to obtain the 594 * stored key when it may not be identical to the search key. For 595 * example, if the compare function is a case-insensitive string 596 * compare, then the hash key may be desired in order to obtain the 597 * canonical case corresponding to a search key. 598 * @param hash The target UHashtable. 599 * @param key A key stored in a hashtable 600 * @return a hash element, or NULL if the key is not found. 601 */ 602 U_CAPI const UHashElement* U_EXPORT2 603 uhash_find(const UHashtable *hash, const void* key); 604 605 /** 606 * \def UHASH_FIRST 607 * Constant for use with uhash_nextElement 608 * @see uhash_nextElement 609 */ 610 #define UHASH_FIRST (-1) 611 612 /** 613 * Iterate through the elements of a UHashtable. The caller must not 614 * modify the returned object. However, uhash_removeElement() may be 615 * called during iteration to remove an element from the table. 616 * Iteration may safely be resumed afterwards. If uhash_put() is 617 * called during iteration the iteration will then be out of sync and 618 * should be restarted. 619 * @param hash The target UHashtable. 620 * @param pos This should be set to UHASH_FIRST initially, and left untouched 621 * thereafter. 622 * @return a hash element, or NULL if no further key-value pairs 623 * exist in the table. 624 */ 625 U_CAPI const UHashElement* U_EXPORT2 626 uhash_nextElement(const UHashtable *hash, 627 int32_t *pos); 628 629 /** 630 * Remove an element, returned by uhash_nextElement(), from the table. 631 * Iteration may be safely continued afterwards. 632 * @param hash The hashtable 633 * @param e The element, returned by uhash_nextElement(), to remove. 634 * Must not be NULL. Must not be an empty or deleted element (as long 635 * as this was returned by uhash_nextElement() it will not be empty or 636 * deleted). Note: Although this parameter is const, it will be 637 * modified. 638 * @return the value that was removed. 639 */ 640 U_CAPI void* U_EXPORT2 641 uhash_removeElement(UHashtable *hash, const UHashElement* e); 642 643 /******************************************************************** 644 * UHashTok convenience 645 ********************************************************************/ 646 647 /** 648 * Return a UHashTok for an integer. 649 * @param i The given integer 650 * @return a UHashTok for an integer. 651 */ 652 /*U_CAPI UHashTok U_EXPORT2 653 uhash_toki(int32_t i);*/ 654 655 /** 656 * Return a UHashTok for a pointer. 657 * @param p The given pointer 658 * @return a UHashTok for a pointer. 659 */ 660 /*U_CAPI UHashTok U_EXPORT2 661 uhash_tokp(void* p);*/ 662 663 /******************************************************************** 664 * UChar* and char* Support Functions 665 ********************************************************************/ 666 667 /** 668 * Generate a hash code for a null-terminated UChar* string. If the 669 * string is not null-terminated do not use this function. Use 670 * together with uhash_compareUChars. 671 * @param key The string (const UChar*) to hash. 672 * @return A hash code for the key. 673 */ 674 U_CAPI int32_t U_EXPORT2 675 uhash_hashUChars(const UHashTok key); 676 677 /** 678 * Generate a hash code for a null-terminated char* string. If the 679 * string is not null-terminated do not use this function. Use 680 * together with uhash_compareChars. 681 * @param key The string (const char*) to hash. 682 * @return A hash code for the key. 683 */ 684 U_CAPI int32_t U_EXPORT2 685 uhash_hashChars(const UHashTok key); 686 687 /** 688 * Generate a case-insensitive hash code for a null-terminated char* 689 * string. If the string is not null-terminated do not use this 690 * function. Use together with uhash_compareIChars. 691 * @param key The string (const char*) to hash. 692 * @return A hash code for the key. 693 */ 694 U_CAPI int32_t U_EXPORT2 695 uhash_hashIChars(const UHashTok key); 696 697 /** 698 * Generate a case-insensitive hash code for a std::string_view. 699 * Use together with uhash_compareIStringView. 700 * @param key A pointer to the std::string_view to hash. 701 * @return A hash code for the key. 702 */ 703 U_CAPI int32_t U_EXPORT2 704 uhash_hashIStringView(const UHashTok key); 705 706 /** 707 * Comparator for null-terminated UChar* strings. Use together with 708 * uhash_hashUChars. 709 * @param key1 The string for comparison 710 * @param key2 The string for comparison 711 * @return true if key1 and key2 are equal, return false otherwise. 712 */ 713 U_CAPI UBool U_EXPORT2 714 uhash_compareUChars(const UHashTok key1, const UHashTok key2); 715 716 /** 717 * Comparator for null-terminated char* strings. Use together with 718 * uhash_hashChars. 719 * @param key1 The string for comparison 720 * @param key2 The string for comparison 721 * @return true if key1 and key2 are equal, return false otherwise. 722 */ 723 U_CAPI UBool U_EXPORT2 724 uhash_compareChars(const UHashTok key1, const UHashTok key2); 725 726 /** 727 * Case-insensitive comparator for null-terminated char* strings. Use 728 * together with uhash_hashIChars. 729 * @param key1 The string for comparison 730 * @param key2 The string for comparison 731 * @return true if key1 and key2 are equal, return false otherwise. 732 */ 733 U_CAPI UBool U_EXPORT2 734 uhash_compareIChars(const UHashTok key1, const UHashTok key2); 735 736 /** 737 * Case-insensitive comparator for std::string_view. 738 * Use together with uhash_hashIStringView. 739 * @param key1 A pointer to the std::string_view for comparison 740 * @param key2 A pointer to the std::string_view for comparison 741 * @return true if key1 and key2 are equal, return false otherwise. 742 */ 743 U_CAPI UBool U_EXPORT2 744 uhash_compareIStringView(const UHashTok key1, const UHashTok key2); 745 746 /******************************************************************** 747 * UnicodeString Support Functions 748 ********************************************************************/ 749 750 /** 751 * Hash function for UnicodeString* keys. 752 * @param key The string (const char*) to hash. 753 * @return A hash code for the key. 754 */ 755 U_CAPI int32_t U_EXPORT2 756 uhash_hashUnicodeString(const UElement key); 757 758 /** 759 * Hash function for UnicodeString* keys (case insensitive). 760 * Make sure to use together with uhash_compareCaselessUnicodeString. 761 * @param key The string (const char*) to hash. 762 * @return A hash code for the key. 763 */ 764 U_CAPI int32_t U_EXPORT2 765 uhash_hashCaselessUnicodeString(const UElement key); 766 767 /******************************************************************** 768 * int32_t Support Functions 769 ********************************************************************/ 770 771 /** 772 * Hash function for 32-bit integer keys. 773 * @param key The string (const char*) to hash. 774 * @return A hash code for the key. 775 */ 776 U_CAPI int32_t U_EXPORT2 777 uhash_hashLong(const UHashTok key); 778 779 /** 780 * Comparator function for 32-bit integer keys. 781 * @param key1 The integer for comparison 782 * @param Key2 The integer for comparison 783 * @return true if key1 and key2 are equal, return false otherwise 784 */ 785 U_CAPI UBool U_EXPORT2 786 uhash_compareLong(const UHashTok key1, const UHashTok key2); 787 788 /******************************************************************** 789 * Other Support Functions 790 ********************************************************************/ 791 792 /** 793 * Deleter for Hashtable objects. 794 * @param obj The object to be deleted 795 */ 796 U_CAPI void U_EXPORT2 797 uhash_deleteHashtable(void *obj); 798 799 /* Use uprv_free() itself as a deleter for any key or value allocated using uprv_malloc. */ 800 801 /** 802 * Checks if the given hashtables are equal or not. 803 * @param hash1 804 * @param hash2 805 * @return true if the hashtables are equal and false if not. 806 */ 807 U_CAPI UBool U_EXPORT2 808 uhash_equals(const UHashtable* hash1, const UHashtable* hash2); 809 810 811 #if U_SHOW_CPLUSPLUS_API 812 813 U_NAMESPACE_BEGIN 814 815 /** 816 * \class LocalUHashtablePointer 817 * "Smart pointer" class, closes a UHashtable via uhash_close(). 818 * For most methods see the LocalPointerBase base class. 819 * 820 * @see LocalPointerBase 821 * @see LocalPointer 822 * @stable ICU 4.4 823 */ 824 U_DEFINE_LOCAL_OPEN_POINTER(LocalUHashtablePointer, UHashtable, uhash_close); 825 826 U_NAMESPACE_END 827 828 #endif 829 830 #endif