--- a/docs/Writerside/topics/map.h.md Tue Mar 11 12:05:01 2025 +0100
+++ b/docs/Writerside/topics/map.h.md Wed Mar 12 16:08:35 2025 +0100
@@ -13,7 +13,7 @@
CxMap *cxHashMapCreateSimple(size_t itemsize);
```
-The function `cxHashMapCreate()` creates a new [map](map.h.md) where both the map structure
+The function `cxHashMapCreate()` creates a new map where both the map structure
and the contained buckets are allocated by the specified `allocator`.
The default stdlib allocator is used in `cxHashMapCreateSimple()`.
@@ -32,9 +32,14 @@
## Overview
<warning>
-TODO: write example
+TODO: example
</warning>
+> In the following Sections, the type for the key is denoted `KeyType`.
+> All functions are implemented as generics, so that the following types are supported:
+> `CxHashKey`, `cxstring`, `cxmutstr`, `const char*`, and `char*`.
+> {style="note"}
+
## Insert
```C
@@ -43,9 +48,18 @@
int cxMapPut(CxMap *map, KeyType key, void *value);
```
-<warning>
-TODO: document
-</warning>
+The function `cxMapPut()` stores the specified `key` / `value` pair.
+
+The key is always copied.
+The behavior for the value is dependent on whether the map is storing pointers.
+If it is storing pointers, the `value` pointer is directly stored in the map.
+Otherwise, the memory pointed to by `value` is copied, using the element size of the collection.
+
+If an element is already associated with the specified key, it is replaced.
+If [destructor functions](collection.h.md#destructor-functions) are registered,
+they are invoked for the old element before it is replaced.
+
+This function returns zero if the element was successfully put into the map and non-zero otherwise.
## Access
@@ -57,9 +71,10 @@
size_t cxMapSize(const CxMap *map);
```
-<warning>
-TODO: document
-</warning>
+With the function `cxMapGet()` you can retrieve a value stored under the specified `key`.
+If there is no such value, this function returns `NULL`.
+
+The function `cxMapSize()` returns how many key/value-pairs are currently stored in the map.
## Remove
@@ -73,31 +88,45 @@
void cxMapClear(CxMap *map);
```
-<warning>
-TODO: document
-</warning>
+The function `cxMapRemove()` retrieves and removes a value stored under the specified `key`.
+If [destructor functions](collection.h.md#destructor-functions) are registered, they are called before removal.
+
+On the other hand, `cxMapRemoveAndGet()` does not invoke the destructor functions,
+and instead copies the value into the `targetbuf` which must be sufficiently large to hold the value.
+
+In either case, the functions return zero when an element was found under the specified key, and non-zero otherwise.
+
+The function `cxMapClear()` removes all elements from the map, invoking the destructor functions for each of them.
## Iterators
```C
#include <cx/map.h>
-CxMapIterator cxMapIteratorValues(const CxMap *map);
+CxMapIterator cxMapIterator(const CxMap *map);
CxMapIterator cxMapIteratorKeys(const CxMap *map);
CxMapIterator cxMapIteratorValues(const CxMap *map);
-CxMapIterator cxMapMutIteratorValues(CxMap *map);
+CxMapIterator cxMapMutIterator(CxMap *map);
CxMapIterator cxMapMutIteratorKeys(CxMap *map);
CxMapIterator cxMapMutIteratorValues(CxMap *map);
```
-<warning>
-TODO: document
-</warning>
+The above functions create a ([mutating](iterator.h.md#mutating-iterators)) iterator over the
+pairs, keys, or values of the specified `map`, respectively.
+
+Iterators over pairs yield elements of type `CxMapEntry*` which is a struct containing a pointer to the `key` and the value, respectively.
+
+Iterators over keys yield elements of type `const CxHashKey*` (cf. [CxHashKey documentation](hash_key.h.md)).
+
+The behavior of iterators over values depends on the concrete implementation.
+Implementations are encouraged to support `CX_STORE_POINTERS`.
+If used, the `void*` elements the iterator yields, shall be directly the stored pointers.
+Otherwise, the iterator shall yield pointers to the map's memory where the value is stored.
## Dispose
@@ -107,9 +136,8 @@
void cxMapFree(CxMap *map);
```
-<warning>
-TODO: document
-</warning>
+The function `cxMapFree()` invokes the [destructor functions](collection.h.md#destructor-functions) for all elements,
+and then deallocates the entire memory for the map.
## Implement own Map Structures
@@ -121,9 +149,26 @@
```
<warning>
-TODO: document
+TODO: example
</warning>
+The required behavior for the implementations is described in the following table.
+You can always look at the source code of the UCX hash map to get inspiration.
+
+| Function | Description |
+|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `clear` | Invoke [destructor functions](collection.h.md#destructor-functions) on all elements and remove them from the map. |
+| `deallocate` | Invoke destructor functions on all elements and deallocate the entire map memory. |
+| `put` | Store an element in the map. If an element is already stored, invoke the destructor functions on that element and replace it with the new element. Return non-zero when allocating memory fails. |
+| `get` | Look up the specified key and return the associated value (or `NULL` if the key was not found). |
+| `remove` | Remove an element from the map. If a target buffer is specified, copy the elements to that buffer. Otherwise, invoke the destructor functions for the element. If the key was not found in the map, return non-zero. |
+| `iterator` | Return an iterator over the pairs, the keys, or the values, depending on the iterator type passed with the last argument. |
+
+> In contrast to the list interface, there is no `cx_map_init()` function which automatically
+> configures a wrapping mechanism when `CX_STORE_POINTERS` is used.
+> That means, in the implementation of the above functions you must take care of distinguishing between
+> maps that are storing pointers and that are storing elements yourself (if you want to support both).
+>{style="note"}
<seealso>
<category ref="apidoc">