comparison: docs/Writerside/topics/array_list.h.md
docs/Writerside/topics/array_list.h.md
- branch
- docs/3.1
- changeset 1141
- a06a2d27c043
- child 1142
- 9437530176bc
equal
deleted
inserted
replaced
| 1140:88a9ee79c102 | 1141:a06a2d27c043 |
|---|---|
| 1 # array_list.h | |
| 2 | |
| 3 Since low-level array lists are just plain arrays, there is no need for such many low-level functions as for linked | |
| 4 lists. | |
| 5 However, there is one extremely powerful function that can be used for several complex tasks: `cx_array_copy`. | |
| 6 The full signature is shown below: | |
| 7 ```c | |
| 8 int cx_array_copy( | |
| 9 void **target, | |
| 10 void *size, | |
| 11 void *capacity, | |
| 12 unsigned width, | |
| 13 size_t index, | |
| 14 const void *src, | |
| 15 size_t elem_size, | |
| 16 size_t elem_count, | |
| 17 struct cx_array_reallocator_s *reallocator | |
| 18 ); | |
| 19 ``` | |
| 20 The `target` argument is a pointer to the target array pointer. | |
| 21 The reason for this additional indirection is that this function writes | |
| 22 back the pointer to the possibly reallocated array. | |
| 23 The next two arguments are pointers to the `size` and `capacity` of the target array for which the width | |
| 24 (in bits) is specified in the `width` argument. | |
| 25 | |
| 26 On a successful invocation, the function copies `elem_count` number of elements, each of size `elem_size` from | |
| 27 `src` to `*target` and uses the `reallocator` to extend the array when necessary. | |
| 28 Finally, the size, capacity, and the pointer to the array are all updated and the function returns zero. | |
| 29 | |
| 30 A few things to note: | |
| 31 * `*target` and `src` can point to the same memory region, effectively copying elements within the array with `memmove` | |
| 32 * `*target` does not need to point to the start of the array, but `size` and `capacity` always start counting from the | |
| 33 position, `*target` points to - in this scenario, the need for reallocation must be avoided for obvious reasons | |
| 34 * `index` does not need to be within size of the current array | |
| 35 * `index` does not even need to be within the capacity of the array | |
| 36 * `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) | |
| 37 | |
| 38 If you just want to add one single element to an existing array, you can use the macro `cx_array_add()`. | |
| 39 You can use `CX_ARRAY_DECLARE()` to declare the necessary fields within a structure and then use the | |
| 40 `cx_array_simple_*()` convenience macros to reduce code overhead. | |
| 41 The convenience macros automatically determine the width of the size/capacity variables. |
