docs/Writerside/topics/hash_map.h.md

# Hash Map

UCX provides a basic hash map implementation with a configurable number of buckets.
If you do not specify the number of buckets, a default of 16 buckets will be used.

You can always rehash the map with `cxMapRehash()` to change the number of buckets to something more efficient,
but you need to be careful, because when you use this function you are effectively locking into using this
specific hash map implementation, and you would need to remove all calls to this function when you want to
exchange the concrete map implementation with something different.

```C
#include <cx/hash_map.h>

CxMap *cxHashMapCreate(const CxAllocator *allocator,
        size_t itemsize, size_t buckets);

CxMap *cxHashMapCreateSimple(size_t itemsize);

int cxMapRehash(CxMap *map);
```

The function `cxHashMapCreate()` creates a new [map](map.h.md) where both the map structure
and the contained buckets are allocated by the specified `allocator`.
The [default allocator](allocator.h.md#default-allocator) is used in `cxHashMapCreateSimple()`.

The map will store items of size `itemsize`.
You can use the `CX_STORE_POINTERS` macro for `itemsize` to indicate that the map shall store
pointers instead of actual items.

If you pass zero for the number of `buckets`, or use `cxHashMapSimple()`,
the map is initialized with a default of 16 buckets; otherwise the specified number of buckets is allocated.

The function `cxMapRehash()` allocates a new array of buckets and re-distributes all elements,
if the number of elements exceeds ¾ of the number of buckets.
Otherwise, no action is performed, and this function simply returns 0.
After rehashing, the number of buckets is at least 2½ times the number of elements.

> Advice if you want to create your own hash map structures:
> Calling `cxMapRehash()` on a map is only defined, when the map is based on the
> `struct cx_hash_map_s` structure.

<seealso>
<category ref="apidoc">
<a href="https://ucx.sourceforge.io/api/hash__map_8h.html">hash_map.h</a>
</category>
</seealso>