Mercurial > hg > ucx / file diff

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/Writerside/topics/map.h.md	Tue Feb 11 19:55:32 2025 +0100
@@ -0,0 +1,34 @@
+# Map Interface
+
+<warning>
+Outdated - Rewrite!
+</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