Mercurial > hg > ucx / file diff

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