README.md

   1 Introduction
   2 ============
   3
   4 **LibHashSet** is a [*hash set*](https://en.wikipedia.org/wiki/Hash_table) and [*hash map*](https://en.wikipedia.org/wiki/Hash_table) implementation for C99. It uses open addressing and double hashing.
   5
   6 At this time, the *only* types of elements supported are `uint16_t`, `uint32_t` and `uint64_t`.
   7
   8 This hash set implementation has successfully been tested to *efficiently* handle several billions of items 😏
   9
  10
  11 Getting Started
  12 ===============
  13
  14 Here is a simple example of how to use LibHashSet in your application:
  15
  16 ```C
  17 #include <hash_set.h>
  18 #include <stdio.h>
  19
  20 int main(void)
  21 {
  22         uint64_t item;
  23         uintptr_t cursor = 0U;
  24
  25         /* create new hash set instance */
  26         hash_set64_t* const hash_set = hash_set_create64(0U, -1.0, 42U);
  27         if (!hash_set)
  28         {
  29                 fputs("Allocation has failed!\n", stderr);
  30                 return EXIT_FAILURE;
  31         }
  32
  33         /* add a number of items to the hash set, the set will grow as needed */
  34         puts("Insertign items, please wait...");
  35         while (have_more_items())
  36         {
  37                 const errno_t error = hash_set_insert64(hash_set, get_next_item());
  38                 if (error)
  39                 {
  40                         fprintf(stderr, "Insert operation has failed! (error: %d)\n", error);
  41                         return EXIT_FAILURE;
  42                 }
  43         }
  44         puts("Done.\n");
  45
  46         /* print total number of items in the hash set*/
  47         printf("Total number of items: %zu\n\n", hash_set_size64(hash_set));
  48
  49         /* print all items in the set */
  50         while (hash_set_iterate64(hash_set, &cursor, &item) == 0)
  51         {
  52                 printf("Item: %016llX\n", item);
  53         }
  54
  55         /* destroy the hash set, when it is no longer needed! */
  56         hash_set_destroy64(hash_set);
  57         return EXIT_SUCCESS;
  58 }
  59 ```
  60
  61
  62 API Reference
  63 =============
  64
  65 This section describes the LibHashSet programming interface. The functions for managing *hash sets* are declared in `<hash_set.h>`, whereas the functions for managing to *hash maps* are declared in `<hash_map.h>`.
  66
  67 LibHashSet supports sets and maps containing elements of different integral types. For each element type, separate functions are provided. The functions for `uint16_t`, `uint32_t` and `uint64_t` can be distinguished by the suffix `…16`, `…32` and `…64`, respectively. In the following, the functions are described in their "generic" form.
  68
  69 ***Note:*** On Microsoft Windows (Visual C++), when using LibHashSet as a "shared" library (DLL file), the macro `HASHSET_DLL` must be defined *before* including the `<hash_set.h>` or `<hash_map.h>` header files!
  70
  71 Types
  72 -----
  73
  74 ### hash_set_t
  75
  76 A `struct` that represents a LibHashSet *hash set* instance. Hash set instances can be allocated and de-allocated via the [hash_set_create()](#hash_set_create) and [hash_set_destroy()](#hash_set_destroy) functions, respectively.
  77
  78 ***Note:*** Application code shall treat this `struct` as opaque. The internals may change in future versions!
  79
  80 ```C
  81 typedef struct _hash_set hash_set_t;
  82 ```
  83
  84 ### hash_map_t
  85
  86 A `struct` that represents a LibHashSet *hash map* instance. Hash map instances can be allocated and de-allocated via the [hash_map_create()](#hash_map_create) and [hash_map_destroy()](#hash_map_destroy) functions, respectively.
  87
  88 ***Note:*** Application code shall treat this `struct` as opaque! The internals may change in future versions!
  89
  90 ```C
  91 typedef struct _hash_map hash_map_t;
  92 ```
  93
  94 Globals
  95 -------
  96
  97 ### Version information
  98
  99 The *major*, *minor* and *patch* version of the LibHashSet library:
 100
 101 ```C
 102 extern const uint16_t HASHSET_VERSION_MAJOR;
 103 extern const uint16_t HASHSET_VERSION_MINOR;
 104 extern const uint16_t HASHSET_VERSION_PATCH;
 105 ```
 106
 107 ### Build information
 108
 109 The build *date* and *time* of the LibHashSet library:
 110
 111 ```C
 112 extern const char *const HASHSET_BUILD_DATE;
 113 extern const char *const HASHSET_BUILD_TIME;
 114 ```
 115
 116 Set Functions
 117 -------------
 118
 119 This section describes all functions for managing `hash_set_t` instances.
 120
 121 ### hash_set_create()
 122
 123 Allocates a new hash set instance. The new hash set instance is empty initially.
 124
 125 ```C
 126 hash_set_t *hash_set_create(
 127         const size_t initial_capacity,
 128         const double load_factor,
 129         const uint64_t seed
 130 );
 131 ```
 132
 133 #### Parameters
 134
 135 * `initial_capacity`
 136   The initial capacity of the hash set (number of items). The given count will be rounded to the next power of two. If the number of items to be inserted into the hash set can be estimated beforehand, then the initial capacity should be adjusted accordingly to avoid unnecessary re-allocations. In any case, the hash set will be able to grow dynamically as needed. If this parameter is set to *zero*, the the *default* initial capacity (8192) is used.
 137
 138 * `load_factor`
 139   The load factor to be applied to the hash set. The given load factor will be clipped to the **0.1** to **1.0** range. Generally, the default load factor (0.75) offers a good trade-off between performance and memory usage. Higher load factors decrease the memory overhead, but also may increase the time required for insert, lookup and remove operations. If this parameter is less than or equal to *zero*, the *default* load factor is used.
 140
 141 * `seed`
 142   The "seed" value that is used to tweak the internal hash computation. The application should set this parameter to a value that is hard to predict and that is unlikely to repeat (e.g., a high-resolution timer is suitable here).
 143
 144 #### Return value
 145
 146 On success, this function returns a pointer to a new hash set instance. On error, a `NULL` pointer is returned.
 147
 148 ***Note:*** To avoid a memory leak, the returned pointer must be de-allocated by the application using the [hash_set_destroy()](#hash_set_destroy) function, as soon as the instance is *not* needed anymore!
 149
 150 ### hash_set_destroy()
 151
 152 De-allocates an existing hash set instance. All items in the hash set are discarded.
 153
 154 ```C
 155 void hash_set_destroy(
 156         hash_set_t *instance
 157 );
 158 ```
 159
 160 #### Parameters
 161
 162 * `instance`
 163   A pointer to the hash set instance that is to be destroyed, as returned by the [hash_set_create()](#hash_set_create) function.
 164   ***Note:*** The given pointer is *invalidated* by this function, and it **must not** be used afterwards!
 165
 166 ### hash_set_insert()
 167
 168 Tries to insert the given item into the hash set. The operation fails, if the set already contains the given item.
 169
 170 ***Note:*** If the item is actually inserted, then the hash set *may* need to grow.
 171
 172 ```C
 173 errno_t hash_set_insert(
 174         hash_set_t *const instance,
 175         const value_t item
 176 );
 177 ```
 178
 179 #### Parameters
 180
 181 * `instance`
 182   A pointer to the hash set instance to be modified, as returned by the [hash_set_create()](#hash_set_create) function.
 183
 184 * `item`
 185   The item to be inserted into the hash set.
 186
 187 #### Return value
 188
 189 On success, this function returns *zero*. On error, the appropriate error code is returned. Possible error codes include:
 190
 191 * `EINVAL`
 192   An invalid argument was given, e.g. `instance` was set to `NULL`.
 193
 194 * `EEXIST`
 195   The given item was *not* inserted into the hash set (again), because it was already present.
 196
 197 * `ENOMEM`
 198   The set failed to grow, because the required amount of memory could *not* be allocated (out of memory).
 199
 200 * `EFBIG`
 201   The set needs to grow, but doing so would exceed the maximum size supported by the underlying system.
 202
 203 * `EFAULT`
 204   Something else went wrong. This usually indicates an internal error and is *not* supposed to happen.
 205
 206 ### hash_set_remove()
 207
 208 Tries to remove the given item from the hash set. The operation fails, if the set does *not* contain the given item.
 209
 210 ***Note:*** If the item is actually removed, then the hash set *may* shrink.
 211
 212 ```C
 213 errno_t hash_set_remove(
 214         hash_set_t *const instance,
 215         const value_t item
 216 );
 217 ```
 218
 219 #### Parameters
 220
 221 * `instance`
 222   A pointer to the hash set instance to be modified, as returned by the [hash_set_create()](#hash_set_create) function.
 223
 224 * `item`
 225   The item to be removed from the hash set.
 226
 227 #### Return value
 228
 229 On success, this function returns *zero*. On error, the appropriate error code is returned. Possible error codes include:
 230
 231 * `EINVAL`
 232   An invalid argument was given, e.g. `instance` was set to `NULL`.
 233
 234 * `ENOENT`
 235   The given item could *not* be removed from the hash set, because *no* such item was present.
 236
 237 * `EFAULT`
 238   Something else went wrong. This usually indicates an internal error and is *not* supposed to happen.
 239
 240 ### hash_set_clear()
 241
 242 Discards *all* items from the hash set at once.
 243
 244 ```C
 245 errno_t hash_set_clear(
 246         hash_set_t *const instance
 247 );
 248 ```
 249 #### Parameters
 250
 251 * `instance`
 252   A pointer to the hash set instance to be modified, as returned by the [hash_set_create()](#hash_set_create) function.
 253
 254 #### Return value
 255
 256 On success, this function returns *zero*. On error, the appropriate error code is returned. Possible error codes include:
 257
 258 * `EINVAL`
 259   An invalid argument was given, e.g. `instance` was set to `NULL`.
 260
 261 * `EAGAIN`
 262   The hash set was *not* cleared, because it already was empty. Please try again later!
 263
 264 * `EFAULT`
 265   Something else went wrong. This usually indicates an internal error and is *not* supposed to happen.
 266
 267 ### hash_set_contains()
 268
 269 Tests whether the hash set contains an item. The operation fails, if the set does *not* contain the given item.
 270
 271 ```C
 272 errno_t hash_set_contains(
 273         const hash_set_t *const instance,
 274         const value_t item
 275 );
 276 ```
 277
 278 #### Parameters
 279
 280 * `instance`
 281   A pointer to the hash set instance to be examined, as returned by the [hash_set_create()](#hash_set_create) function.
 282
 283 * `item`
 284   The item to be searched in the hash set.
 285
 286 #### Return value
 287
 288 On success, this function returns *zero*. On error, the appropriate error code is returned. Possible error codes include:
 289
 290 * `EINVAL`
 291   An invalid argument was given, e.g. `instance` was set to `NULL`.
 292
 293 * `ENOENT`
 294   The hash set does *not* contain the specified item.
 295
 296 * `EFAULT`
 297   Something else went wrong. This usually indicates an internal error and is *not* supposed to happen.
 298
 299 ### hash_set_iterate()
 300
 301 Iterates through the items stored in the hash set. The elements are iterated in **no** particular order.
 302
 303 This function returns one item at a time. It should be called *repeatedly*, until the end of the set is encountered.
 304
 305 ***Warning:*** The result is *undefined*, if the set is modified while the iteration is in progress!
 306
 307 ```C
 308 errno_t hash_set_iterate(
 309         const hash_set_t *const instance,
 310         size_t *const cursor,
 311         value_t *const item
 312 );
 313 ```
 314
 315 #### Parameters
 316
 317 * `instance`
 318   A pointer to the hash set instance to be examined, as returned by the [hash_set_create()](#hash_set_create) function.
 319
 320 * `cursor`
 321   A pointer to a variable of type `size_t` where the current iterator state (position) is saved.
 322   This variable **must** be initialized to the value `0U`, by the calling application, prior to the the *first* invocation!
 323   Each invocation will update the value of `*cursor`. This value **shall not** be altered by the application.
 324
 325 * `item`
 326   A pointer to a variable of type `value_t` where the next item in the set is stored on success.
 327   The content of the variable should be considered *undefined*, if the invocation has failed.
 328
 329 #### Return value
 330
 331 On success, this function returns *zero*. On error, the appropriate error code is returned. Possible error codes include:
 332
 333 * `EINVAL`
 334   An invalid argument was given, e.g. `instance` was set to `NULL`.
 335
 336 * `ENOENT`
 337   No more items. The end of the set has been encountered.
 338
 339 * `EFAULT`
 340   Something else went wrong. This usually indicates an internal error and is *not* supposed to happen.
 341
 342 ### hash_set_size()
 343
 344 Returns the current number of (distinct) items in the hash set.
 345
 346 ```C
 347 size_t hash_set_size(
 348         const hash_set_t *const instance
 349 );
 350 ```
 351
 352 #### Parameters
 353
 354 * `instance`
 355   A pointer to the hash set instance to be examined, as returned by the [hash_set_create()](#hash_set_create) function.
 356
 357 #### Return value
 358
 359 This function returns the number of (distinct) items in the hash set.
 360
 361 ### hash_set_info()
 362
 363 Returns technical information about the hash set.
 364
 365 ```C
 366 errno_t hash_set_info(
 367         const hash_set_t *const instance,
 368         size_t *const capacity,
 369         size_t *const valid,
 370         size_t *const deleted,
 371         size_t *const limit
 372 );
 373 ```
 374
 375 #### Parameters
 376
 377 * `instance`
 378   A pointer to the hash set instance to be examined, as returned by the [hash_set_create()](#hash_set_create) function.
 379
 380 * `capacity`
 381   A pointer to a variable of type `size_t` where the current total *capacity* of the hash set is stored.
 382   This value will always be greater than or equal to the sum of the *valid* and *deleted* entries.
 383
 384 * `valid`
 385   A pointer to a variable of type `size_t` where the current number of *valid* entries in the hash set is stored.
 386   This value is equivalent to the return value of the [hash_set_size()](#hash_set_size) function.
 387
 388 * `deleted`
 389   A pointer to a variable of type `size_t` where the current number of *deleted* entries in the hash set is stored.
 390   For technical reasons, entires are *not* removed from the set immediately, but are marked as "deleted".
 391
 392 * `limit`
 393   A pointer to a variable of type `size_t` where the current "grow" *limit* of the hash set is stored.
 394   The hash set is grown automatically, as soon as the sum of the *valid* and *deleted* entries exceeds this limit.
 395
 396 #### Return value
 397
 398 On success, this function returns *zero*. On error, the appropriate error code is returned. Possible error codes include:
 399
 400 * `EINVAL`
 401   An invalid argument was given, e.g. `instance` was set to `NULL`.
 402
 403 * `EFAULT`
 404   Something else went wrong. This usually indicates an internal error and is *not* supposed to happen.
 405
 406 ### hash_set_dump()
 407
 408 Dump the current status and content of all "slots" of the hash set.
 409
 410 ```C
 411 errno_t hash_set_dump(
 412         const hash_set_t *const instance,
 413         const hash_map_callback_t callback
 414 );
 415 ```
 416
 417 #### Parameters
 418
 419 * `instance`
 420   A pointer to the hash set instance to be examined, as returned by the [hash_set_create()](#hash_set_create) function.
 421
 422 * `callback`
 423   A pointer to the callback function that will be invoked once for every "slot" in the hash set.
 424
 425   The callback function is defined as follows:
 426   ```C
 427   typedef int (*hash_map_callback_t)(
 428         const size_t index,
 429         const char status,
 430         const value_t key,
 431         const value_t value
 432   );
 433   ```
 434
 435   ##### Parameters
 436
 437   * `index`
 438     The index of the current "slot" within the hash set.
 439
 440   * `status`
 441     Indicates the status of the current "slot":
 442     - `'u'` &ndash; the slot is *unused*
 443     - `'v'` &ndash; the slot is *valid*
 444     - `'d'` &ndash; the slot is *deleted*
 445
 446   * `item`
 447     The item that is stored at the current "slot" index.
 448
 449   ##### Return value
 450
 451   If the function returns a *non-zero* value, the iteration continues; otherwise it is cancelled.
 452
 453 #### Return value
 454
 455 On success, this function returns *zero*. On error, the appropriate error code is returned. Possible error codes include:
 456
 457 * `EINVAL`
 458   An invalid argument was given, e.g. `instance` was set to `NULL`.
 459
 460 * `ECANCELED`
 461   The operation was cancelled by the calling application.
 462
 463 * `EFAULT`
 464   Something else went wrong. This usually indicates an internal error and is *not* supposed to happen.
 465
 466 Map Functions
 467 -------------
 468
 469 This section describes all functions for managing `hash_map_t` instances.
 470
 471 ### hash_map_create()
 472
 473 Allocates a new hash map instance. The new hash map instance is empty initially.
 474
 475 ```C
 476 hash_map_t *hash_map_create(
 477         const size_t initial_capacity,
 478         const double load_factor,
 479         const uint64_t seed
 480 );
 481 ```
 482
 483 #### Parameters
 484
 485 * `initial_capacity`
 486   The initial capacity of the hash map. The given count will be rounded to the next power of two. If the number of key-value pairs to be inserted into the hash map can be estimated beforehand, then the initial capacity should be adjusted accordingly to avoid unnecessary re-allocations. In any case, the hash map will be able to grow dynamically as needed. If this parameter is map to *zero*, the the *default* initial capacity (8192) is used.
 487
 488 * `load_factor`
 489   The load factor to be applied to the hash map. The given load factor will be clipped to the **0.1** to **1.0** range. Generally, the default load factor (0.75) offers a good trade-off between performance and memory usage. Higher load factors decrease the memory overhead, but also may increase the time required for insert, lookup and remove operations. If this parameter is less than or equal to *zero*, the *default* load factor is used.
 490
 491 * `seed`
 492   The "seed" value that is used to tweak the internal hash computation. The application should set this parameter to a value that is hard to predict and that is unlikely to repeat (e.g., a high-resolution timer is suitable here).
 493
 494 #### Return value
 495
 496 On success, this function returns a pointer to a new hash map instance. On error, a `NULL` pointer is returned.
 497
 498 ***Note:*** To avoid a memory leak, the returned pointer must be de-allocated by the application using the [hash_map_destroy()](#hash_map_destroy) function, as soon as the instance is *not* needed anymore!
 499
 500 ### hash_map_destroy()
 501
 502 De-allocates an existing hash map instance. All key-value pairs in the hash map are discarded.
 503
 504 ```C
 505 void hash_map_destroy(
 506         hash_map_t *instance
 507 );
 508 ```
 509
 510 #### Parameters
 511
 512 * `instance`
 513   A pointer to the hash map instance that is to be destroyed, as returned by the [hash_map_create()](#hash_map_create) function.
 514   ***Note:*** The given pointer is *invalidated* by this function, and it **must not** be used afterwards!
 515
 516 ### hash_map_insert()
 517
 518 Tries to insert the given key-value pair into the hash map.
 519
 520 ***Note:*** If the key is actually inserted, then the hash map *may* need to grow.
 521
 522 ```C
 523 errno_t hash_map_insert(
 524         hash_map_t *const instance,
 525         const value_t key,
 526         const value_t value,
 527         const int update
 528 );
 529 ```
 530
 531 #### Parameters
 532
 533 * `instance`
 534   A pointer to the hash map instance to be modified, as returned by the [hash_map_create()](#hash_map_create) function.
 535
 536 * `key`
 537   The key to be inserted into the hash map.
 538
 539 * `value`
 540   The value to be associated with the given key.
 541
 542 * `update`
 543   If the map already contains the specified key, then if this parameter is *non-zero*, the value associated with the existing key will be updated; otherwise, the value currently associated with key remains unchanged.
 544
 545 #### Return value
 546
 547 On success, this function returns *zero*. On error, the appropriate error code is returned. Possible error codes include:
 548
 549 * `EINVAL`
 550   An invalid argument was given, e.g. `instance` was map to `NULL`.
 551
 552 * `EEXIST`
 553   The given key was *not* inserted into the hash map (again), because it was already present.
 554   Nonetheless, if `update` was non-zero, the value associated with the existing key has been updated.
 555
 556 * `ENOMEM`
 557   The map failed to grow, because the required amount of memory could *not* be allocated (out of memory).
 558
 559 * `EFBIG`
 560   The map needs to grow, but doing so would exceed the maximum size supported by the underlying system.
 561
 562 * `EFAULT`
 563   Something else went wrong. This usually indicates an internal error and is *not* supposed to happen.
 564
 565 ### hash_map_remove()
 566
 567 Tries to remove the given key from the hash map. The operation fails, if the map does *not* contain the given key.
 568
 569 The value associated with the removed key is discarded.
 570
 571 ***Note:*** If the key is actually removed, then the hash map *may* shrink.
 572
 573 ```C
 574 errno_t hash_map_remove(
 575         hash_map_t *const instance,
 576         const value_t key,
 577         value_t *const value
 578 );
 579 ```
 580
 581 #### Parameters
 582
 583 * `instance`
 584   A pointer to the hash map instance to be modified, as returned by the [hash_map_create()](#hash_map_create) function.
 585
 586 * `key`
 587   The key to be removed from the hash map.
 588
 589 * `value`
 590   A pointer to a variable of type `value_t` where the value that was associated with the deleted key is stored.
 591   The content of the variable should be considered *undefined*, if the key could *not* be removed.
 592   ***Note:*** This parameter can be set to `NULL`, in which case the value will *not* be reported to the application.
 593
 594 #### Return value
 595
 596 On success, this function returns *zero*. On error, the appropriate error code is returned. Possible error codes include:
 597
 598 * `EINVAL`
 599   An invalid argument was given, e.g. `instance` was map to `NULL`.
 600
 601 * `ENOENT`
 602   The given key could *not* be removed from the hash map, because *no* such key was present.
 603
 604 * `EFAULT`
 605   Something else went wrong. This usually indicates an internal error and is *not* supposed to happen.
 606
 607 ### hash_map_clear()
 608
 609 Discards *all* key-value pairs from the hash map at once.
 610
 611 ```C
 612 errno_t hash_map_clear(
 613         hash_map_t *const instance
 614 );
 615 ```
 616 #### Parameters
 617
 618 * `instance`
 619   A pointer to the hash map instance to be modified, as returned by the [hash_map_create()](#hash_map_create) function.
 620
 621 #### Return value
 622
 623 On success, this function returns *zero*. On error, the appropriate error code is returned. Possible error codes include:
 624
 625 * `EINVAL`
 626   An invalid argument was given, e.g. `instance` was map to `NULL`.
 627
 628 * `EAGAIN`
 629   The hash map was *not* cleared, because it already was empty. Please try again later!
 630
 631 * `EFAULT`
 632   Something else went wrong. This usually indicates an internal error and is *not* supposed to happen.
 633
 634 ### hash_map_contains()
 635
 636 Tests whether the hash map contains a key. The operation fails, if the map does *not* contain the given key.
 637
 638 ```C
 639 errno_t hash_map_contains(
 640         const hash_map_t *const instance,
 641         const value_t key
 642 );
 643 ```
 644
 645 #### Parameters
 646
 647 * `instance`
 648   A pointer to the hash map instance to be examined, as returned by the [hash_map_create()](#hash_map_create) function.
 649
 650 * `key`
 651   The key to be searched in the hash map.
 652
 653 #### Return value
 654
 655 On success, this function returns *zero*. On error, the appropriate error code is returned. Possible error codes include:
 656
 657 * `EINVAL`
 658   An invalid argument was given, e.g. `instance` was map to `NULL`.
 659
 660 * `ENOENT`
 661   The hash map does *not* contain the specified key.
 662
 663 * `EFAULT`
 664   Something else went wrong. This usually indicates an internal error and is *not* supposed to happen.
 665
 666 ### hash_map_get()
 667
 668 Retrieves the value that is associated with the given key. The operation fails, if the map does *not* contain the key.
 669
 670 ```C
 671 errno_t hash_map_get(
 672         const hash_map_t *const instance,
 673         const value_t key,
 674         value_t *const value
 675 );
 676 ```
 677
 678 #### Parameters
 679
 680 * `instance`
 681   A pointer to the hash map instance to be examined, as returned by the [hash_map_create()](#hash_map_create) function.
 682
 683 * `key`
 684   The key to be searched in the hash map.
 685
 686 * `value`
 687   A pointer to a variable of type `value_t` where the value associated with the key is stored on success.
 688   The content of the variable should be considered *undefined*, if the invocation has failed.
 689
 690 #### Return value
 691
 692 On success, this function returns *zero*. On error, the appropriate error code is returned. Possible error codes include:
 693
 694 * `EINVAL`
 695   An invalid argument was given, e.g. `instance` was map to `NULL`.
 696
 697 * `ENOENT`
 698   The hash map does *not* contain the specified key.
 699
 700 * `EFAULT`
 701   Something else went wrong. This usually indicates an internal error and is *not* supposed to happen.
 702
 703 ### hash_map_iterate()
 704
 705 Iterates through the key-value pairs stored in the hash map. The entries are iterated in **no** particular order.
 706
 707 This function returns one key-value pair at a time. It should be called *repeatedly*, until the end of the map is encountered.
 708
 709 ***Warning:*** The result is *undefined*, if the map is modified while the iteration is in progress!
 710
 711 ```C
 712 errno_t hash_map_iterate(
 713         const hash_map_t *const instance,
 714         size_t *const cursor,
 715         value_t *const key,
 716         value_t *const value
 717 );
 718 ```
 719
 720 #### Parameters
 721
 722 * `instance`
 723   A pointer to the hash map instance to be examined, as returned by the [hash_map_create()](#hash_map_create) function.
 724
 725 * `cursor`
 726   A pointer to a variable of type `size_t` where the current iterator state (position) is saved.
 727   This variable **must** be initialized to the value `0U`, by the calling application, prior to the the *first* invocation!
 728   Each invocation will update the value of `*cursor`. This value **shall not** be altered by the application.
 729
 730 * `key`
 731   A pointer to a variable of type `value_t` where the next key in the map is stored on success.
 732   The content of the variable should be considered *undefined*, if the invocation has failed.
 733
 734 * `value`
 735   A pointer to a variable of type `value_t` where the next value in the map is stored on success.
 736   The content of the variable should be considered *undefined*, if the invocation has failed.
 737
 738 #### Return value
 739
 740 On success, this function returns *zero*. On error, the appropriate error code is returned. Possible error codes include:
 741
 742 * `EINVAL`
 743   An invalid argument was given, e.g. `instance` was map to `NULL`.
 744
 745 * `ENOENT`
 746   No more entries. The end of the map has been encountered.
 747
 748 * `EFAULT`
 749   Something else went wrong. This usually indicates an internal error and is *not* supposed to happen.
 750
 751 ### hash_map_size()
 752
 753 Returns the current number of (distinct) keys in the hash map.
 754
 755 ```C
 756 size_t hash_map_size(
 757         const hash_map_t *const instance
 758 );
 759 ```
 760
 761 #### Parameters
 762
 763 * `instance`
 764   A pointer to the hash map instance to be examined, as returned by the [hash_map_create()](#hash_map_create) function.
 765
 766 #### Return value
 767
 768 This function returns the number of (distinct) keys in the hash map.
 769
 770 ### hash_map_info()
 771
 772 Returns technical information about the hash map.
 773
 774 ```C
 775 errno_t hash_map_info(
 776         const hash_map_t *const instance,
 777         size_t *const capacity,
 778         size_t *const valid,
 779         size_t *const deleted,
 780         size_t *const limit
 781 );
 782 ```
 783
 784 #### Parameters
 785
 786 * `instance`
 787   A pointer to the hash map instance to be examined, as returned by the [hash_map_create()](#hash_map_create) function.
 788
 789 * `capacity`
 790   A pointer to a variable of type `size_t` where the current total *capacity* of the hash map is stored.
 791   This value will always be greater than or equal to the sum of the *valid* and *deleted* entries.
 792
 793 * `valid`
 794   A pointer to a variable of type `size_t` where the current number of *valid* entries in the hash map is stored.
 795   This value is equivalent to the return value of the [hash_map_size()](#hash_map_size) function.
 796
 797 * `deleted`
 798   A pointer to a variable of type `size_t` where the current number of *deleted* entries in the hash map is stored.
 799   For technical reasons, entires are *not* removed from the map immediately, but are marked as "deleted".
 800
 801 * `limit`
 802   A pointer to a variable of type `size_t` where the current "grow" *limit* of the hash map is stored.
 803   The hash map is grown automatically, as soon as the sum of the *valid* and *deleted* entries exceeds this limit.
 804
 805 #### Return value
 806
 807 On success, this function returns *zero*. On error, the appropriate error code is returned. Possible error codes include:
 808
 809 * `EINVAL`
 810   An invalid argument was given, e.g. `instance` was map to `NULL`.
 811
 812 * `EFAULT`
 813   Something else went wrong. This usually indicates an internal error and is *not* supposed to happen.
 814
 815 ### hash_map_dump()
 816
 817 Dump the current status and content of all "slots" of the hash map.
 818
 819 ```C
 820 errno_t hash_map_dump(
 821         const hash_map_t *const instance,
 822         const hash_map_callback_t callback
 823 );
 824 ```
 825
 826 #### Parameters
 827
 828 * `instance`
 829   A pointer to the hash map instance to be examined, as returned by the [hash_map_create()](#hash_map_create) function.
 830
 831 * `callback`
 832   A pointer to the callback function that will be invoked once for every "slot" in the hash map.
 833
 834   The callback function is defined as follows:
 835   ```C
 836   typedef int (*hash_map_callback_t)(
 837         const size_t index,
 838         const char status,
 839         const value_t key,
 840         const value_t value
 841   );
 842   ```
 843
 844   ##### Parameters
 845
 846   * `index`
 847     The index of the current "slot" within the hash map.
 848
 849   * `status`
 850     Indicates the status of the current "slot":
 851     - `'u'` &ndash; the slot is *unused*
 852     - `'v'` &ndash; the slot is *valid*
 853     - `'d'` &ndash; the slot is *deleted*
 854
 855   * `key`
 856     The key that is stored at the current "slot" index.
 857
 858   * `value`
 859     The value that is stored at the current "slot" index.
 860
 861   ##### Return value
 862
 863   If the function returns a *non-zero* value, the iteration continues; otherwise it is cancelled.
 864
 865 #### Return value
 866
 867 On success, this function returns *zero*. On error, the appropriate error code is returned. Possible error codes include:
 868
 869 * `EINVAL`
 870   An invalid argument was given, e.g. `instance` was map to `NULL`.
 871
 872 * `ECANCELED`
 873   The operation was cancelled by the calling application.
 874
 875 * `EFAULT`
 876   Something else went wrong. This usually indicates an internal error and is *not* supposed to happen.
 877
 878 Thread Safety
 879 -------------
 880
 881 LibHashSet is ***thread-safe***, in the sense that all public functions operate *exclusively* on the given `hash_set_t` or `hash_map_t` instance; there is **no** implicit shared "global" state. This means that **no** synchronization is required in multi-threaded applications, provided that each instance is created and accessed only by a ***single*** thread.
 882
 883 However, LibHashSet does **nothing** to synchronize access to a particular `hash_set_t` or `hash_map_t` instance! Consequently, in situations where the *same* instance needs to be shared across *multiple* concurrent threads, the calling application is responsible for serializing all access to the "shared" instance, e.g. by using a [*mutex*](https://pubs.opengroup.org/onlinepubs/007908799/xsh/pthread_mutex_lock.html) lock!
 884
 885 Source Code
 886 ===========
 887
 888 The "official" Git repository is mirrored at:
 889
 890 * `git clone https://github.com/lordmulder/HashSet.git` ([Browse](https://github.com/lordmulder/HashSet))
 891
 892 * `git clone https://gitlab.com/lord_mulder/libhashset.git` ([Browse](https://gitlab.com/lord_mulder/libhashset))
 893
 894 * `git clone https://repo.or.cz/HashSet.git` ([Browse](https://repo.or.cz/HashSet.git))
 895
 896 * `git clone https://punkindrublic.mooo.com:3000/Muldersoft/LibHashSet.git` ([Browse](https://punkindrublic.mooo.com:3000/Muldersoft/LibHashSet))
 897
 898
 899 Build Instructions
 900 ==================
 901
 902 This section describes how to build LibHashSet from the source codes.
 903
 904 Windows
 905 -------
 906
 907 On Microsoft Windows, project/solution files are provided to build LibHashSet with [Microsoft Visual Studio](https://visualstudio.microsoft.com/).
 908
 909 LibHashSet also can be built using *GCC* or *Clang* via [MSYS2/Mingw-w64](https://www.msys2.org/) or [Cygwin](https://www.cygwin.com/). Be sure that *GCC* (or *Clang*) and *GNU make* are installed. Then run `make` from the project base directory, in the MSYS2 (or Cygwin) shell!
 910
 911 Linux, &#42;BSD and MacOS X
 912 ---------------------------
 913
 914 On Linux, &#42;BSD or MacOS X, building LibHashSet with *GCC* or *Clang* is supported. *GNU make* is required to build.
 915
 916 Simply run `make` (or `gmake`, if on &#42;BSD) from the project base directory. That's it!
 917
 918 ### Influential environment variables
 919
 920 The following environment variables can be used to control the build process:
 921
 922 * `CC` &ndash; specifies the C compiler (default is `cc`)
 923
 924 * `STRIP` &ndash; set to a non-zero value in order to *strip* the generated binaries
 925
 926 * `STATIC` &ndash; set to a non-zero value in order to enable *static* linking for the example/test programs
 927
 928 * `FLTO` &ndash; set to a non-zero value in order to enable *link-time optimizer* (`-flto`)
 929
 930 * `DEBUG` &ndash; set to a non-zero value in order to enable "debug" build
 931
 932 * `ASAN` &ndash; set to a non-zero value in order to enable the [address-sanitizer](https://en.wikipedia.org/wiki/AddressSanitizer)
 933
 934
 935 License
 936 =======
 937
 938 This work has been released under the **CC0 1.0 Universal** license.
 939
 940 For details, please refer to:
 941 <https://creativecommons.org/publicdomain/zero/1.0/legalcode>
 942
 943
 944 &marker;