# HG changeset patch # User Mike Becker # Date 1706216748 -3600 # Node ID 5da2ead43077e9daf9ace43a3bb82871f91159b1 # Parent 2be8fe3d5a2d439d0726285af5edc3ab638783ea rename cx_array_copy_result to just cx_array_result diff -r 2be8fe3d5a2d -r 5da2ead43077 docs/src/features.md --- 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 diff -r 2be8fe3d5a2d -r 5da2ead43077 src/array_list.c --- 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, diff -r 2be8fe3d5a2d -r 5da2ead43077 src/cx/array_list.h --- 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, diff -r 2be8fe3d5a2d -r 5da2ead43077 tests/test_list.c --- 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);