Mercurial > hg > ucx / file diff

--- a/src/cx/list.h	Sun May 04 12:15:03 2025 +0200
+++ b/src/cx/list.h	Sun May 04 17:22:30 2025 +0200
@@ -80,8 +80,10 @@
 
     /**
      * Member function for inserting a single element.
+     * The data pointer may be @c NULL in which case the function shall only allocate memory.
+     * Returns a pointer to the data of the inserted element.
      */
-    int (*insert_element)(
+    void *(*insert_element)(
             struct cx_list_s *list,
             size_t index,
             const void *data
@@ -370,6 +372,7 @@
  * @retval zero success
  * @retval non-zero memory allocation failure
  * @see cxListAddArray()
+ * @see cxListEmplace()
  */
 cx_attr_nonnull
 static inline int cxListAdd(
@@ -377,7 +380,7 @@
         const void *elem
 ) {
     list->collection.sorted = false;
-    return list->cl->insert_element(list, list->collection.size, elem);
+    return list->cl->insert_element(list, list->collection.size, elem) == NULL;
 }
 
 /**
@@ -418,6 +421,7 @@
  * @retval non-zero memory allocation failure or the index is out of bounds
  * @see cxListInsertAfter()
  * @see cxListInsertBefore()
+ * @see cxListEmplaceAt()
  */
 cx_attr_nonnull
 static inline int cxListInsert(
@@ -426,7 +430,41 @@
         const void *elem
 ) {
     list->collection.sorted = false;
-    return list->cl->insert_element(list, index, elem);
+    return list->cl->insert_element(list, index, elem) == NULL;
+}
+
+/**
+ * Allocates memory for an element at the specified index and returns a pointer to that memory.
+ *
+ * @remark When the list is storing pointers, this will return a @c void**.
+ *
+ * @param list the list
+ * @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 cxListInsert()
+ */
+cx_attr_nonnull
+static inline void *cxListEmplaceAt(CxList *list, size_t index) {
+    list->collection.sorted = false;
+    return list->cl->insert_element(list, index, NULL);
+}
+
+
+/**
+ * Allocates memory for an element at the end of the list and returns a pointer to that memory.
+ *
+ * @remark When the list is storing pointers, this will return a @c void**.
+ *
+ * @param list the list
+ * @return a pointer to the allocated memory; @c NULL when the operation fails, or the index is out-of-bounds
+ * @see cxListEmplaceAt()
+ * @see cxListAdd()
+ */
+cx_attr_nonnull
+static inline void *cxListEmplace(CxList *list) {
+    list->collection.sorted = false;
+    return list->cl->insert_element(list, list->collection.size, NULL);
 }
 
 /**