--- a/docs/src/features.md Thu Nov 28 20:59:11 2024 +0100
+++ b/docs/src/features.md Mon Dec 02 20:58:17 2024 +0100
@@ -273,45 +273,40 @@
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_result cx_array_copy(
+int cx_array_copy(
void **target,
- size_t *size,
- size_t *capacity, // optional
+ void *size,
+ void *capacity,
+ unsigned width,
size_t index,
const void *src,
size_t elem_size,
size_t elem_count,
- struct cx_array_reallocator_s *reallocator // optional
+ struct cx_array_reallocator_s *reallocator
);
```
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
+The reason for this additional indirection is that 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.
-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_REALLOC_NOT_SUPPORTED` and do nothing.
+The next two arguments are pointers to the `size` and `capacity` of the target array for which the width
+(in bits) is specified in the `width` argument.
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_SUCCESS`.
-
-The third, but extremely rare, return code is `CX_ARRAY_REALLOC_FAILED` and speaks for itself.
+Finally, the size, capacity, and the pointer to the array are all updated and the function returns zero.
A few things to note:
* `*target` and `src` can point to the same memory region, effectively copying elements within the array with `memmove`
* `*target` does not need to point to the start of the array, but `size` and `capacity` always start counting from the
- position, `*target` points to - in this scenario, specifying a `reallocator` is forbidden for obvious reasons
-* `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
+ position, `*target` points to - in this scenario, the need for reallocation must be avoided for obvious reasons
+* `index` does not need to be within size of the current array
+* `index` does not even need to be within the capacity of the array
+* `width` must be one of 8, 16, 32, 64 (only on 64-bit systems), or zero (in which case the native word width is used)
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.
+The convenience macros automatically determine the width of the size/capacity variables.
## Map
