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