Thu, 23 Oct 2025 17:50:28 +0200
add documentation for cxMapClone() - resolves #743
--- 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