Mercurial > hg > ucx / file diff

--- a/docs/Writerside/topics/list.h.md	Sun Oct 26 15:51:49 2025 +0100
+++ b/docs/Writerside/topics/list.h.md	Sun Oct 26 16:16:43 2025 +0100
@@ -368,6 +368,12 @@
         cx_clone_func clone_func,
         const CxAllocator *clone_allocator,
         void *data);
+
+int cxListDifference(CxList *dst,
+        const CxList *minuend, const CxList *subtrahend,
+        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.
@@ -375,9 +381,13 @@
 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.
+It is optimized for sorted lists, in which case it will take linear time instead of quadratic time for the operation.
+
 Refer to the documentation of the [clone-function callback](allocator.h.md#clone-function) to learn how to implement it.
 
-The function returns zero if and only if all clone operations were successful.
+The functions return zero if and only if all clone operations were successful.
 
 > 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