comparison: docs/src/features.md
docs/src/features.md
- changeset 819
- 5da2ead43077
- parent 746
- b4bd0155f03f
- child 831
- 7970eac1c598
equal
deleted
inserted
replaced
| 818:2be8fe3d5a2d | 819:5da2ead43077 |
|---|---|
| 279 Since low-level array lists are just plain arrays, there is no need for such many low-level functions as for linked | 279 Since low-level array lists are just plain arrays, there is no need for such many low-level functions as for linked |
| 280 lists. | 280 lists. |
| 281 However, there is one extremely powerful function that can be used for several complex tasks: `cx_array_copy`. | 281 However, there is one extremely powerful function that can be used for several complex tasks: `cx_array_copy`. |
| 282 The full signature is shown below: | 282 The full signature is shown below: |
| 283 ```c | 283 ```c |
| 284 enum cx_array_copy_result cx_array_copy( | 284 enum cx_array_result cx_array_copy( |
| 285 void **target, | 285 void **target, |
| 286 size_t *size, | 286 size_t *size, |
| 287 size_t *capacity, // optional | 287 size_t *capacity, // optional |
| 288 size_t index, | 288 size_t index, |
| 289 void const *src, | 289 void const *src, |
| 293 ); | 293 ); |
| 294 ``` | 294 ``` |
| 295 The `target` argument is a pointer to the target array pointer. | 295 The `target` argument is a pointer to the target array pointer. |
| 296 The reason for this additional indirection is that - given that you provide a `reallocator` - this function writes | 296 The reason for this additional indirection is that - given that you provide a `reallocator` - this function writes |
| 297 back the pointer to the possibly reallocated array. | 297 back the pointer to the possibly reallocated array. |
| 298 THe next two arguments are pointers to the `size` and `capacity` of the target array. | 298 The next two arguments are pointers to the `size` and `capacity` of the target array. |
| 299 Tracking the capacity is optional. | 299 Tracking the capacity is optional. |
| 300 If you do not specify a pointer for the capacity, automatic reallocation of the array is entirely disabled (i.e. it | 300 If you do not specify a pointer for the capacity, automatic reallocation of the array is entirely disabled (i.e. it |
| 301 does not make sense to specify a `reallocator` then). | 301 does not make sense to specify a `reallocator` then). |
| 302 In this case, the function cannot copy more than `size-index` elements and if you try, it will return | 302 In this case, the function cannot copy more than `size-index` elements and if you try, it will return |
| 303 `CX_ARRAY_COPY_REALLOC_NOT_SUPPORTED` and do nothing. | 303 `CX_ARRAY_REALLOC_NOT_SUPPORTED` and do nothing. |
| 304 | 304 |
| 305 On a successful invocation, the function copies `elem_count` number of elements, each of size `elem_size` from | 305 On a successful invocation, the function copies `elem_count` number of elements, each of size `elem_size` from |
| 306 `src` to `*target` and uses the `reallocator` to extend the array when necessary. | 306 `src` to `*target` and uses the `reallocator` to extend the array when necessary. |
| 307 Finally, the size, capacity, and the pointer to the array are all updated and the function returns | 307 Finally, the size, capacity, and the pointer to the array are all updated and the function returns |
| 308 `CX_ARRAY_COPY_SUCCESS`. | 308 `CX_ARRAY_SUCCESS`. |
| 309 | 309 |
| 310 The third, but extremely rare, return code is `CX_ARRAY_COPY_REALLOC_FAILED` and speaks for itself. | 310 The third, but extremely rare, return code is `CX_ARRAY_REALLOC_FAILED` and speaks for itself. |
| 311 | 311 |
| 312 A few things to note: | 312 A few things to note: |
| 313 * `*target` and `src` can point to the same memory region, effectively copying elements within the array with `memmove` | 313 * `*target` and `src` can point to the same memory region, effectively copying elements within the array with `memmove` |
| 314 * `*target` does not need to point to the start of the array, but `size` and `capacity` always start counting from the | 314 * `*target` does not need to point to the start of the array, but `size` and `capacity` always start counting from the |
| 315 position, `*target` points to - in this scenario, specifying a `reallocator` is forbidden for obvious reasons | 315 position, `*target` points to - in this scenario, specifying a `reallocator` is forbidden for obvious reasons |
| 316 * `index` does not need to be within size of the current array, if `capacity` is specified | 316 * `index` does not need to be within size of the current array, if `capacity` is specified |
| 317 * `index` does not even need to be within the capacity of the array, if `reallocator` is specified | 317 * `index` does not even need to be within the capacity of the array, if `reallocator` is specified |
| 318 | 318 |
| 319 If you just want to add one single element to an existing array, you can use the macro `cx_array_add()`. | |
| 320 In that case, since the element is added to the end of the array, the `capacity` argument is mandatory. | |
| 319 | 321 |
| 320 ## Map | 322 ## Map |
| 321 | 323 |
| 322 *Header file:* [map.h](api/map_8h.html) | 324 *Header file:* [map.h](api/map_8h.html) |
| 323 | 325 |
