docs/Writerside/topics/array_list.h.md

# Array List

Since low-level array lists are just plain arrays, there is no need for such many low-level functions as for linked
lists.
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
int cx_array_copy(
        void **target,
        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
);
```
The `target` argument is a pointer to the target array pointer.
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 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 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, 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()`.
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.

## Undocumented Symbols (TODO)
### cx_array_binary_search
### cx_array_binary_search_inf
### cx_array_binary_search_sup
### cx_array_copy
### cx_array_default_reallocator
### cx_array_default_reallocator_impl
### cx_array_insert_sorted
### cxArrayListCreate
### cx_array_reallocator
### cx_array_reserve
### cx_array_swap
### cx_array_swap_sbo_size