Mercurial > hg > ucx / changeset

--- a/docs/src/features.md	Thu Jan 25 22:01:12 2024 +0100
+++ b/docs/src/features.md	Thu Jan 25 22:05:48 2024 +0100
@@ -281,7 +281,7 @@
 However, there is one extremely powerful function that can be used for several complex tasks: `cx_array_copy`.
 The full signature is shown below:
 ```c
-enum cx_array_copy_result cx_array_copy(
+enum cx_array_result cx_array_copy(
         void **target,
         size_t *size,
         size_t *capacity,  // optional
@@ -295,19 +295,19 @@
 The `target` argument is a pointer to the target array pointer.
 The reason for this additional indirection is that - given that you provide a `reallocator` - this function writes
 back the pointer to the possibly reallocated array.
-THe next two arguments are pointers to the `size` and `capacity` of the target array.
+The next two arguments are pointers to the `size` and `capacity` of the target array.
 Tracking the capacity is optional.
 If you do not specify a pointer for the capacity, automatic reallocation of the array is entirely disabled (i.e. it
 does not make sense to specify a `reallocator` then).
 In this case, the function cannot copy more than `size-index` elements and if you try, it will return
-`CX_ARRAY_COPY_REALLOC_NOT_SUPPORTED` and do nothing.
+`CX_ARRAY_REALLOC_NOT_SUPPORTED` and do nothing.
 
 On a successful invocation, the function copies `elem_count` number of elements, each of size `elem_size` from
 `src` to `*target` and uses the `reallocator` to extend the array when necessary.
 Finally, the size, capacity, and the pointer to the array are all updated and the function returns
-`CX_ARRAY_COPY_SUCCESS`.
+`CX_ARRAY_SUCCESS`.
 
-The third, but extremely rare, return code is `CX_ARRAY_COPY_REALLOC_FAILED` and speaks for itself.
+The third, but extremely rare, return code is `CX_ARRAY_REALLOC_FAILED` and speaks for itself.
 
 A few things to note:
 * `*target` and `src` can point to the same memory region, effectively copying elements within the array with `memmove`
@@ -316,6 +316,8 @@
 * `index` does not need to be within size of the current array, if `capacity` is specified
 * `index` does not even need to be within the capacity of the array, if `reallocator` is specified 
 
+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.
 
 ## Map
 

--- a/src/array_list.c	Thu Jan 25 22:01:12 2024 +0100
+++ b/src/array_list.c	Thu Jan 25 22:05:48 2024 +0100
@@ -50,7 +50,7 @@
 
 // LOW LEVEL ARRAY LIST FUNCTIONS
 
-enum cx_array_copy_result cx_array_copy(
+enum cx_array_result cx_array_copy(
         void **target,
         size_t *size,
         size_t *capacity,
@@ -77,7 +77,7 @@
     if (needrealloc) {
         // a reallocator and a capacity variable must be available
         if (reallocator == NULL || capacity == NULL) {
-            return CX_ARRAY_COPY_REALLOC_NOT_SUPPORTED;
+            return CX_ARRAY_REALLOC_NOT_SUPPORTED;
         }
 
         // check, if we need to repair the src pointer
@@ -95,7 +95,7 @@
                 *target, cap, elem_size, reallocator
         );
         if (newmem == NULL) {
-            return CX_ARRAY_COPY_REALLOC_FAILED;
+            return CX_ARRAY_REALLOC_FAILED;
         }
 
         // repair src pointer, if necessary
@@ -117,7 +117,7 @@
     *size = newsize;
 
     // return successfully
-    return CX_ARRAY_COPY_SUCCESS;
+    return CX_ARRAY_SUCCESS;
 }
 
 #ifndef CX_ARRAY_SWAP_SBO_SIZE
@@ -227,7 +227,7 @@
         size_t elems_to_move = list->size - index;
         size_t start_of_moved = index + n;
 
-        if (CX_ARRAY_COPY_SUCCESS != cx_array_copy(
+        if (CX_ARRAY_SUCCESS != cx_array_copy(
                 &arl->data,
                 &list->size,
                 &arl->capacity,
@@ -247,7 +247,7 @@
     // therefore, it is impossible to leave this function with an invalid array
 
     // place the new elements
-    if (CX_ARRAY_COPY_SUCCESS == cx_array_copy(
+    if (CX_ARRAY_SUCCESS == cx_array_copy(
             &arl->data,
             &list->size,
             &arl->capacity,

--- a/src/cx/array_list.h	Thu Jan 25 22:01:12 2024 +0100
+++ b/src/cx/array_list.h	Thu Jan 25 22:05:48 2024 +0100
@@ -99,12 +99,12 @@
 extern struct cx_array_reallocator_s *cx_array_default_reallocator;
 
 /**
- * Return codes for cx_array_copy().
+ * Return codes for array functions.
  */
-enum cx_array_copy_result {
-    CX_ARRAY_COPY_SUCCESS,
-    CX_ARRAY_COPY_REALLOC_NOT_SUPPORTED,
-    CX_ARRAY_COPY_REALLOC_FAILED,
+enum cx_array_result {
+    CX_ARRAY_SUCCESS,
+    CX_ARRAY_REALLOC_NOT_SUPPORTED,
+    CX_ARRAY_REALLOC_FAILED,
 };
 
 /**
@@ -132,7 +132,7 @@
  * if re-allocation shall not happen
  * @return zero on success, non-zero error code on failure
  */
-enum cx_array_copy_result cx_array_copy(
+enum cx_array_result cx_array_copy(
         void **target,
         size_t *size,
         size_t *capacity,

--- a/tests/test_list.c	Thu Jan 25 22:01:12 2024 +0100
+++ b/tests/test_list.c	Thu Jan 25 22:05:48 2024 +0100
@@ -50,10 +50,10 @@
     size_t heaparray_size = 3;
     size_t heaparray_capacity = 5;
     int elem = 8, elem2 = 47;
-    enum cx_array_copy_result result;
+    enum cx_array_result result;
     CX_TEST_DO {
         result = cx_array_add(&stackarray, &stackarray_size, &stackarray_capacity, sizeof(int), &elem, NULL);
-        CX_TEST_ASSERT(result == CX_ARRAY_COPY_SUCCESS);
+        CX_TEST_ASSERT(result == CX_ARRAY_SUCCESS);
         CX_TEST_ASSERT(stackarray[0] == 1);
         CX_TEST_ASSERT(stackarray[1] == 1);
         CX_TEST_ASSERT(stackarray[2] == 2);
@@ -64,7 +64,7 @@
 
         stackarray_size = 5;
         result = cx_array_add(&stackarray, &stackarray_size, &stackarray_capacity, sizeof(int), &elem2, NULL);
-        CX_TEST_ASSERT(result == CX_ARRAY_COPY_REALLOC_NOT_SUPPORTED);
+        CX_TEST_ASSERT(result == CX_ARRAY_REALLOC_NOT_SUPPORTED);
         CX_TEST_ASSERT(stackarray[0] == 1);
         CX_TEST_ASSERT(stackarray[1] == 1);
         CX_TEST_ASSERT(stackarray[2] == 2);
@@ -74,7 +74,7 @@
         CX_TEST_ASSERT(stackarray_capacity == 5);
 
         result = cx_array_add(&heaparray, &heaparray_size, &heaparray_capacity, sizeof(int), &elem, cx_array_default_reallocator);
-        CX_TEST_ASSERT(result == CX_ARRAY_COPY_SUCCESS);
+        CX_TEST_ASSERT(result == CX_ARRAY_SUCCESS);
         CX_TEST_ASSERT(heaparray[0] == 2);
         CX_TEST_ASSERT(heaparray[1] == 3);
         CX_TEST_ASSERT(heaparray[2] == 5);
@@ -85,7 +85,7 @@
 
         heaparray_size = 5;
         result = cx_array_add(&heaparray, &heaparray_size, &heaparray_capacity, sizeof(int), &elem2, cx_array_default_reallocator);
-        CX_TEST_ASSERT(result == CX_ARRAY_COPY_SUCCESS);
+        CX_TEST_ASSERT(result == CX_ARRAY_SUCCESS);
         CX_TEST_ASSERT(heaparray[0] == 2);
         CX_TEST_ASSERT(heaparray[1] == 3);
         CX_TEST_ASSERT(heaparray[2] == 5);