Mercurial > hg > ucx / file diff

--- a/docs/Writerside/topics/list.h.md	Fri Nov 07 18:42:06 2025 +0100
+++ b/docs/Writerside/topics/list.h.md	Fri Nov 07 19:13:28 2025 +0100
@@ -380,6 +380,12 @@
         cx_clone_func clone_func,
         const CxAllocator *clone_allocator,
         void *data);
+        
+int cxListUnion(CxList *dst,
+        const CxList *src,  const CxList *other,
+        cx_clone_func clone_func,
+        const CxAllocator *clone_allocator,
+        void *data);
 ```
 
 With `cxListClone()` you can create deep copies of the elements in a list and insert them into another list.
@@ -387,10 +393,17 @@
 Depending on the concrete list implementation, `cxListClone()` tries to allocate enough memory up-front, before trying
 to insert anything.
 
-The function `cxListDifference()` is similar to `cxListClone()`,
-except that it only clones elements from the minuend that are _not_ contained in the subtrahend,
-while `cxListIntersection()` only clones elements that _are_ contained in both lists.
-Both functions are optimized for sorted lists, in which case they will take linear time instead of quadratic time for the operation.
+The function `cxListDifference()` clones elements from the `minuend` that are _not_ contained in the `subtrahend`,
+while `cxListIntersection()` only clones elements from the `src` that are _also_ contained in the `other` list.
+And `cxListUnion()` clones elements from `src` first, and from `other` only when they are _not_ contained in `src`.
+
+All three functions, for union, difference, and intersection, are optimized for sorted lists.
+In that case they will take linear time instead of quadratic time for the operation.
+Also, `cxListUnion()` makes sure that the elements from `src` and `other` are cloned interleaving,
+so that the result of the union is still sorted.
+
+However, when the `dst` list already contains elements, all functions will only append the result of the operation to that list.
+That means, the `dst` list is only guaranteed to be sorted, when it was empty and the input lists are all sorted.
 
 Refer to the documentation of the [clone-function callback](allocator.h.md#clone-function) to learn how to implement it.