comparison: docs/Writerside/topics/list.h.md
docs/Writerside/topics/list.h.md
- changeset 1489
- 185dc2a4b45c
- parent 1482
- 6769cb72521b
equal
deleted
inserted
replaced
| 1488:946895d19dde | 1489:185dc2a4b45c |
|---|---|
| 399 const CxList *src, const CxList *other); | 399 const CxList *src, const CxList *other); |
| 400 ``` | 400 ``` |
| 401 | 401 |
| 402 With `cxListClone()` you can create deep copies of the elements in a list and insert them into another list. | 402 With `cxListClone()` you can create deep copies of the elements in a list and insert them into another list. |
| 403 The destination list does not need to be empty, in which case the elements will be appended. | 403 The destination list does not need to be empty, in which case the elements will be appended. |
| 404 Depending on the concrete list implementation, `cxListClone()` tries to allocate enough memory up-front, before trying | 404 Depending on the concrete list implementation, `cxListClone()` tries to allocate enough memory up-front before trying |
| 405 to insert anything. | 405 to insert anything. |
| 406 | 406 |
| 407 The function `cxListDifference()` clones elements from the `minuend` that are _not_ contained in the `subtrahend`, | 407 The function `cxListDifference()` clones elements from the `minuend` that are _not_ contained in the `subtrahend`, |
| 408 while `cxListIntersection()` only clones elements from the `src` that are _also_ contained in the `other` list. | 408 while `cxListIntersection()` only clones elements from the `src` that are _also_ contained in the `other` list. |
| 409 And `cxListUnion()` clones elements from `src` first, and from `other` only when they are _not_ contained in `src`. | 409 And `cxListUnion()` clones elements from `src` first, and from `other` only when they are _not_ contained in `src`. |
| 412 In that case they will take linear time instead of quadratic time for the operation. | 412 In that case they will take linear time instead of quadratic time for the operation. |
| 413 Also, `cxListUnion()` makes sure that the elements from `src` and `other` are cloned interleaving, | 413 Also, `cxListUnion()` makes sure that the elements from `src` and `other` are cloned interleaving, |
| 414 so that the result of the union is still sorted. | 414 so that the result of the union is still sorted. |
| 415 | 415 |
| 416 However, when the `dst` list already contains elements, all functions will only append the result of the operation to that list. | 416 However, when the `dst` list already contains elements, all functions will only append the result of the operation to that list. |
| 417 That means, the `dst` list is only guaranteed to be sorted, when it was empty and the input lists are all sorted. | 417 That means the `dst` list is only guaranteed to be sorted when it was empty and the input lists are all sorted. |
| 418 | 418 |
| 419 Refer to the documentation of the [clone-function callback](allocator.h.md#clone-function) to learn how to implement it. | 419 Refer to the documentation of the [clone-function callback](allocator.h.md#clone-function) to learn how to implement it. |
| 420 | 420 |
| 421 The _simple_ versions of the above functions use an internal shallow clone function | 421 The _simple_ versions of the above functions use an internal shallow clone function |
| 422 which uses `memcpy()` to copy the elements. | 422 which uses `memcpy()` to copy the elements. |
| 442 int cxListShrink(CxList *list); | 442 int cxListShrink(CxList *list); |
| 443 ``` | 443 ``` |
| 444 | 444 |
| 445 If a list implementation allows overallocation, the function `cxListReserve()` can be used to reserve memory for a total of `count` elements. | 445 If a list implementation allows overallocation, the function `cxListReserve()` can be used to reserve memory for a total of `count` elements. |
| 446 On the other hand, you can use `cxListShrink()` to dispose of any overallocated memory and reduce the capacity to the actual number of currently stored elements. | 446 On the other hand, you can use `cxListShrink()` to dispose of any overallocated memory and reduce the capacity to the actual number of currently stored elements. |
| 447 Calling `cxListReserve()` with a `count` argument that is less than the current size of the list has no effect and the function returns zero. | 447 Calling `cxListReserve()` with a `count` argument that is less than the current size of the list has no effect, and the function returns zero. |
| 448 | 448 |
| 449 If allocating memory fails, `cxListReserve()` returns a non-zero value. | 449 If allocating memory fails, `cxListReserve()` returns a non-zero value. |
| 450 Since shrinking should never fail, `cxListShrink()` will usually always return zero, | 450 Since shrinking should never fail, `cxListShrink()` will usually always return zero, |
| 451 but depending on the list (or allocator) implementation, the possibility for a non-zero return value is there. | 451 but depending on the list (or allocator) implementation, the possibility for a non-zero return value is there. |
| 452 | 452 |
