Mercurial > hg > ucx / changeset

--- a/docs/Writerside/topics/hash_map.h.md	Tue Mar 11 11:10:19 2025 +0100
+++ b/docs/Writerside/topics/hash_map.h.md	Tue Mar 11 12:05:01 2025 +0100
@@ -2,6 +2,7 @@
 
 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

--- a/docs/Writerside/topics/list.h.md	Tue Mar 11 11:10:19 2025 +0100
+++ b/docs/Writerside/topics/list.h.md	Tue Mar 11 12:05:01 2025 +0100
@@ -36,6 +36,11 @@
 
 > When you create a list which is storing pointers and do not specify a compare function, `cx_cmp_ptr` will be used by default.
 
+> If you want to lazy-initialize lists, you can use the global `cxEmptyList` symbol as a placeholder instead of using a `NULL`-pointer.
+> While you *must not* insert elements into that list, you can safely access this list or create iterators.
+> This allows you to write clean code without checking for `NULL`-pointer everywhere.
+> You still need to make sure that the placeholder is replaced with an actual list before inserting elements.
+
 ## Example
 
 In the following example we create a linked-list of regular expressions for filtering data.
@@ -100,12 +105,7 @@
 However, it should be clear by now that using `CX_STORE_POINTERS` is a bad choice for this use case to begin with.
 
 As a rule of thumb: if you allocate memory for an element that you immediately put into the list, consider storing the element directly.
-And if you are getting pointers to already allocated memory from somewhere else, and you just want to organize those elements in a list, then consider using `CX_STORE_POINTERS`. 
-
-> If you want to lazy-initialize lists, you can use the global `cxEmptyList` symbol as a placeholder instead of using a `NULL`-pointer.
-> While you *must not* insert elements into that list, you can safely access this list or create iterators.
-> This allows you to write clean code without checking for `NULL`-pointer everywhere.
-> You still need to make sure that the placeholder is replaced with an actual list before inserting elements.
+And if you are getting pointers to already allocated memory from somewhere else, and you just want to organize those elements in a list, then consider using `CX_STORE_POINTERS`.
 
 ## Insert
 

--- a/docs/Writerside/topics/map.h.md	Tue Mar 11 11:10:19 2025 +0100
+++ b/docs/Writerside/topics/map.h.md	Tue Mar 11 12:05:01 2025 +0100
@@ -1,39 +1,129 @@
 # 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.
+
+UCX is shipped with a [hash map](hash_map.h.md) implementation of this interface. 
 
-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);
+```C
+#include <cx/hash_map.h>
+
+CxMap *cxHashMapCreate(const CxAllocator *allocator,
+        size_t itemsize, size_t buckets);
+
+CxMap *cxHashMapCreateSimple(size_t itemsize);
 ```
-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.
+
+The function `cxHashMapCreate()` creates a new [map](map.h.md) where both the map structure
+and the contained buckets are allocated by the specified `allocator`.
+The default stdlib allocator is used in `cxHashMapCreateSimple()`.
+
+The map will store items of size `itemsize`.
+You can use the `CX_STORE_POINTERS` macro for `itemsize` to indicate that the map shall store
+pointers instead of actual items.
+
+If you pass zero for the number of `buckets`, or use `cxHashMapSimple()`,
+the map is initialized with a default of 16 buckets, otherwise the specified number of buckets is allocated.
+
+> If you want to lazy-initialize maps, you can use the global `cxEmptyMap` symbol as a placeholder instead of using a `NULL`-pointer.
+> While you *must not* insert elements into that map, you can safely access this map or create iterators.
+> This allows you to write clean code without checking for `NULL`-pointer everywhere.
+> You still need to make sure that the placeholder is replaced with an actual map before inserting elements.
+
+## Overview
 
-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);
+<warning>
+TODO: write example
+</warning>
+
+## Insert
+
+```C
+#include <cx/map.h>
+
+int cxMapPut(CxMap *map, KeyType key, void *value);
+```
+
+<warning>
+TODO: document
+</warning>
+
+## Access
+
+```C
+#include <cx/map.h>
+
+void *cxMapGet(CxMap *map, KeyType key);
+
+size_t cxMapSize(const CxMap *map);
 ```
-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.
+
+<warning>
+TODO: document
+</warning>
+
+## Remove
+
+```C
+#include <cx/map.h>
+
+int cxMapRemove(CxMap *map, KeyType key);
+
+int cxMapRemoveAndGet(CxMap *map, KeyType key, void* targetbuf);
+
+void cxMapClear(CxMap *map);
+```
+
+<warning>
+TODO: document
+</warning>
+
+## Iterators
+
+```C
+#include <cx/map.h>
+
+CxMapIterator cxMapIteratorValues(const CxMap *map);
+
+CxMapIterator cxMapIteratorKeys(const CxMap *map);
+
+CxMapIterator cxMapIteratorValues(const CxMap *map);
+
+CxMapIterator cxMapMutIteratorValues(CxMap *map);
 
-<!--
-## Undocumented Symbols (TODO)
-### cx_empty_map
-### cxEmptyMap
-### cxMapFree
-### cxMapMutIterator
-### cxMapMutIteratorKeys
-### cxMapMutIteratorValues
--->
+CxMapIterator cxMapMutIteratorKeys(CxMap *map);
+
+CxMapIterator cxMapMutIteratorValues(CxMap *map);
+```
+
+<warning>
+TODO: document
+</warning>
+
+## Dispose
+
+```C
+#include <cx/map.h>
+
+void cxMapFree(CxMap *map);
+```
+
+<warning>
+TODO: document
+</warning>
+
+## Implement own Map Structures 
+
+```C
+typedef struct cx_map_entry_s {
+    const CxHashKey *key;
+    void *value;
+} CxMapEntry;
+```
+
+<warning>
+TODO: document
+</warning>
+
 
 <seealso>
 <category ref="apidoc">