docs/Writerside/topics/map.h.md

# Map Interface

<warning>
Outdated Section - will be updated soon!
</warning>

Similar to the list interface, the map interface provides a common API for implementing maps.
There are some minor subtle differences, though.

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);
```
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.

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);
```
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.

<!--
## Undocumented Symbols (TODO)
### cx_empty_map
### cxEmptyMap
### cxMapFree
### cxMapMutIterator
### cxMapMutIteratorKeys
### cxMapMutIteratorValues
-->

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