Mercurial > hg > ucx / file diff

--- a/src/cx/list.h	Sun Oct 06 19:17:41 2024 +0200
+++ b/src/cx/list.h	Mon Oct 07 20:20:21 2024 +0200
@@ -118,11 +118,20 @@
     );
 
     /**
-     * Member function for removing an element.
+     * Member function for removing elements.
+     *
+     * Implementations SHALL check if \p targetbuf is set and copy the elements
+     * to the buffer without invoking any destructor.
+     * When \p targetbuf is not set, the destructors SHALL be invoked.
+     *
+     * The function SHALL return the actual number of elements removed, which
+     * might be lower than \p num when going out of bounds.
      */
-    int (*remove)(
+    size_t (*remove)(
             struct cx_list_s *list,
-            size_t index
+            size_t index,
+            size_t num,
+            void *targetbuf
     );
 
     /**
@@ -512,7 +521,73 @@
         CxList *list,
         size_t index
 ) {
-    return list->cl->remove(list, index);
+    return list->cl->remove(list, index, 1, NULL) == 0;
+}
+
+/**
+ * Removes and returns the element at the specified index.
+ *
+ * No destructor is called and instead the element is copied to the
+ * \p targetbuf which MUST be large enough to hold the removed element.
+ *
+ * @param list the list
+ * @param index the index of the element
+ * @param targetbuf a buffer where to copy the element
+ * @return zero on success, non-zero if the index is out of bounds
+ */
+__attribute__((__nonnull__))
+static inline int cxListRemoveAndGet(
+        CxList *list,
+        size_t index,
+        void *targetbuf
+) {
+    return list->cl->remove(list, index, 1, targetbuf) == 0;
+}
+
+/**
+ * Removes multiple element starting at the specified index.
+ *
+ * If an element destructor function is specified, it is called for each
+ * element. It is guaranteed that the destructor is called before removing
+ * the element, however, due to possible optimizations it is neither guaranteed
+ * that the destructors are invoked for all elements before starting to remove
+ * them, nor that the element is removed immediately after the destructor call
+ * before proceeding to the next element.
+ *
+ * @param list the list
+ * @param index the index of the element
+ * @param num the number of elements to remove
+ * @return the actual number of removed elements
+ */
+__attribute__((__nonnull__))
+static inline size_t cxListRemoveArray(
+        CxList *list,
+        size_t index,
+        size_t num
+) {
+    return list->cl->remove(list, index, num, NULL);
+}
+
+/**
+ * Removes and returns multiple element starting at the specified index.
+ *
+ * No destructor is called and instead the elements are copied to the
+ * \p targetbuf which MUST be large enough to hold all removed elements.
+ *
+ * @param list the list
+ * @param index the index of the element
+ * @param num the number of elements to remove
+ * @param targetbuf a buffer where to copy the elements
+ * @return the actual number of removed elements
+ */
+__attribute__((__nonnull__))
+static inline size_t cxListRemoveArrayAndGet(
+        CxList *list,
+        size_t index,
+        size_t num,
+        void *targetbuf
+) {
+    return list->cl->remove(list, index, num, targetbuf);
 }
 
 /**