--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/Writerside/topics/array_list.h.md Tue Feb 11 19:55:32 2025 +0100
@@ -0,0 +1,59 @@
+# Array List
+
+<warning>
+Outdated - Rewrite!
+</warning>
+
+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
\ No newline at end of file
