Mercurial > hg > ucx / changeset

--- a/docs/Writerside/topics/hash_key.h.md	Tue Mar 11 12:05:01 2025 +0100
+++ b/docs/Writerside/topics/hash_key.h.md	Wed Mar 12 16:08:35 2025 +0100
@@ -25,10 +25,9 @@
 
 In all cases, the hash will be available in the `hash` field of the returned structure.
 
-<note>
-UCX assigns the hash value <code>1574210520</code> to the <code>NULL</code> pointer.
-This is a careful choice which is not standard MurmurHash2 and an extension to support <code>NULL</code> pointers.
-</note>
+
+> UCX assigns the hash value `1574210520` to the `NULL` pointer.
+> This is a careful choice which is not standard MurmurHash2 and an extension to support `NULL` pointers.
 
 If you want to create a hash completely manually,
 you can initialize the `data` and `len` members of `CxHashKey`

--- a/docs/Writerside/topics/list.h.md	Tue Mar 11 12:05:01 2025 +0100
+++ b/docs/Writerside/topics/list.h.md	Wed Mar 12 16:08:35 2025 +0100
@@ -326,7 +326,7 @@
 ```C
 // define the class with pointers to your functions
 static cx_list_class my_list_class = {
-        my_list_destructor,
+        my_list_deallocate,
         my_list_insert_element,
         my_list_insert_array,
         my_list_insert_sorted,
@@ -373,7 +373,7 @@
 | Function         | Description                                                                                                                                                                                                                                                                                                                |
 |------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `clear`          | Invoke destructor functions on all elements and remove them from the list.                                                                                                                                                                                                                                                 |
-| `destructor`     | Invoke destructor functions on all elements and deallocate the entire list memory.                                                                                                                                                                                                                                         |
+| `deallocate`     | Invoke destructor functions on all elements and deallocate the entire list memory.                                                                                                                                                                                                                                         |
 | `insert_element` | Insert a single element at the specified index. Return zero on success and non-zero on failure.                                                                                                                                                                                                                            |
 | `insert_array`   | Insert an array of elements starting at the specified index. Return the number of elements inserted.                                                                                                                                                                                                                       |
 | `insert_sorted`  | Insert an array of sorted elements into a sorted list. Return the number of elements inserted.                                                                                                                                                                                                                             |

--- 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">