about.md- allocator.h.md
- array_list.h.md
- buffer.h.md
- collection.h.md
- collections.md
- compare.h.md
- features.md
- hash_key.h.md
- hash_map.h.md
- install.md
- iterator.h.md
- json.h.md
- kv_list.h.md
- license.md
- linked_list.h.md
- list.h.md
- map.h.md
- memory.md
- mempool.h.md
- parsers.md
- printf.h.md
- properties.h.md
- streams.h.md
- string.h.md
- strings.md
- test.h.md
- tree.h.md
- utils.md
1 # Hash Map
2
3 UCX provides a basic hash map implementation with a configurable number of buckets.
4 If you do not specify the number of buckets, a default of 16 buckets will be used.
5
6 You can always rehash the map with `cxMapRehash()` to change the number of buckets to something more efficient,
7 but you need to be careful, because when you use this function you are effectively locking into using this
8 specific hash map implementation, and you would need to remove all calls to this function when you want to
9 exchange the concrete map implementation with something different.
10
11 ```C
12 #include <cx/hash_map.h>
13
14 CxMap *cxHashMapCreate(const CxAllocator *allocator,
15 size_t itemsize, size_t buckets);
16
17 CxMap *cxHashMapCreateSimple(size_t itemsize);
18
19 int cxMapRehash(CxMap *map);
20 ```
21
22 The function `cxHashMapCreate()` creates a new [map](map.h.md) where both the map structure
23 and the contained buckets are allocated by the specified `allocator`.
24 The [default allocator](allocator.h.md#default-allocator) is used in `cxHashMapCreateSimple()`.
25
26 The map will store items of size `itemsize`.
27 You can use the `CX_STORE_POINTERS` macro for `itemsize` to indicate that the map shall store
28 pointers instead of actual items.
29
30 If you pass zero for the number of `buckets`, or use `cxHashMapSimple()`,
31 the map is initialized with a default of 16 buckets; otherwise the specified number of buckets is allocated.
32
33 The function `cxMapRehash()` allocates a new array of buckets and re-distributes all elements,
34 if the number of elements exceeds ¾ of the number of buckets.
35 Otherwise, no action is performed, and this function simply returns 0.
36 After rehashing, the number of buckets is at least 2½ times the number of elements.
37
38 > Advice if you want to create your own hash map structures:
39 > Calling `cxMapRehash()` on a map is only defined, when the map is based on the
40 > `struct cx_hash_map_s` structure.
41
42 <seealso>
43 <category ref="apidoc">
44 <a href="https://ucx.sourceforge.io/api/hash__map_8h.html">hash_map.h</a>
45 </category>
46 </seealso>
47
48