Mercurial > hg > ucx / changeset

     1.1 --- a/docs/src/features.md	Mon Jul 03 18:37:19 2023 +0200
     1.2 +++ b/docs/src/features.md	Fri Jul 07 17:11:15 2023 +0200
     1.3 @@ -307,10 +307,38 @@
     1.4  
     1.5  *Header file:* [map.h](api/map_8h.html)
     1.6  
     1.7 +Similar to the list interface, the map interface provides a common API for implementing maps.
     1.8 +There are some minor subtle differences, though.
     1.9 +
    1.10 +First, the `remove` method is not always a destructive removal.
    1.11 +Instead, the last argument is a Boolean that indicates whether the element shall be destroyed or returned.
    1.12 +```c
    1.13 +void *(*remove)(CxMap *map, CxHashKey key, bool destroy);
    1.14 +```
    1.15 +When you implement this method, you are either supposed to invoke the destructors and return `NULL`,
    1.16 +or just remove the element from the map and return it.
    1.17 +
    1.18 +Secondly, the iterator method is a bit more complete. The signature is as follows:
    1.19 +```c
    1.20 +CxIterator (*iterator)(CxMap const *map, enum cx_map_iterator_type type);
    1.21 +```
    1.22 +There are three map iterator types: for values, for keys, for pairs.
    1.23 +Depending on the iterator type requested, you need to create an iterator with the correct methods that
    1.24 +return the requested thing.
    1.25 +There are no automatic checks to enforce this - it's completely up to you.
    1.26 +If you need inspiration on how to do that, check the hash map implementation that comes with UCX.
    1.27 +
    1.28  ### Hash Map
    1.29  
    1.30  *Header file:* [hash_map.h](api/hash__map_8h.html)
    1.31  
    1.32 +UCX provides a basic hash map implementation with a configurable amount of buckets.
    1.33 +If you do not specify the number of buckets, a default of 16 buckets will be used.
    1.34 +You can always rehash the map with `cxMapRehash()` to change the number of buckets to something more efficient,
    1.35 +but you need to be careful, because when you use this function you are effectively locking into using this
    1.36 +specific hash map implementation, and you would need to remove all calls to this function when you want to
    1.37 +exchange the concrete map implementation with something different.
    1.38 +
    1.39  ## Utilities
    1.40  
    1.41  *Header file:* [utils.h](api/utils_8h.html)