Mercurial > hg > ucx / changeset

--- a/docs/Writerside/topics/hash_map.h.md	Sun Feb 23 14:04:38 2025 +0100
+++ b/docs/Writerside/topics/hash_map.h.md	Mon Feb 24 20:39:29 2025 +0100
@@ -1,9 +1,5 @@
 # Hash Map
 
-<warning>
-Outdated Section - will be updated soon!
-</warning>
-
 UCX provides a basic hash map implementation with a configurable amount 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,
@@ -11,11 +7,36 @@
 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.
 
-<!--
-## Undocumented Symbols (TODO)
-### cxHashMapCreate
-### cxMapRehash
--->
+```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 stdlib 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">