add documentation for cxListClone() - relates to #744 default tip

Thu, 23 Oct 2025 17:54:17 +0200

author
Mike Becker <universe@uap-core.de>
date
Thu, 23 Oct 2025 17:54:17 +0200
changeset 1441
78ec3e2243e4
parent 1440
0d1430668271

add documentation for cxListClone() - relates to #744

docs/Writerside/topics/list.h.md file | annotate | diff | comparison | revisions
--- a/docs/Writerside/topics/list.h.md	Thu Oct 23 17:50:28 2025 +0200
+++ b/docs/Writerside/topics/list.h.md	Thu Oct 23 17:54:17 2025 +0200
@@ -370,6 +370,20 @@
         void *data);
 ```
 
+With `cxListClone()` you can create deep copies of the elements in a list and insert them into another list.
+The destination list does not need to be empty, in which case the elements will be appended.
+Depending on the concrete list implementation, `cxListClone()` tries to allocate enough memory up-front, before trying
+to insert anything.
+
+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 list.
+
+> It is perfectly possible to clone items into a list of a different type.
+> For example, you can clone elements from a list that is just storing pointers (`CX_STORE_POINTERS`) to a list that
+> allocates the memory for the objects (and vice versa).
+
 ## Dispose
 
 ```C

mercurial