Mercurial > hg > ucx / file diff

--- a/docs/Writerside/topics/list.h.md	Fri Oct 10 12:26:43 2025 +0200
+++ b/docs/Writerside/topics/list.h.md	Fri Oct 10 17:24:19 2025 +0200
@@ -122,6 +122,8 @@
 
 int cxListInsertSorted(CxList *list, const void *elem);
 
+int cxListInsertUnique(CxList *list, const void *elem);
+
 size_t cxListAddArray(CxList *list, const void *array, size_t n);
 
 size_t cxListInsertArray(CxList *list, size_t index,
@@ -130,6 +132,9 @@
 size_t cxListInsertSortedArray(CxList *list,
         const void *array, size_t n);
 
+size_t cxListInsertUniqueArray(CxList *list,
+        const void *array, size_t n);
+
 int cxListInsertAfter(CxIterator *iter, const void *elem);
 
 int cxListInsertBefore(CxIterator *iter, const void *elem);
@@ -143,6 +148,7 @@
 Be aware that when the list is storing pointers, the allocated memory will be for the pointer, not the actual element's data.
 
 The function `cxListInsertSorted()` inserts the element at the correct position so that the list remains sorted according to the list's compare function.
+On top of that, `cxListInsertUnique()` inserts the element only if it is not already in the list. 
 
 When you are currently iterating through a list, you can insert elements before or after the current position of the iterator
 with `cxListInsertBefore()` or `cxListInsertAfter()`, respectively.
@@ -151,15 +157,20 @@
 If the list is storing pointers (cf. `cxCollectionStoresPointers()`), the pointer `elem` is directly added to the list.
 Otherwise, the contents at the location pointed to by `elem` are copied to the list's memory with the element size specified during creation of the list.
 
-On the other hand, the `array` argument for `cxListAddArray()`, `cxListInsertArray()`, and `cxListInsertSortedArray()`
+On the other hand, the `array` argument for `cxListAddArray()`, `cxListInsertArray()`, `cxListInsertSortedArray()`, and `cxListInsertUniqueArray()`
 must always point to an array of elements to be added (i.e., either an array of pointers or an array of actual elements).
 
-A special requirement for `cxListInsertSortedArray()` is, that the `array` must already be sorted.
+When calling `cxListInsertSortedArray()` or `cxListInsertUniqueArray()`, the `array` must already be sorted.
+
+The return values of the array-inserting functions are the number of elements that have been successfully _processed_.
+Usually this is equivalent to the number of inserted elements, except for `cxListInsertUniqueArray()`,
+where the actual number of inserted elements may be less than the number of successfully processed elements.
 
 > Implementations are required to optimize the insertion of a sorted array into a sorted list in linear time,
 > while inserting each element separately via `cxListInsertSorted()` may take quadratic time.
 
-> The functions `cxListInsertSorted()` and `cxListInsertSortedArray()` do neither check if the list is already sorted, nor do they actively sort the list.
+> The functions do not check if the list is already sorted, nor do they actively sort the list.
+> In debug builds, invoking the functions on unsorted lists may trigger an assertion.
 > {style="note"}
 
 ## Access and Find