comparison: docs/Writerside/topics/list.h.md
docs/Writerside/topics/list.h.md
- changeset 1433
- 81c301a59b7c
- parent 1429
- 6e0c3a8a914a
equal
deleted
inserted
replaced
| 1432:fb82e7a92258 | 1433:81c301a59b7c |
|---|---|
| 118 | 118 |
| 119 void *cxListEmplace(CxList *list); | 119 void *cxListEmplace(CxList *list); |
| 120 | 120 |
| 121 void *cxListEmplaceAt(CxList *list, size_t index); | 121 void *cxListEmplaceAt(CxList *list, size_t index); |
| 122 | 122 |
| 123 CxIterator cxListEmplaceArray(CxList *list, size_t n); | |
| 124 | |
| 125 CxIterator cxListEmplaceArrayAt(CxList *list, size_t index, size_t n); | |
| 126 | |
| 123 int cxListInsertSorted(CxList *list, const void *elem); | 127 int cxListInsertSorted(CxList *list, const void *elem); |
| 124 | 128 |
| 125 int cxListInsertUnique(CxList *list, const void *elem); | 129 int cxListInsertUnique(CxList *list, const void *elem); |
| 126 | 130 |
| 127 size_t cxListAddArray(CxList *list, const void *array, size_t n); | 131 size_t cxListAddArray(CxList *list, const void *array, size_t n); |
| 143 The function `cxListAdd()` appends the element `elem` to the list and returns zero on success or non-zero when allocating the memory for the element fails. | 147 The function `cxListAdd()` appends the element `elem` to the list and returns zero on success or non-zero when allocating the memory for the element fails. |
| 144 Similarly, `cxListInsert()` adds the element at the specified `index`. | 148 Similarly, `cxListInsert()` adds the element at the specified `index`. |
| 145 | 149 |
| 146 The functions `cxListEmplace()` and `cxListEmplaceAt()` behave like `cxListAdd()` and `cxListInsert()`, | 150 The functions `cxListEmplace()` and `cxListEmplaceAt()` behave like `cxListAdd()` and `cxListInsert()`, |
| 147 except that they only allocate the memory and return a pointer to it, leaving it to the callee to copy the element data into it. | 151 except that they only allocate the memory and return a pointer to it, leaving it to the callee to copy the element data into it. |
| 152 The same is true for `cxListEmplaceArray()` and `cxListEmplaceArrayAt()`, which allocate memory for `n` elements and return an iterator to the first element. | |
| 148 Be aware that when the list is storing pointers, the allocated memory will be for the pointer, not the actual element's data. | 153 Be aware that when the list is storing pointers, the allocated memory will be for the pointer, not the actual element's data. |
| 154 | |
| 155 > If `cxListEmplaceArray()` or `cxListEmplaceArrayAt()` is unable to allocate memory for `n` elements, | |
| 156 > the iterator will iterate only over the elements that have been successfully allocated. | |
| 157 > The `elem_count` attribute of the iterator will be set to the number of successfully allocated elements. | |
| 158 > And the `index` attribute will count from zero to `elem_count - 1`. | |
| 159 > {style="note"} | |
| 149 | 160 |
| 150 The function `cxListInsertSorted()` inserts the element at the correct position so that the list remains sorted according to the list's compare function. | 161 The function `cxListInsertSorted()` inserts the element at the correct position so that the list remains sorted according to the list's compare function. |
| 151 It is important that the list is already sorted before calling this function. | 162 It is important that the list is already sorted before calling this function. |
| 152 On the other hand, `cxListInsertUnique()` inserts the element only if it is not already in the list. | 163 On the other hand, `cxListInsertUnique()` inserts the element only if it is not already in the list. |
| 153 In this case it is strongly recommended that the list is already sorted but not required; the function will fall back to an inefficient algorithm when the list is not sorted. | 164 In this case it is strongly recommended that the list is already sorted but not required; the function will fall back to an inefficient algorithm when the list is not sorted. |
| 416 | 427 |
| 417 | Function | Description | | 428 | Function | Description | |
| 418 |------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 429 |------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
| 419 | `clear` | Invoke destructor functions on all elements and remove them from the list. | | 430 | `clear` | Invoke destructor functions on all elements and remove them from the list. | |
| 420 | `deallocate` | Invoke destructor functions on all elements and deallocate the entire list memory. | | 431 | `deallocate` | Invoke destructor functions on all elements and deallocate the entire list memory. | |
| 421 | `insert_element` | Insert a single element at the specified index. Return a pointer to the allocated element or `NULL` on failure. | | 432 | `insert_element` | Insert or allocate a single element at the specified index. Return a pointer to the allocated element or `NULL` on failure. | |
| 422 | `insert_array` | Insert an array of elements starting at the specified index. Return the number of elements inserted. | | 433 | `insert_array` | Insert or allocate an array of elements starting at the specified index. Return the number of successfully inserted or allocated elements. | |
| 423 | `insert_sorted` | Insert an array of sorted elements into a sorted list. Return the number of elements processed (equals the number of elements inserted in this case). | | 434 | `insert_sorted` | Insert an array of sorted elements into a sorted list. Return the number of elements processed (equals the number of elements inserted in this case). | |
| 424 | `insert_unique` | Insert an array of sorted unique elements into a sorted list. Return the number of elements processed (not the number of elements inserted, which might be lower). | | 435 | `insert_unique` | Insert an array of sorted unique elements into a sorted list. Return the number of elements processed (not the number of elements inserted, which might be lower). | |
| 425 | `insert_iter` | Insert a single element depending on the iterator position. The third argument to this function is zero when the element shall be inserted after the iterator position and non-zero if it shall be inserted before the iterator position. The implementation is also responsible for adjusting the iterator, respectively. | | 436 | `insert_iter` | Insert a single element depending on the iterator position. The third argument to this function is zero when the element shall be inserted after the iterator position and non-zero if it shall be inserted before the iterator position. The implementation is also responsible for adjusting the iterator, respectively. | |
| 426 | `remove` | Removes a multiple elements starting at the specified index. If a target buffer is specified, copy the elements to that buffer. Otherwise, invoke the destructor functions for the elements. Return the number of elements actually removed. | | 437 | `remove` | Removes a multiple elements starting at the specified index. If a target buffer is specified, copy the elements to that buffer. Otherwise, invoke the destructor functions for the elements. Return the number of elements actually removed. | |
| 427 | `swap` | Swap two elements by index. Return zero on success or non-zero when any index was out-of-bounds. | | 438 | `swap` | Swap two elements by index. Return zero on success or non-zero when any index was out-of-bounds. | |
