Mercurial > hg > ucx / changeset

--- a/CHANGELOG	Thu Oct 23 17:38:44 2025 +0200
+++ b/CHANGELOG	Thu Oct 23 17:50:28 2025 +0200
@@ -6,7 +6,7 @@
  * adds new key-value-based list implementation
  + adds support for integer keys to CxHashKey
  * adds support for comparing arbitrary strings without explicit call to cx_strcast()
- * adds cxListClone()
+ * adds cxListClone() and cxMapClone()
  * adds cxListSet()
  * adds cxListContains()
  * adds cxListFirst() and cxListLast()

--- a/docs/Writerside/topics/about.md	Thu Oct 23 17:38:44 2025 +0200
+++ b/docs/Writerside/topics/about.md	Thu Oct 23 17:50:28 2025 +0200
@@ -33,7 +33,7 @@
 * adds new key-value-based list implementation
 * adds support for integer keys to CxHashKey
 * adds support for comparing arbitrary strings without explicit call to cx_strcast()
-* adds cxListClone()
+* adds cxListClone() and cxMapClone()
 * adds cxListSet()
 * adds cxListContains()
 * adds cxListFirst() and cxListLast()

--- a/docs/Writerside/topics/allocator.h.md	Thu Oct 23 17:38:44 2025 +0200
+++ b/docs/Writerside/topics/allocator.h.md	Thu Oct 23 17:50:28 2025 +0200
@@ -219,7 +219,7 @@
 }
 ```
 
-Clone functions are, for example, used by the functions to clone [lists](list.h.md#clone) or maps.
+Clone functions are, for example, used by the functions to clone [lists](list.h.md#clone) or [maps](map.h.md#clone).
 
 <seealso>
 <category ref="apidoc">

--- a/docs/Writerside/topics/map.h.md	Thu Oct 23 17:38:44 2025 +0200
+++ b/docs/Writerside/topics/map.h.md	Thu Oct 23 17:50:28 2025 +0200
@@ -279,6 +279,38 @@
 It is always safe to call the above functions on a `NULL`-pointer.
 In that case, the returned iterator will behave like an iterator over an empty map.
 
+## Clone
+
+```C
+#include <cx/allocator.h>
+
+typedef void*(cx_clone_func)(
+        void *target, const void *source,
+        const CxAllocator *allocator,
+        void *data);
+
+#include <cx/map.h>
+
+size_t cxMapClone(CxMap *dst, const CxMap *src,
+        cx_clone_func clone_func,
+        const CxAllocator *clone_allocator,
+        void *data);
+```
+
+With `cxMapClone()` you can create deep copies of the values in one map and insert them into another map.
+The destination map does not need to be empty.
+But when a key already exists in the destination map, the value is overwritten with the clone from the source map.
+If the destination map has destructors defined, they are called for the replaced element.
+
+Refer to the documentation of the [clone-function callback](allocator.h.md#clone-function) to learn how to implement it.
+
+The function returns the number of elements successfully cloned.
+If an allocation error occurs, this might be smaller than the size of the source map.
+
+> It is perfectly possible to clone items into a map of a different type.
+> For example, you can clone entries from a map that is just storing pointers (`CX_STORE_POINTERS`) to a map that
+> allocates the memory for the objects (and vice versa).
+
 ## Dispose
 
 ```C