Mercurial > hg > ucx / file diff

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/Writerside/topics/array_list.h.md	Thu Jan 23 01:33:36 2025 +0100
@@ -0,0 +1,41 @@
+# array_list.h
+
+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.