diff -r bbb734f73392 -r 13e15cd529ae docs/Writerside/topics/map.h.md
--- a/docs/Writerside/topics/map.h.md Tue Mar 11 11:10:19 2025 +0100
+++ b/docs/Writerside/topics/map.h.md Tue Mar 11 12:05:01 2025 +0100
@@ -1,39 +1,129 @@
# Map Interface
-
-Outdated Section - will be updated soon!
-
-
Similar to the list interface, the map interface provides a common API for implementing maps.
-There are some minor subtle differences, though.
+
+UCX is shipped with a [hash map](hash_map.h.md) implementation of this interface.
-First, the `remove` method is not always a destructive removal.
-Instead, the last argument is a Boolean that indicates whether the element shall be destroyed or returned.
-```c
-void *(*remove)(CxMap *map, CxHashKey key, bool destroy);
+```C
+#include
+
+CxMap *cxHashMapCreate(const CxAllocator *allocator,
+ size_t itemsize, size_t buckets);
+
+CxMap *cxHashMapCreateSimple(size_t itemsize);
```
-When you implement this method, you are either supposed to invoke the destructors and return `NULL`,
-or just remove the element from the map and return it.
+
+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.
+
+> If you want to lazy-initialize maps, you can use the global `cxEmptyMap` symbol as a placeholder instead of using a `NULL`-pointer.
+> While you *must not* insert elements into that map, you can safely access this map or create iterators.
+> This allows you to write clean code without checking for `NULL`-pointer everywhere.
+> You still need to make sure that the placeholder is replaced with an actual map before inserting elements.
+
+## Overview
-Secondly, the iterator method is a bit more complete. The signature is as follows:
-```c
-CxIterator (*iterator)(const CxMap *map, enum cx_map_iterator_type type);
+
+TODO: write example
+
+
+## Insert
+
+```C
+#include
+
+int cxMapPut(CxMap *map, KeyType key, void *value);
+```
+
+
+TODO: document
+
+
+## Access
+
+```C
+#include
+
+void *cxMapGet(CxMap *map, KeyType key);
+
+size_t cxMapSize(const CxMap *map);
```
-There are three map iterator types: for values, for keys, for pairs.
-Depending on the iterator type requested, you need to create an iterator with the correct methods that
-return the requested thing.
-There are no automatic checks to enforce this - it's completely up to you.
-If you need inspiration on how to do that, check the hash map implementation that comes with UCX.
+
+
+TODO: document
+
+
+## Remove
+
+```C
+#include
+
+int cxMapRemove(CxMap *map, KeyType key);
+
+int cxMapRemoveAndGet(CxMap *map, KeyType key, void* targetbuf);
+
+void cxMapClear(CxMap *map);
+```
+
+
+TODO: document
+
+
+## Iterators
+
+```C
+#include
+
+CxMapIterator cxMapIteratorValues(const CxMap *map);
+
+CxMapIterator cxMapIteratorKeys(const CxMap *map);
+
+CxMapIterator cxMapIteratorValues(const CxMap *map);
+
+CxMapIterator cxMapMutIteratorValues(CxMap *map);
-
+CxMapIterator cxMapMutIteratorKeys(CxMap *map);
+
+CxMapIterator cxMapMutIteratorValues(CxMap *map);
+```
+
+
+TODO: document
+
+
+## Dispose
+
+```C
+#include
+
+void cxMapFree(CxMap *map);
+```
+
+
+TODO: document
+
+
+## Implement own Map Structures
+
+```C
+typedef struct cx_map_entry_s {
+ const CxHashKey *key;
+ void *value;
+} CxMapEntry;
+```
+
+
+TODO: document
+
+