comparison: docs/Writerside/topics/array_list.h.md
docs/Writerside/topics/array_list.h.md
- changeset 1188
- b0300de92b72
- parent 1146
- 151c057faf7c
- child 1190
- a7b913d5d589
equal
deleted
inserted
replaced
| 1187:0f70bb04f7ba | 1188:b0300de92b72 |
|---|---|
| 1 # Array List | |
| 2 | |
| 3 <warning> | |
| 4 Outdated - Rewrite! | |
| 5 </warning> | |
| 6 | |
| 7 Since low-level array lists are just plain arrays, there is no need for such many low-level functions as for linked | |
| 8 lists. | |
| 9 However, there is one extremely powerful function that can be used for several complex tasks: `cx_array_copy`. | |
| 10 The full signature is shown below: | |
| 11 ```c | |
| 12 int cx_array_copy( | |
| 13 void **target, | |
| 14 void *size, | |
| 15 void *capacity, | |
| 16 unsigned width, | |
| 17 size_t index, | |
| 18 const void *src, | |
| 19 size_t elem_size, | |
| 20 size_t elem_count, | |
| 21 struct cx_array_reallocator_s *reallocator | |
| 22 ); | |
| 23 ``` | |
| 24 The `target` argument is a pointer to the target array pointer. | |
| 25 The reason for this additional indirection is that this function writes | |
| 26 back the pointer to the possibly reallocated array. | |
| 27 The next two arguments are pointers to the `size` and `capacity` of the target array for which the width | |
| 28 (in bits) is specified in the `width` argument. | |
| 29 | |
| 30 On a successful invocation, the function copies `elem_count` number of elements, each of size `elem_size` from | |
| 31 `src` to `*target` and uses the `reallocator` to extend the array when necessary. | |
| 32 Finally, the size, capacity, and the pointer to the array are all updated and the function returns zero. | |
| 33 | |
| 34 A few things to note: | |
| 35 * `*target` and `src` can point to the same memory region, effectively copying elements within the array with `memmove` | |
| 36 * `*target` does not need to point to the start of the array, but `size` and `capacity` always start counting from the | |
| 37 position, `*target` points to - in this scenario, the need for reallocation must be avoided for obvious reasons | |
| 38 * `index` does not need to be within size of the current array | |
| 39 * `index` does not even need to be within the capacity of the array | |
| 40 * `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) | |
| 41 | |
| 42 If you just want to add one single element to an existing array, you can use the macro `cx_array_add()`. | |
| 43 You can use `CX_ARRAY_DECLARE()` to declare the necessary fields within a structure and then use the | |
| 44 `cx_array_simple_*()` convenience macros to reduce code overhead. | |
| 45 The convenience macros automatically determine the width of the size/capacity variables. | |
| 46 | |
| 47 ## Undocumented Symbols (TODO) | |
| 48 ### cx_array_binary_search | |
| 49 ### cx_array_binary_search_inf | |
| 50 ### cx_array_binary_search_sup | |
| 51 ### cx_array_copy | |
| 52 ### cx_array_default_reallocator | |
| 53 ### cx_array_default_reallocator_impl | |
| 54 ### cx_array_insert_sorted | |
| 55 ### cxArrayListCreate | |
| 56 ### cx_array_reallocator | |
| 57 ### cx_array_reserve | |
| 58 ### cx_array_swap | |
| 59 ### cx_array_swap_sbo_size |
