--- a/docs/Writerside/topics/array_list.h.md Wed Mar 12 16:08:35 2025 +0100
+++ b/docs/Writerside/topics/array_list.h.md Wed Mar 12 18:32:57 2025 +0100
@@ -1,26 +1,120 @@
# Array List
+Next to an array list implementation of the list interface,
+UCX offers several functions to work with plain C arrays equipped with a size and a capacity.
+
+The high level [list interface](list.h.md) is documented on a separate page and explains how lists are used
+that are created by one of the following functions.
+
+```C
+#include <cx/array_list.h>
+
+CxList *cxArrayListCreate(const CxAllocator *allocator,
+ cx_compare_func comparator, size_t elem_size,
+ size_t initial_capacity);
+
+CxList *cxArrayListCreateSimple(size_t elem_size,
+ size_t initial_capacity);
+```
+
+The remaining documentation on this page concentrates on dealing with plain C arrays.
+
+## Declare Array with Size and Capacity
+
+```C
+#include <cx/array_list.h>
+
+#define CX_ARRAY_DECLARE_SIZED(type, name, size_type)
+
+#define CX_ARRAY_DECLARE(type, name)
+
+#define cx_array_initialize(ARRAY, capacity)
+
+#define cx_array_initialize_a(allocator, ARRAY, capacity)
+```
+
<warning>
-Outdated Section - will be updated soon!
+TODO: document
</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
+## Array Reallocator
+
+```C
+#include <cx/array_list.h>
+
+typedef struct {
+ void *(*realloc)(void *array, size_t capacity, size_t elem_size,
+ CxArrayReallocator *alloc);
+ void *ptr1;
+ void *ptr2;
+ size_t int1;
+ size_t int2;
+} CxArrayReallocator;
+
+CxArrayReallocator cx_array_reallocator(
+ const struct cx_allocator_s *allocator,
+ const void *stackmem
);
```
+
+<warning>
+TODO: document
+</warning>
+
+## Add Elements
+
+```C
+#include <cx/array_list.h>
+
+cx_array_add(target, size, capacity, elem_size, elem, reallocator)
+
+#define cx_array_simple_add(ARRAY, elem)
+
+#define cx_array_simple_add_a(reallocator, ARRAY, elem)
+```
+
+<warning>
+TODO: document
+</warning>
+
+## Reserve
+
+```C
+#include <cx/array_list.h>
+
+int cx_array_reserve(
+ void **array, void *size, void *capacity, unsigned width,
+ size_t elem_size, size_t elem_count,
+ CxArrayReallocator *reallocator);
+
+#define cx_array_simple_reserve(ARRAY, count)
+#define cx_array_simple_reserve_a(reallocator, ARRAY, count)
+```
+
+<warning>
+TODO: document
+</warning>
+
+## Copy
+
+```C
+#include <cx/array_list.h>
+
+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,
+ CxArrayReallocator *reallocator);
+
+#define cx_array_simple_copy(ARRAY, index, src, count)
+
+#define cx_array_simple_copy_a(reallocator, ARRAY, index, src, count)
+```
+
+<warning>
+TODO: outdated - rewrite
+</warning>
+
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.
@@ -39,26 +133,96 @@
* `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.
+## Insertion Sort
+
+```C
+int cx_array_insert_sorted(
+ void **target, size_t *size, size_t *capacity,
+ cx_compare_func cmp_func,
+ const void *src, size_t elem_size, size_t elem_count,
+ CxArrayReallocator *reallocator);
+
+#define cx_array_simple_insert_sorted(ARRAY,
+ src, elem_count, cmp_func)
+
+#define cx_array_simple_insert_sorted_a(reallocator, ARRAY,
+ src, elem_count, cmp_func)
+
+int cx_array_add_sorted(
+ void **target, size_t *size, size_t *capacity,
+ size_t elem_size, const void *elem,
+ cx_compare_func cmp_func,
+ CxArrayReallocator *reallocator);
+
+#define cx_array_simple_add_sorted(ARRAY,
+ elem, cmp_func)
+
+#define cx_array_simple_add_sorted_a(reallocator, ARRAY,
+ elem, cmp_func)
+```
+
+<warning>
+TODO: document
+</warning>
+
+## Binary Search
+
+```C
+#include <cx/array_list.h>
+
+size_t cx_array_binary_search(
+ const void *arr, size_t size, size_t elem_size,
+ const void *elem, cx_compare_func cmp_func);
+
+size_t cx_array_binary_search_inf(
+ const void *arr, size_t size, size_t elem_size,
+ const void *elem, cx_compare_func cmp_func);
-<!--
-## 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
--->
+size_t cx_array_binary_search_sup(
+ const void *arr, size_t size, size_t elem_size,
+ const void *elem, cx_compare_func cmp_func);
+```
+
+<warning>
+TODO: document
+</warning>
+
+## Iterators
+
+```C
+#include <cx/iterator.h>
+
+CxIterator cxIterator(const void *array,
+ size_t elem_size, size_t elem_count);
+
+CxIterator cxMutIterator(void *array,
+ size_t elem_size, size_t elem_count, bool remove_keeps_order);
+
+CxIterator cxIteratorPtr(const void *array, size_t elem_count);
+
+CxIterator cxMutIteratorPtr(void *array, size_t elem_count,
+ bool remove_keeps_order);
+```
+
+Iterators over plain C arrays are defined in [iterator.h](iterator.h.md#creating-an-iterator).
+
+## Other
+
+```C
+#include <cx/array_list.h>
+
+void cx_array_swap(
+ void *arr,
+ size_t elem_size,
+ size_t idx1,
+ size_t idx2
+);
+```
+
+<warning>
+TODO: document
+</warning>
+
<seealso>
<category ref="apidoc">
<a href="https://ucx.sourceforge.io/api/array__list_8h.html">array_list.h</a>