# HG changeset patch
# User Mike Becker <universe@uap-core.de>
# Date 1708257669 -3600
# Node ID 7970eac1c59876b0603a82aa9303480f36f1c988
# Parent  c4dae6fe6d5b7b0c115d34532933ab981a96452d
add convenience macros for cx_array_*

diff -r c4dae6fe6d5b -r 7970eac1c598 CHANGELOG
--- a/CHANGELOG	Sun Feb 18 12:24:04 2024 +0100
+++ b/CHANGELOG	Sun Feb 18 13:01:09 2024 +0100
@@ -3,6 +3,7 @@
  * adds tree.h
  * adds cx_array_default_reallocator
  * adds cx_array_add()
+ * adds cx_array_declare() and cx_array_simple_*() convenience macros
  * adds cx_linked_list_find_node()
  * adds cxListFindRemove()
  * adds cxBufferReset()
diff -r c4dae6fe6d5b -r 7970eac1c598 docs/src/features.md
--- a/docs/src/features.md	Sun Feb 18 12:24:04 2024 +0100
+++ b/docs/src/features.md	Sun Feb 18 13:01:09 2024 +0100
@@ -318,6 +318,8 @@
 
 If you just want to add one single element to an existing array, you can use the macro `cx_array_add()`.
 In that case, since the element is added to the end of the array, the `capacity` argument is mandatory.
+You can use `cx_array_declare()` to declare the necessary fields within a structure and then use the
+`cx_array_simple_*()` convenience macros to reduce code overhead.
 
 ## Map
 
diff -r c4dae6fe6d5b -r 7970eac1c598 src/cx/array_list.h
--- a/src/cx/array_list.h	Sun Feb 18 12:24:04 2024 +0100
+++ b/src/cx/array_list.h	Sun Feb 18 13:01:09 2024 +0100
@@ -50,14 +50,25 @@
 extern unsigned cx_array_swap_sbo_size;
 
 /**
+ * Declares variables for an array that can be used with the convenience macros.
+ *
+ * @see cx_array_simple_add()
+ * @see cx_array_simple_copy()
+ */
+#define cx_array_declare(type, name) \
+    type * name;                     \
+    size_t name##_size;              \
+    size_t name##_capacity;
+
+/**
  * Defines a reallocation mechanism for arrays.
  */
 struct cx_array_reallocator_s {
     /**
-     * Re-allocates space for the given array.
+     * Reallocates 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
+     * This allows reallocation of static memory by allocating heap memory
      * and copying the array contents. The information in the custom fields of
      * the referenced allocator can be used to track the state of the memory
      * or to transport other additional data.
@@ -120,7 +131,7 @@
  * attempt is made, unless the \p reallocator is set to \c NULL, in which case
  * this function ultimately returns a failure.
  *
- * @param target the target array
+ * @param target a pointer to 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
@@ -128,8 +139,8 @@
  * @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
+ * @param reallocator the array reallocator to use, or \c NULL
+ * if reallocation shall not happen
  * @return zero on success, non-zero error code on failure
  */
 enum cx_array_result cx_array_copy(
@@ -144,6 +155,18 @@
 ) __attribute__((__nonnull__(1, 2, 5)));
 
 /**
+ * Convenience macro that uses cx_array_copy() with a default layout and the default reallocator.
+ *
+ * @param array the name of the array (NOT a pointer to the array)
+ * @param index the index where the copied elements shall be placed
+ * @param src the source array
+ * @param count the number of elements to copy
+ */
+#define cx_array_simple_copy(array, index, src, count) \
+    cx_array_copy((void**)&(array), &(array##_size), &(array##_capacity), \
+    index, src, sizeof((array)[0]), count, cx_array_default_reallocator)
+
+/**
  * Adds an element to an array with the possibility of allocating more space.
  *
  * The element \p elem is added to the end of the \p target array which containing
@@ -154,19 +177,27 @@
  * \p reallocator is not \c NULL, an attempt increase the \p capacity is made
  * and the new capacity is written back.
  *
- * @param target the target array
+ * @param target a pointer to the target array
  * @param size a pointer to the size of the target array
  * @param capacity a pointer to the target array's capacity - must not be \c NULL
  * @param elem_size the size of one element
  * @param elem the element to add
- * @param reallocator the array re-allocator to use, or \c NULL
- * if re-allocation shall not happen
+ * @param reallocator the array reallocator to use, or \c NULL if reallocation shall not happen
  * @return zero on success, non-zero error code on failure
  */
 #define cx_array_add(target, size, capacity, elem_size, elem, reallocator) \
     cx_array_copy((void**)(target), size, capacity, *(size), elem, elem_size, 1, reallocator)
 
 /**
+ * Convenience macro that uses cx_array_add() with a default layout and the default reallocator.
+ *
+ * @param array the name of the array (NOT a pointer to the array)
+ * @param elem the element to add
+ */
+#define cx_array_simple_add(array, elem) \
+    cx_array_simple_copy(array, array##_size, elem, 1)
+
+/**
  * Swaps two array elements.
  *
  * @param arr the array
diff -r c4dae6fe6d5b -r 7970eac1c598 tests/test_list.c
--- a/tests/test_list.c	Sun Feb 18 12:24:04 2024 +0100
+++ b/tests/test_list.c	Sun Feb 18 13:01:09 2024 +0100
@@ -41,14 +41,15 @@
     int *stackarray = stackspace;
     size_t stackarray_size = 3;
     size_t stackarray_capacity = 5;
-    int *heaparray = calloc(5, sizeof(int));
+    cx_array_declare(int, heaparray);
+    heaparray = calloc(5, sizeof(int));
     heaparray[0] = 2;
     heaparray[1] = 3;
     heaparray[2] = 5;
     heaparray[3] = 7;
     heaparray[4] = 11;
-    size_t heaparray_size = 3;
-    size_t heaparray_capacity = 5;
+    heaparray_size = 3;
+    heaparray_capacity = 5;
     int elem = 8, elem2 = 47;
     enum cx_array_result result;
     CX_TEST_DO {
@@ -73,7 +74,7 @@
         CX_TEST_ASSERT(stackarray_size == 5);
         CX_TEST_ASSERT(stackarray_capacity == 5);
 
-        result = cx_array_add(&heaparray, &heaparray_size, &heaparray_capacity, sizeof(int), &elem, cx_array_default_reallocator);
+        result = cx_array_simple_add(heaparray, &elem);
         CX_TEST_ASSERT(result == CX_ARRAY_SUCCESS);
         CX_TEST_ASSERT(heaparray[0] == 2);
         CX_TEST_ASSERT(heaparray[1] == 3);
@@ -84,7 +85,7 @@
         CX_TEST_ASSERT(heaparray_capacity == 5);
 
         heaparray_size = 5;
-        result = cx_array_add(&heaparray, &heaparray_size, &heaparray_capacity, sizeof(int), &elem2, cx_array_default_reallocator);
+        result = cx_array_simple_add(heaparray, &elem2);
         CX_TEST_ASSERT(result == CX_ARRAY_SUCCESS);
         CX_TEST_ASSERT(heaparray[0] == 2);
         CX_TEST_ASSERT(heaparray[1] == 3);