Mercurial > hg > ucx / changeset

     1.1 --- a/docs/src/features.md	Thu Jan 25 22:01:12 2024 +0100
     1.2 +++ b/docs/src/features.md	Thu Jan 25 22:05:48 2024 +0100
     1.3 @@ -281,7 +281,7 @@
     1.4  However, there is one extremely powerful function that can be used for several complex tasks: `cx_array_copy`.
     1.5  The full signature is shown below:
     1.6  ```c
     1.7 -enum cx_array_copy_result cx_array_copy(
     1.8 +enum cx_array_result cx_array_copy(
     1.9          void **target,
    1.10          size_t *size,
    1.11          size_t *capacity,  // optional
    1.12 @@ -295,19 +295,19 @@
    1.13  The `target` argument is a pointer to the target array pointer.
    1.14  The reason for this additional indirection is that - given that you provide a `reallocator` - this function writes
    1.15  back the pointer to the possibly reallocated array.
    1.16 -THe next two arguments are pointers to the `size` and `capacity` of the target array.
    1.17 +The next two arguments are pointers to the `size` and `capacity` of the target array.
    1.18  Tracking the capacity is optional.
    1.19  If you do not specify a pointer for the capacity, automatic reallocation of the array is entirely disabled (i.e. it
    1.20  does not make sense to specify a `reallocator` then).
    1.21  In this case, the function cannot copy more than `size-index` elements and if you try, it will return
    1.22 -`CX_ARRAY_COPY_REALLOC_NOT_SUPPORTED` and do nothing.
    1.23 +`CX_ARRAY_REALLOC_NOT_SUPPORTED` and do nothing.
    1.24  
    1.25  On a successful invocation, the function copies `elem_count` number of elements, each of size `elem_size` from
    1.26  `src` to `*target` and uses the `reallocator` to extend the array when necessary.
    1.27  Finally, the size, capacity, and the pointer to the array are all updated and the function returns
    1.28 -`CX_ARRAY_COPY_SUCCESS`.
    1.29 +`CX_ARRAY_SUCCESS`.
    1.30  
    1.31 -The third, but extremely rare, return code is `CX_ARRAY_COPY_REALLOC_FAILED` and speaks for itself.
    1.32 +The third, but extremely rare, return code is `CX_ARRAY_REALLOC_FAILED` and speaks for itself.
    1.33  
    1.34  A few things to note:
    1.35  * `*target` and `src` can point to the same memory region, effectively copying elements within the array with `memmove`
    1.36 @@ -316,6 +316,8 @@
    1.37  * `index` does not need to be within size of the current array, if `capacity` is specified
    1.38  * `index` does not even need to be within the capacity of the array, if `reallocator` is specified 
    1.39  
    1.40 +If you just want to add one single element to an existing array, you can use the macro `cx_array_add()`.
    1.41 +In that case, since the element is added to the end of the array, the `capacity` argument is mandatory.
    1.42  
    1.43  ## Map
    1.44  

     2.1 --- a/src/array_list.c	Thu Jan 25 22:01:12 2024 +0100
     2.2 +++ b/src/array_list.c	Thu Jan 25 22:05:48 2024 +0100
     2.3 @@ -50,7 +50,7 @@
     2.4  
     2.5  // LOW LEVEL ARRAY LIST FUNCTIONS
     2.6  
     2.7 -enum cx_array_copy_result cx_array_copy(
     2.8 +enum cx_array_result cx_array_copy(
     2.9          void **target,
    2.10          size_t *size,
    2.11          size_t *capacity,
    2.12 @@ -77,7 +77,7 @@
    2.13      if (needrealloc) {
    2.14          // a reallocator and a capacity variable must be available
    2.15          if (reallocator == NULL || capacity == NULL) {
    2.16 -            return CX_ARRAY_COPY_REALLOC_NOT_SUPPORTED;
    2.17 +            return CX_ARRAY_REALLOC_NOT_SUPPORTED;
    2.18          }
    2.19  
    2.20          // check, if we need to repair the src pointer
    2.21 @@ -95,7 +95,7 @@
    2.22                  *target, cap, elem_size, reallocator
    2.23          );
    2.24          if (newmem == NULL) {
    2.25 -            return CX_ARRAY_COPY_REALLOC_FAILED;
    2.26 +            return CX_ARRAY_REALLOC_FAILED;
    2.27          }
    2.28  
    2.29          // repair src pointer, if necessary
    2.30 @@ -117,7 +117,7 @@
    2.31      *size = newsize;
    2.32  
    2.33      // return successfully
    2.34 -    return CX_ARRAY_COPY_SUCCESS;
    2.35 +    return CX_ARRAY_SUCCESS;
    2.36  }
    2.37  
    2.38  #ifndef CX_ARRAY_SWAP_SBO_SIZE
    2.39 @@ -227,7 +227,7 @@
    2.40          size_t elems_to_move = list->size - index;
    2.41          size_t start_of_moved = index + n;
    2.42  
    2.43 -        if (CX_ARRAY_COPY_SUCCESS != cx_array_copy(
    2.44 +        if (CX_ARRAY_SUCCESS != cx_array_copy(
    2.45                  &arl->data,
    2.46                  &list->size,
    2.47                  &arl->capacity,
    2.48 @@ -247,7 +247,7 @@
    2.49      // therefore, it is impossible to leave this function with an invalid array
    2.50  
    2.51      // place the new elements
    2.52 -    if (CX_ARRAY_COPY_SUCCESS == cx_array_copy(
    2.53 +    if (CX_ARRAY_SUCCESS == cx_array_copy(
    2.54              &arl->data,
    2.55              &list->size,
    2.56              &arl->capacity,

     3.1 --- a/src/cx/array_list.h	Thu Jan 25 22:01:12 2024 +0100
     3.2 +++ b/src/cx/array_list.h	Thu Jan 25 22:05:48 2024 +0100
     3.3 @@ -99,12 +99,12 @@
     3.4  extern struct cx_array_reallocator_s *cx_array_default_reallocator;
     3.5  
     3.6  /**
     3.7 - * Return codes for cx_array_copy().
     3.8 + * Return codes for array functions.
     3.9   */
    3.10 -enum cx_array_copy_result {
    3.11 -    CX_ARRAY_COPY_SUCCESS,
    3.12 -    CX_ARRAY_COPY_REALLOC_NOT_SUPPORTED,
    3.13 -    CX_ARRAY_COPY_REALLOC_FAILED,
    3.14 +enum cx_array_result {
    3.15 +    CX_ARRAY_SUCCESS,
    3.16 +    CX_ARRAY_REALLOC_NOT_SUPPORTED,
    3.17 +    CX_ARRAY_REALLOC_FAILED,
    3.18  };
    3.19  
    3.20  /**
    3.21 @@ -132,7 +132,7 @@
    3.22   * if re-allocation shall not happen
    3.23   * @return zero on success, non-zero error code on failure
    3.24   */
    3.25 -enum cx_array_copy_result cx_array_copy(
    3.26 +enum cx_array_result cx_array_copy(
    3.27          void **target,
    3.28          size_t *size,
    3.29          size_t *capacity,

     4.1 --- a/tests/test_list.c	Thu Jan 25 22:01:12 2024 +0100
     4.2 +++ b/tests/test_list.c	Thu Jan 25 22:05:48 2024 +0100
     4.3 @@ -50,10 +50,10 @@
     4.4      size_t heaparray_size = 3;
     4.5      size_t heaparray_capacity = 5;
     4.6      int elem = 8, elem2 = 47;
     4.7 -    enum cx_array_copy_result result;
     4.8 +    enum cx_array_result result;
     4.9      CX_TEST_DO {
    4.10          result = cx_array_add(&stackarray, &stackarray_size, &stackarray_capacity, sizeof(int), &elem, NULL);
    4.11 -        CX_TEST_ASSERT(result == CX_ARRAY_COPY_SUCCESS);
    4.12 +        CX_TEST_ASSERT(result == CX_ARRAY_SUCCESS);
    4.13          CX_TEST_ASSERT(stackarray[0] == 1);
    4.14          CX_TEST_ASSERT(stackarray[1] == 1);
    4.15          CX_TEST_ASSERT(stackarray[2] == 2);
    4.16 @@ -64,7 +64,7 @@
    4.17  
    4.18          stackarray_size = 5;
    4.19          result = cx_array_add(&stackarray, &stackarray_size, &stackarray_capacity, sizeof(int), &elem2, NULL);
    4.20 -        CX_TEST_ASSERT(result == CX_ARRAY_COPY_REALLOC_NOT_SUPPORTED);
    4.21 +        CX_TEST_ASSERT(result == CX_ARRAY_REALLOC_NOT_SUPPORTED);
    4.22          CX_TEST_ASSERT(stackarray[0] == 1);
    4.23          CX_TEST_ASSERT(stackarray[1] == 1);
    4.24          CX_TEST_ASSERT(stackarray[2] == 2);
    4.25 @@ -74,7 +74,7 @@
    4.26          CX_TEST_ASSERT(stackarray_capacity == 5);
    4.27  
    4.28          result = cx_array_add(&heaparray, &heaparray_size, &heaparray_capacity, sizeof(int), &elem, cx_array_default_reallocator);
    4.29 -        CX_TEST_ASSERT(result == CX_ARRAY_COPY_SUCCESS);
    4.30 +        CX_TEST_ASSERT(result == CX_ARRAY_SUCCESS);
    4.31          CX_TEST_ASSERT(heaparray[0] == 2);
    4.32          CX_TEST_ASSERT(heaparray[1] == 3);
    4.33          CX_TEST_ASSERT(heaparray[2] == 5);
    4.34 @@ -85,7 +85,7 @@
    4.35  
    4.36          heaparray_size = 5;
    4.37          result = cx_array_add(&heaparray, &heaparray_size, &heaparray_capacity, sizeof(int), &elem2, cx_array_default_reallocator);
    4.38 -        CX_TEST_ASSERT(result == CX_ARRAY_COPY_SUCCESS);
    4.39 +        CX_TEST_ASSERT(result == CX_ARRAY_SUCCESS);
    4.40          CX_TEST_ASSERT(heaparray[0] == 2);
    4.41          CX_TEST_ASSERT(heaparray[1] == 3);
    4.42          CX_TEST_ASSERT(heaparray[2] == 5);