Mercurial > hg > ucx / changeset

--- a/src/cx/array_list.h	Sun Nov 13 13:21:48 2022 +0100
+++ b/src/cx/array_list.h	Sun Nov 13 13:22:03 2022 +0100
@@ -46,6 +46,72 @@
 #endif
 
 /**
+ * Defines a reallocation mechanism for arrays.
+ */
+struct cx_array_reallocator_s {
+    /**
+     * Re-allocates space for the given array.
+     *
+     * Implementations are not required to free the original array.
+     * This allows re-allocation of static memory by allocating heap memory
+     * and copying the array contents. The information in \p data can keep
+     * track of the state of the memory or other additional allocator info.
+     *
+     * @param array the array to reallocate
+     * @param capacity the new capacity (number of elements)
+     * @param elem_size the size of each element
+     * @param data additional data
+     * @return a pointer to the reallocated memory or \c NULL on failure
+     */
+    void *(*realloc)(
+            void *array,
+            size_t capacity,
+            size_t elem_size,
+            void *data
+    );
+
+    /**
+     * Additional data.
+     */
+    void *data;
+};
+
+/**
+ * Copies elements from one array to another.
+ *
+ * The elements are copied to the \p target array at the specified \p index,
+ * overwriting possible elements. The index must be in range of the current
+ * array \p size. If the number of elements added would extend the array's size,
+ * and \p capacity is not \c NULL, the remaining capacity is used.
+ *
+ * If the capacity is insufficient to hold the new data, a reallocation
+ * attempt is made, unless the allocator is set to \c NULL, in which case
+ * this function ultimately returns a failure.
+ *
+ * @param target the target array
+ * @param size a pointer to the size of the target array
+ * @param capacity a pointer to the target array's capacity -
+ * \c NULL if only the size shall be used to bound the array
+ * @param index the index where the copied elements shall be placed
+ * @param src the source array
+ * @param elem_size the size of one element
+ * @param elem_count the number of elements to copy
+ * @param reallocator the array re-allocator to use, or \c NULL
+ * if re-allocation shall not happen
+ * @return zero on success, non-zero on failure
+ */
+int cx_array_copy(
+        void **target,
+        size_t *size,
+        size_t *capacity,
+        size_t index,
+        void const *src,
+        size_t elem_size,
+        size_t elem_count,
+        struct cx_array_reallocator_s const *reallocator
+) __attribute__((__nonnull__(1, 2, 5)));
+
+/**
  * Allocates an array list for storing elements with \p item_size bytes each.
  *
  * @param allocator the allocator for allocating the list memory