Mercurial > hg > ucx / changeset

--- a/docs/src/features.md	Mon Jul 03 18:37:19 2023 +0200
+++ b/docs/src/features.md	Fri Jul 07 17:11:15 2023 +0200
@@ -307,10 +307,38 @@
 
 *Header file:* [map.h](api/map_8h.html)
 
+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)(CxMap const *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.
+
 ### Hash Map
 
 *Header file:* [hash_map.h](api/hash__map_8h.html)
 
+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,
+but you need to be careful, because when you use this function you are effectively locking into using this
+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.
+
 ## Utilities
 
 *Header file:* [utils.h](api/utils_8h.html)