Mercurial > hg > ucx / changeset

--- a/src/array_list.c	Tue Dec 16 11:48:52 2025 +0100
+++ b/src/array_list.c	Tue Dec 16 12:07:01 2025 +0100
@@ -80,7 +80,7 @@
     return 0;
 }
 
-int cx_array_move_to_new_(const CxAllocator *allocator, CxArray *array, size_t elem_size, size_t capacity) {
+int cx_array_copy_to_new_(const CxAllocator *allocator, CxArray *array, size_t elem_size, size_t capacity) {
     CxArray heap_array;
     if (cx_array_init_(allocator, &heap_array, elem_size, capacity)) {
         return -1; // LCOV_EXCL_LINE

--- a/src/cx/array_list.h	Tue Dec 16 11:48:52 2025 +0100
+++ b/src/cx/array_list.h	Tue Dec 16 12:07:01 2025 +0100
@@ -49,6 +49,12 @@
  */
 CX_EXPORT extern const unsigned cx_array_swap_sbo_size;
 
+/**
+ * Declares a typed array with size and capacity.
+ *
+ * @param type the type of the elements
+ * @param name the name of the array
+ */
 #define CX_ARRAY(type, name) \
     struct { \
         type *data; \
@@ -56,106 +62,570 @@
         size_t capacity; \
     } name
 
+/**
+ * Internal structure for arrays.
+ *
+ * A generalization of array structures declared with CX_ARRAY().
+ */
 typedef struct cx_array_s {
+    /** The array data. */
     void *data;
+    /** The number of elements. */
     size_t size;
+    /** The maximum number of elements. */
     size_t capacity;
 } CxArray;
 
+/**
+ * Initializes an array by allocating memory.
+ *
+ * Internal function - do not use manually.
+ *
+ * @param allocator the allocator for the array
+ * @param array a pointer to the array structure
+ * @param elem_size size of one element
+ * @param capacity the initial maximum number of elements
+ * @retval zero allocation was successful
+ * @retval non-zero allocation failed
+ */
 cx_attr_nonnull
 CX_EXPORT int cx_array_init_(const CxAllocator *allocator, CxArray *array, size_t elem_size, size_t capacity);
 
+/**
+ * Initializes an array by allocating memory.
+ *
+ * The size is set to zero.
+ *
+ * @attention If the array was already initialized, this will leak memory.
+ * Use cx_array_reserve() to change the capacity of an initialized array.
+ *
+ * @param allocator (@c CxAllocator*) the allocator for the array
+ * @param array the name of the array
+ * @param capacity (@c size_t) the initial maximum number of elements
+ * @retval zero allocation was successful
+ * @retval non-zero allocation failed
+ */
 #define cx_array_init_a(allocator, array, capacity) cx_array_init_(allocator, (CxArray*)&(array), sizeof((array).data[0]), capacity)
 
+/**
+ * Initializes an array by allocating memory.
+ *
+ * The size is set to zero.
+ *
+ * @attention If the array was already initialized, this will leak memory.
+ *
+ * @param array the name of the array
+ * @param capacity (@c size_t) the initial maximum number of elements
+ * @retval zero allocation was successful
+ * @retval non-zero allocation failed
+ */
 #define cx_array_init(array, capacity) cx_array_init_a(cxDefaultAllocator, array, capacity)
 
+/**
+ * Initializes an array with fixed size memory.
+ *
+ * Internal function - do not use manually.
+ *
+ * @param array a pointer to the array structure
+ * @param data the fixed size array
+ * @param capacity the capacity of the fixed size array
+ * @param size the number of initialized elements in the fixed size array
+ */
 cx_attr_nonnull
 CX_EXPORT void cx_array_init_fixed_(CxArray *array, const void *data, size_t capacity, size_t size);
 
-#define cx_array_init_fixed(array, fixed_size_array, num_initialized) cx_array_init_fixed_((CxArray*)&(array), fixed_size_array, cx_nmemb(fixed_size_array), num_initialized)
+/**
+ * Initializes an array with fixed size memory.
+ *
+ * This is useful, for example, when you want to work with memory on the stack
+ * and only want to move to the heap when the stack memory is not enough.
+ *
+ * With the @p num_initialized argument you can specify how many elements in the
+ * fixed size array are already correctly initialized, which determines the
+ * initial size of the array.
+ *
+ * The capacity is determined automatically by the compiler.
+ *
+ * @attention When you add elements to an array that was initialized with fixed
+ * size memory, you MUST check the capacity before adding the element and invoke
+ * cx_array_copy_to_new() when you intend to exceed the capacity.
+ *
+ * @attention When you pass a pointer to an array that does not have a fixed
+ * size, the behavior is unspecified.
+ *
+ * @param array the name of the array to initialize
+ * @param fixed_size_array (@c void*) the fixed size array
+ * @param num_initialized (@c size_t) the number of already initialized elements in the fixed size array
+ * @see cx_array_copy_to_new()
+ */
+#define cx_array_init_fixed(array, fixed_size_array, num_initialized) \
+        cx_array_init_fixed_((CxArray*)&(array), fixed_size_array, cx_nmemb(fixed_size_array), num_initialized)
 
+/**
+ * Changes the capacity of an array.
+ *
+ * Internal function - do not use.
+ *
+ * @param allocator the allocator
+ * @param array a pointer to the array structure
+ * @param elem_size the size of one element
+ * @param capacity the new capacity
+ * @retval zero allocation was successful
+ * @retval non-zero allocation failed
+ */
 cx_attr_nonnull
 CX_EXPORT int cx_array_reserve_(const CxAllocator *allocator, CxArray *array, size_t elem_size, size_t capacity);
 
-#define cx_array_reserve_a(allocator, array, capacity) cx_array_reserve_(allocator, (CxArray*)&(array), sizeof((array).data[0]), capacity)
+/**
+ * Changes the capacity of an array.
+ *
+ * If required, the size is reduced to fit into the new capacity.
+ *
+ * @param allocator (@c CxAllocator*) the allocator for the array
+ * @param array the name of the array
+ * @param capacity (@c size_t) the new maximum number of elements
+ * @retval zero allocation was successful
+ * @retval non-zero allocation failed
+ */
+#define cx_array_reserve_a(allocator, array, capacity) \
+        cx_array_reserve_(allocator, (CxArray*)&(array), sizeof((array).data[0]), capacity)
 
-#define cx_array_reserve(array, capacity) cx_array_reserve_a(cxDefaultAllocator, array, capacity)
+/**
+ * Changes the capacity of an array.
+ *
+ * If required, the size is reduced to fit into the new capacity.
+ *
+ * @param array the name of the array
+ * @param capacity (@c size_t) the new maximum number of elements
+ * @retval zero allocation was successful
+ * @retval non-zero allocation failed
+ */
+#define cx_array_reserve(array, capacity) \
+        cx_array_reserve_a(cxDefaultAllocator, array, capacity)
 
+/**
+ * Copies the array to a new memory region.
+ *
+ * Internal function - do not use.
+ *
+ * @param allocator the allocator for new new memory
+ * @param array a pointer to the array structure
+ * @param elem_size the size of one element
+ * @param capacity the new capacity
+ * @retval zero allocation was successful
+ * @retval non-zero allocation failed
+ */
 cx_attr_nonnull
-CX_EXPORT int cx_array_move_to_new_(const CxAllocator *allocator, CxArray *array, size_t elem_size, size_t capacity);
+CX_EXPORT int cx_array_copy_to_new_(const CxAllocator *allocator, CxArray *array, size_t elem_size, size_t capacity);
+
+/**
+ * Copies the array to a new memory region.
+ *
+ * This is useful when you have initialized the array with a fixed size memory
+ * using cx_array_init_fixed(), and now you want to increase the capacity.
+ *
+ * @attention When the original memory does not belong to stack memory, and
+ * you do not have another reference to this memory, it will leak.
+ *
+ * @param allocator (@c CxAllocator*) the allocator for the new memory
+ * @param array the name of the array
+ * @param capacity (@c size_t) the new maximum number of elements
+ * @retval zero allocation was successful
+ * @retval non-zero allocation failed
+ * @see cx_array_init_fixed()
+ */
+#define cx_array_copy_to_new_a(allocator, array, capacity) \
+        cx_array_copy_to_new_(allocator, (CxArray*)&(array), sizeof((array).data[0]), capacity)
 
-#define cx_array_move_to_new_a(allocator, array, capacity) cx_array_move_to_new_(allocator, (CxArray*)&(array), sizeof((array).data[0]), capacity)
+/**
+ * Copies the array to a new memory region.
+ *
+ * This is useful when you have initialized the array with a fixed size memory
+ * using cx_array_init_fixed(), and now you want to increase the capacity.
+ *
+ * @attention When the original memory does not belong to stack memory, and
+ * you do not have another reference to this memory, it will leak.
+ *
+ * @param array the name of the array
+ * @param capacity (@c size_t) the new maximum number of elements
+ * @retval zero allocation was successful
+ * @retval non-zero allocation failed
+ * @see cx_array_init_fixed()
+ */
+#define cx_array_copy_to_new(array, capacity) \
+        cx_array_copy_to_new_a(cxDefaultAllocator, array, capacity)
 
-#define cx_array_move_to_new(array, capacity) cx_array_move_to_new_a(cxDefaultAllocator, array, capacity)
-
+/**
+ * Inserts data into an array.
+ *
+ * Internal function - do not use.
+ *
+ * @param allocator the allocator to use for a possible reallocation
+ * @param array a pointer to the array structure
+ * @param elem_size the size of one element
+ * @param index the index where to insert the @p other data
+ * @param other a pointer to an array of data that shall be inserted
+ * @param n the number of elements that shall be inserted
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
 cx_attr_nonnull_arg(1, 2)
 CX_EXPORT int cx_array_insert_(const CxAllocator *allocator, CxArray *array,
         size_t elem_size, size_t index, const void *other, size_t n);
 
+/**
+ * Appends an element to an array.
+ *
+ * When the capacity is not enough to hold the new element, a re-allocation is attempted.
+ *
+ * @param allocator (@c CxAllocator*) the allocator to use for a possible reallocation
+ * @param array the name of the array where the element shall be added
+ * @param element (@c void*) a pointer to the element that shall be added
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
 #define cx_array_add_a(allocator, array, element) \
         cx_array_insert_(allocator, (CxArray*)&(array), sizeof((array).data[0]), (array).size, element, 1)
 
-#define cx_array_add(array, element) cx_array_add_a(cxDefaultAllocator, array, element)
+/**
+ * Appends an element to an array.
+ *
+ * When the capacity is not enough to hold the new element, a re-allocation is attempted.
+ *
+ * @param array the name of the array where the element shall be added
+ * @param element (@c void*) a pointer to the element that shall be added
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
+#define cx_array_add(array, element) \
+        cx_array_add_a(cxDefaultAllocator, array, element)
 
+/**
+ * Inserts an element into an array.
+ *
+ * When the capacity is not enough to hold the new element, a re-allocation is attempted.
+ *
+ * @param allocator (@c CxAllocator*) the allocator to use for a possible reallocation
+ * @param array the name of the array where the element shall be inserted
+ * @param index (@c size_t) the index where to insert the @p element
+ * @param element (@c void*) a pointer to the element that shall be inserted
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
 #define cx_array_insert_a(allocator, array, index, element) \
         cx_array_insert_(allocator, (CxArray*)&(array), sizeof((array).data[0]), index, element, 1)
 
-#define cx_array_insert(array, index, element) cx_array_insert_a(cxDefaultAllocator, array, index, element)
+/**
+ * Inserts an element into an array.
+ *
+ * When the capacity is not enough to hold the new element, a re-allocation is attempted.
+ *
+ * @param array the name of the array where the element shall be inserted
+ * @param index (@c size_t) the index where to insert the @p element
+ * @param element (@c void*) a pointer to the element that shall be inserted
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
+#define cx_array_insert(array, index, element) \
+        cx_array_insert_a(cxDefaultAllocator, array, index, element)
 
+/**
+ * Inserts data into an array.
+ *
+ * When the capacity is not enough to hold the new elements, a re-allocation is attempted.
+ *
+ * @param allocator (@c CxAllocator*) the allocator to use for a possible reallocation
+ * @param array the name of the array where the elements shall be inserted
+ * @param index (@c size_t) the index where to insert the @p other data
+ * @param other (@c void*) a pointer to an array of data that shall be inserted
+ * @param n (@c size_t) the number of elements that shall be inserted
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
 #define cx_array_insert_array_a(allocator, array, index, other, n) \
         cx_array_insert_(allocator, (CxArray*)&(array), sizeof((array).data[0]), index, other, n)
 
-#define cx_array_insert_array(array, index, other, n) cx_array_insert_array_a(cxDefaultAllocator, array, index, other, n)
+/**
+ * Inserts data into an array.
+ *
+ * When the capacity is not enough to hold the new elements, a re-allocation is attempted.
+ *
+ * @param array the name of the array where the elements shall be inserted
+ * @param index (@c size_t) the index where to insert the @p other data
+ * @param other (@c void*) a pointer to an array of data that shall be inserted
+ * @param n (@c size_t) the number of elements that shall be inserted
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
+#define cx_array_insert_array(array, index, other, n) \
+        cx_array_insert_array_a(cxDefaultAllocator, array, index, other, n)
 
+/**
+ * Appends data to an array.
+ *
+ * When the capacity is not enough to hold the new elements, a re-allocation is attempted.
+ *
+ * @param allocator (@c CxAllocator*) the allocator to use for a possible reallocation
+ * @param array the name of the array where the elements shall be added
+ * @param other (@c void*) a pointer to an array of data that shall be added
+ * @param n (@c size_t) the number of elements that shall be added
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
 #define cx_array_add_array_a(allocator, array, other, n) \
         cx_array_insert_(allocator, (CxArray*)&(array), sizeof((array).data[0]), (array).size, other, n)
 
-#define cx_array_add_array(array, other, n) cx_array_add_array_a(cxDefaultAllocator, array, other, n)
+/**
+ * Appends data to an array.
+ *
+ * When the capacity is not enough to hold the new elements, a re-allocation is attempted.
+ *
+ * @param array the name of the array where the elements shall be added
+ * @param other (@c void*) a pointer to an array of data that shall be added
+ * @param n (@c size_t) the number of elements that shall be added
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
+#define cx_array_add_array(array, other, n) \
+        cx_array_add_array_a(cxDefaultAllocator, array, other, n)
 
+/**
+ * Inserts sorted data into a sorted array.
+ *
+ * Internal function - do not use.
+ *
+ * @param allocator the allocator to use for a possible reallocation
+ * @param array a pointer to the array structure
+ * @param elem_size the size of one element
+ * @param cmp_func
+ * @param sorted_data a pointer to an array of data that shall be inserted
+ * @param n the number of elements that shall be inserted
+ * @param allow_duplicates @c false if duplicates shall be skipped during insertion
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
 cx_attr_nonnull
 CX_EXPORT int cx_array_insert_sorted_(const CxAllocator *allocator, CxArray *array,
         size_t elem_size, cx_compare_func cmp_func, const void *sorted_data, size_t n,
         bool allow_duplicates);
 
+/**
+ * Inserts an element into a sorted array.
+ *
+ * When the capacity is not enough to hold the new element, a re-allocation is attempted.
+ *
+ * @attention if the array is not sorted according to the specified @p cmp_func, the behavior is undefined.
+ *
+ * @param allocator (@c CxAllocator*) the allocator to use for a possible reallocation
+ * @param array the name of the array where the elements shall be inserted
+ * @param cmp_func (@c cx_compare_func) the compare function that establishes the order
+ * @param element (@c void*) a pointer to element that shall be inserted
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
 #define cx_array_insert_sorted_a(allocator, array, cmp_func, element) \
         cx_array_insert_sorted_(allocator, (CxArray*)&(array), sizeof((array).data[0]), cmp_func, element, 1, true)
 
-#define cx_array_insert_sorted(array, cmp_func, element) cx_array_insert_sorted_a(cxDefaultAllocator, array, cmp_func, element)
+/**
+ * Inserts an element into a sorted array.
+ *
+ * When the capacity is not enough to hold the new element, a re-allocation is attempted.
+ *
+ * @attention if the array is not sorted according to the specified @p cmp_func, the behavior is undefined.
+ *
+ * @param array the name of the array where the elements shall be inserted
+ * @param cmp_func (@c cx_compare_func) the compare function that establishes the order
+ * @param element (@c void*) a pointer to element that shall be inserted
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
+#define cx_array_insert_sorted(array, cmp_func, element) \
+        cx_array_insert_sorted_a(cxDefaultAllocator, array, cmp_func, element)
 
+/**
+ * Inserts sorted data into a sorted array.
+ *
+ * When the capacity is not enough to hold the new elements, a re-allocation is attempted.
+ *
+ * @attention if either array is not sorted according to the specified @p cmp_func, the behavior is undefined.
+ *
+ * @param allocator (@c CxAllocator*) the allocator to use for a possible reallocation
+ * @param array the name of the array where the elements shall be inserted
+ * @param cmp_func (@c cx_compare_func) the compare function that establishes the order
+ * @param sorted_data (@c void*) a pointer to an array of sorted data that shall be inserted
+ * @param n (@c size_t) the number of elements that shall be inserted
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
 #define cx_array_insert_sorted_array_a(allocator, array, cmp_func, sorted_data, n) \
         cx_array_insert_sorted_(allocator, (CxArray*)&(array), sizeof((array).data[0]), cmp_func, sorted_data, n, true)
 
-#define cx_array_insert_sorted_array(array, cmp_func, sorted_data, n) cx_array_insert_sorted_array_a(cxDefaultAllocator, array, cmp_func, sorted_data, n)
+/**
+ * Inserts sorted data into a sorted array.
+ *
+ * When the capacity is not enough to hold the new elements, a re-allocation is attempted.
+ *
+ * @attention if either array is not sorted according to the specified @p cmp_func, the behavior is undefined.
+ *
+ * @param array the name of the array where the elements shall be inserted
+ * @param cmp_func (@c cx_compare_func) the compare function that establishes the order
+ * @param sorted_data (@c void*) a pointer to an array of sorted data that shall be inserted
+ * @param n (@c size_t) the number of elements that shall be inserted
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
+#define cx_array_insert_sorted_array(array, cmp_func, sorted_data, n) \
+        cx_array_insert_sorted_array_a(cxDefaultAllocator, array, cmp_func, sorted_data, n)
 
+/**
+ * Inserts an element into a sorted array if it is not already contained.
+ *
+ * When the capacity is not enough to hold the new element, a re-allocation is attempted.
+ *
+ * @attention if the array is not sorted according to the specified @p cmp_func, the behavior is undefined.
+ *
+ * @param allocator (@c CxAllocator*) the allocator to use for a possible reallocation
+ * @param array the name of the array where the elements shall be inserted
+ * @param cmp_func (@c cx_compare_func) the compare function that establishes the order
+ * @param element (@c void*) a pointer to element that shall be inserted
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
 #define cx_array_insert_unique_a(allocator, array, cmp_func, element) \
         cx_array_insert_sorted_(allocator, (CxArray*)&(array), sizeof((array).data[0]), cmp_func, element, 1, false)
 
-#define cx_array_insert_unique(array, cmp_func, element) cx_array_insert_unique_a(cxDefaultAllocator, array, cmp_func, element)
+/**
+ * Inserts an element into a sorted array if it is not already contained.
+ *
+ * When the capacity is not enough to hold the new element, a re-allocation is attempted.
+ *
+ * @attention if the array is not sorted according to the specified @p cmp_func, the behavior is undefined.
+ *
+ * @param array the name of the array where the elements shall be inserted
+ * @param cmp_func (@c cx_compare_func) the compare function that establishes the order
+ * @param element (@c void*) a pointer to element that shall be inserted
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
+#define cx_array_insert_unique(array, cmp_func, element) \
+        cx_array_insert_unique_a(cxDefaultAllocator, array, cmp_func, element)
 
+/**
+ * Inserts sorted data into a sorted array, skipping duplicates.
+ *
+ * When the capacity is not enough to hold the new elements, a re-allocation is attempted.
+ *
+ * @attention if either array is not sorted according to the specified @p cmp_func, the behavior is undefined.
+ *
+ * @param allocator (@c CxAllocator*) the allocator to use for a possible reallocation
+ * @param array the name of the array where the elements shall be inserted
+ * @param cmp_func (@c cx_compare_func) the compare function that establishes the order
+ * @param sorted_data (@c void*) a pointer to an array of sorted data that shall be inserted
+ * @param n (@c size_t) the number of elements that shall be inserted
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
 #define cx_array_insert_unique_array_a(allocator, array, cmp_func, sorted_data, n) \
         cx_array_insert_sorted_(allocator, (CxArray*)&(array), sizeof((array).data[0]), cmp_func, sorted_data, n, false)
 
-#define cx_array_insert_unique_array(array, cmp_func, sorted_data, n) cx_array_insert_unique_array_a(cxDefaultAllocator, array, cmp_func, sorted_data, n)
+/**
+ * Inserts sorted data into a sorted array, skipping duplicates.
+ *
+ * When the capacity is not enough to hold the new elements, a re-allocation is attempted.
+ *
+ * @attention if either array is not sorted according to the specified @p cmp_func, the behavior is undefined.
+ *
+ * @param array the name of the array where the elements shall be inserted
+ * @param cmp_func (@c cx_compare_func) the compare function that establishes the order
+ * @param sorted_data (@c void*) a pointer to an array of sorted data that shall be inserted
+ * @param n (@c size_t) the number of elements that shall be inserted
+ * @retval zero success
+ * @retval non-zero a re-allocation was necessary but failed
+ */
+#define cx_array_insert_unique_array(array, cmp_func, sorted_data, n) \
+        cx_array_insert_unique_array_a(cxDefaultAllocator, array, cmp_func, sorted_data, n)
 
+/**
+ * Creates an iterator over the elements of an array.
+ *
+ * Internal function - do not use.
+ *
+ * @param array a pointer to the array structure
+ * @param elem_size the size of one element
+ * @return an iterator over the elements
+ */
 cx_attr_nodiscard cx_attr_nonnull
 CX_EXPORT CxIterator cx_array_iterator_(CxArray *array, size_t elem_size);
 
-#define cx_array_iterator(array) cx_array_iterator_((CxArray*)&(array), sizeof((array).data[0]))
+/**
+ * Creates an iterator over the elements of an array.
+ *
+ * The iterator will yield pointers to the elements.
+ *
+ * @param array the name of the array
+ * @return an iterator over the elements
+ * @see cx_array_iterator_ptr()
+ */
+#define cx_array_iterator(array) \
+        cx_array_iterator_((CxArray*)&(array), sizeof((array).data[0]))
 
+/**
+ * Creates an iterator over the elements of an array containing pointers.
+ *
+ * Internal function - do not use.
+ *
+ * @param array the name of the array
+ * @return an iterator over the elements
+ */
 cx_attr_nodiscard cx_attr_nonnull
 CX_EXPORT CxIterator cx_array_iterator_ptr_(CxArray *array);
 
-#define cx_array_iterator_ptr(array) cx_array_iterator_ptr_((CxArray*)&(array))
+/**
+ * Creates an iterator over the elements of an array containing pointers.
+ *
+ * The iterator will yield the elements themselves, which are supposed to
+ * be pointers.
+ *
+ * @param array the name of the array
+ * @return an iterator over the elements
+ * @see cx_array_iterator()
+ */
+#define cx_array_iterator_ptr(array) \
+        cx_array_iterator_ptr_((CxArray*)&(array))
 
+/**
+ * Deallocates an array.
+ *
+ * Internal function - do not use.
+ *
+ * @param allocator (@c CxAllocator*) the allocator which was used to allocate the array
+ * @param array a pointer to the array structure
+ */
 cx_attr_nonnull
 CX_EXPORT void cx_array_free_(const CxAllocator *allocator, CxArray *array);
 
+/**
+ * Deallocates an array.
+ *
+ * The structure is reset to zero and can be re-initialized with
+ * cx_array_inita().
+ *
+ * @param array the name of the array
+ */
 #define cx_array_free(array) cx_array_free_(cxDefaultAllocator, (CxArray*)&(array))
 
+/**
+ * Deallocates an array.
+ *
+ * The structure is reset to zero and can be re-initialized with
+ * cx_array_init_a().
+ *
+ * @param allocator (@c CxAllocator*) the allocator which was used to allocate the array
+ * @param array the name of the array
+ */
 #define cx_array_free_a(allocator, array) cx_array_free_(allocator, (CxArray*)&(array))
 
 
-
 /**
  * Searches the largest lower bound in a sorted array.
  *

--- a/src/json.c	Tue Dec 16 11:48:52 2025 +0100
+++ b/src/json.c	Tue Dec 16 12:07:01 2025 +0100
@@ -506,7 +506,7 @@
         if (json->vbuf.size >= json->vbuf.capacity) {
             int alloc_error;
             if (json->vbuf.data == json->vbuf_internal) {
-                alloc_error = cx_array_move_to_new(json->vbuf, json->vbuf.size+1);
+                alloc_error = cx_array_copy_to_new(json->vbuf, json->vbuf.size+1);
             } else {
                 alloc_error = cx_array_reserve(json->vbuf, json->vbuf.size+1);
             }
@@ -620,7 +620,7 @@
     if (required_states_depth >= json->states.capacity) {
         int alloc_error;
         if (json->states.data == json->states_internal) {
-            alloc_error = cx_array_move_to_new(json->states, required_states_depth);
+            alloc_error = cx_array_copy_to_new(json->states, required_states_depth);
         } else {
             alloc_error = cx_array_reserve(json->states, required_states_depth);
         }

--- a/tests/test_list.c	Tue Dec 16 11:48:52 2025 +0100
+++ b/tests/test_list.c	Tue Dec 16 12:07:01 2025 +0100
@@ -100,7 +100,7 @@
     cx_array_free(arr);
 }
 
-CX_TEST(test_array_move_to_new) {
+CX_TEST(test_array_copy_to_new) {
     CX_ARRAY(int, arr);
     int fixed[5] = {2, 4, 6};
     cx_array_init_fixed(arr, fixed, 3);
@@ -109,7 +109,7 @@
         CX_TEST_ASSERT(arr.size == 3);
         CX_TEST_ASSERT(arr.capacity == 5);
 
-        CX_TEST_ASSERT(0 == cx_array_move_to_new(arr, 8));
+        CX_TEST_ASSERT(0 == cx_array_copy_to_new(arr, 8));
 
         CX_TEST_ASSERT(arr.data != fixed);
         CX_TEST_ASSERT(arr.size == 3);
@@ -3279,7 +3279,7 @@
 
     cx_test_register(suite, test_array_add);
     cx_test_register(suite, test_array_reserve);
-    cx_test_register(suite, test_array_move_to_new);
+    cx_test_register(suite, test_array_copy_to_new);
     cx_test_register(suite, test_array_insert_sorted);
     cx_test_register(suite, test_array_insert_unique);
     cx_test_register(suite, test_array_binary_search);