Mercurial > hg > ucx / file diff

--- a/src/cx/list.h	Mon Oct 20 19:44:18 2025 +0200
+++ b/src/cx/list.h	Mon Oct 20 20:10:36 2025 +0200
@@ -88,12 +88,16 @@
     /**
      * Member function for inserting multiple elements.
      *
+     * The data pointer may be @c NULL, in which case the function shall only allocate memory.
+     * Returns the number of successfully inserted or allocated elements.
+     *
      * @see cx_list_default_insert_array()
      */
     size_t (*insert_array)(struct cx_list_s *list, size_t index, const void *data, size_t n);
 
     /**
      * Member function for inserting sorted elements into a sorted list.
+     * Returns the number of successfully inserted elements.
      *
      * @see cx_list_default_insert_sorted()
      */
@@ -101,7 +105,8 @@
 
     /**
      * Member function for inserting multiple elements if they do not exist.
-     *
+     * Implementations shall return the number of successfully processed elements
+     * (including those which were not added because they are already contained).
      * @see cx_list_default_insert_unique()
      */
     size_t (*insert_unique)(struct cx_list_s *list, const void *sorted_data, size_t n);
@@ -359,6 +364,7 @@
  * @param array a pointer to the elements to add
  * @param n the number of elements to add
  * @return the number of added elements
+ * @see cxListEmplaceArray()
  */
 cx_attr_nonnull
 CX_EXPORT size_t cxListAddArray(CxList *list, const void *array, size_t n);
@@ -389,6 +395,7 @@
  * @param index the index where to emplace the element
  * @return a pointer to the allocated memory; @c NULL when the operation fails, or the index is out-of-bounds
  * @see cxListEmplace()
+ * @see cxListEmplaceArrayAt()
  * @see cxListInsert()
  */
 cx_attr_nonnull
@@ -408,6 +415,45 @@
 CX_EXPORT void *cxListEmplace(CxList *list);
 
 /**
+ * Allocates memory for multiple elements and returns an iterator.
+ *
+ * The iterator will only iterate over the successfully allocated elements.
+ * The @c elem_count attribute is set to that number, and the @c index attribute
+ * will range from zero to @c elem_count minus one.
+ *
+ * @remark When the list is storing pointers, the iterator will iterate over
+ * the @c void** elements.
+ *
+ * @param list the list
+ * @param index the index where to insert the new data
+ * @param n the number of elements for which to allocate the memory
+ * @return an iterator, iterating over the new memory
+ * @see cxListEmplaceAt()
+ * @see cxListInsertArray()
+ */
+cx_attr_nonnull
+CX_EXPORT CxIterator cxListEmplaceArrayAt(CxList *list, size_t index, size_t n);
+
+/**
+ * Allocates memory for multiple elements and returns an iterator.
+ *
+ * The iterator will only iterate over the successfully allocated elements.
+ * The @c elem_count attribute is set to that number, and the @c index attribute
+ * will range from zero to @c elem_count minus one.
+ *
+ * @remark When the list is storing pointers, the iterator will iterate over
+ * the @c void** elements.
+ *
+ * @param list the list
+ * @param n the number of elements for which to allocate the memory
+ * @return an iterator, iterating over the new memory
+ * @see cxListEmplace()
+ * @see cxListAddArray()
+ */
+cx_attr_nonnull
+CX_EXPORT CxIterator cxListEmplaceArray(CxList *list, size_t n);
+
+/**
  * Inserts an item into a sorted list.
  *
  * If the list is not sorted already, the behavior is undefined.
@@ -454,6 +500,7 @@
  * @param array a pointer to the elements to add
  * @param n the number of elements to add
  * @return the number of added elements
+ * @see cxListEmplaceArrayAt()
  */
 cx_attr_nonnull
 CX_EXPORT size_t cxListInsertArray(CxList *list, size_t index, const void *array, size_t n);