Mercurial > hg > ucx / file diff

--- a/src/cx/list.h	Fri Oct 17 14:14:21 2025 +0200
+++ b/src/cx/list.h	Fri Oct 17 15:04:56 2025 +0200
@@ -421,9 +421,12 @@
 CX_EXPORT int cxListInsertSorted(CxList *list, const void *elem);
 
 /**
- * Inserts an item into a sorted list if it does not exist.
+ * Inserts an item into a list if it does not exist.
  *
- * If the list is not sorted already, the behavior is undefined.
+ * If the list is not sorted already, this function will check all elements
+ * and append the new element when it was not found.
+ * It is strongly recommended to use this function only on sorted lists, where
+ * the element, if it is not contained, is inserted at the correct position.
  *
  * @param list the list
  * @param elem a pointer to the element to add
@@ -478,7 +481,14 @@
 CX_EXPORT size_t cxListInsertSortedArray(CxList *list, const void *array, size_t n);
 
 /**
- * Inserts a sorted array into a sorted list, skipping duplicates.
+ * Inserts an array into a list, skipping duplicates.
+ *
+ * The @p list does not need to be sorted (in contrast to cxListInsertSortedArray()).
+ * But it is strongly recommended to use this function only on sorted lists,
+ * because otherwise it will fall back to an inefficient algorithm which inserts
+ * all elements one by one.
+ * If the @p list is not sorted, the @p array also does not need to be sorted.
+ * But when the @p list is sorted, the @p array must also be sorted.
  *
  * This method is usually more efficient than inserting each element separately
  * because consecutive chunks of sorted data are inserted in one pass.
@@ -495,9 +505,6 @@
  * If this list is storing pointers instead of objects @p array is expected to
  * be an array of pointers.
  *
- * If the list is not sorted already, the behavior is undefined.
- * This is also the case when the @p array is not sorted.
- *
  * @param list the list
  * @param array a pointer to the elements to add
  * @param n the number of elements to add