comparison: docs/Writerside/topics/list.h.md
docs/Writerside/topics/list.h.md
- changeset 1419
- e46406fd1b3c
- parent 1351
- 4407229bd944
- child 1420
- c6f55a2b3495
equal
deleted
inserted
replaced
| 1418:5e1579713bcf | 1419:e46406fd1b3c |
|---|---|
| 120 | 120 |
| 121 void *cxListEmplaceAt(CxList *list, size_t index); | 121 void *cxListEmplaceAt(CxList *list, size_t index); |
| 122 | 122 |
| 123 int cxListInsertSorted(CxList *list, const void *elem); | 123 int cxListInsertSorted(CxList *list, const void *elem); |
| 124 | 124 |
| 125 int cxListInsertUnique(CxList *list, const void *elem); | |
| 126 | |
| 125 size_t cxListAddArray(CxList *list, const void *array, size_t n); | 127 size_t cxListAddArray(CxList *list, const void *array, size_t n); |
| 126 | 128 |
| 127 size_t cxListInsertArray(CxList *list, size_t index, | 129 size_t cxListInsertArray(CxList *list, size_t index, |
| 128 const void *array, size_t n); | 130 const void *array, size_t n); |
| 129 | 131 |
| 130 size_t cxListInsertSortedArray(CxList *list, | 132 size_t cxListInsertSortedArray(CxList *list, |
| 133 const void *array, size_t n); | |
| 134 | |
| 135 size_t cxListInsertUniqueArray(CxList *list, | |
| 131 const void *array, size_t n); | 136 const void *array, size_t n); |
| 132 | 137 |
| 133 int cxListInsertAfter(CxIterator *iter, const void *elem); | 138 int cxListInsertAfter(CxIterator *iter, const void *elem); |
| 134 | 139 |
| 135 int cxListInsertBefore(CxIterator *iter, const void *elem); | 140 int cxListInsertBefore(CxIterator *iter, const void *elem); |
| 141 The functions `cxListEmplace()` and `cxListEmplaceAt()` behave like `cxListAdd()` and `cxListInsert()`, | 146 The functions `cxListEmplace()` and `cxListEmplaceAt()` behave like `cxListAdd()` and `cxListInsert()`, |
| 142 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. | 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. |
| 143 Be aware that when the list is storing pointers, the allocated memory will be for the pointer, not the actual element's data. | 148 Be aware that when the list is storing pointers, the allocated memory will be for the pointer, not the actual element's data. |
| 144 | 149 |
| 145 The function `cxListInsertSorted()` inserts the element at the correct position so that the list remains sorted according to the list's compare function. | 150 The function `cxListInsertSorted()` inserts the element at the correct position so that the list remains sorted according to the list's compare function. |
| 151 On top of that, `cxListInsertUnique()` inserts the element only if it is not already in the list. | |
| 146 | 152 |
| 147 When you are currently iterating through a list, you can insert elements before or after the current position of the iterator | 153 When you are currently iterating through a list, you can insert elements before or after the current position of the iterator |
| 148 with `cxListInsertBefore()` or `cxListInsertAfter()`, respectively. | 154 with `cxListInsertBefore()` or `cxListInsertAfter()`, respectively. |
| 149 This _should_ be done with [mutating iterators](iterator.h.md#mutating-iterators) only, but is also defined for normal iterators. | 155 This _should_ be done with [mutating iterators](iterator.h.md#mutating-iterators) only, but is also defined for normal iterators. |
| 150 | 156 |
| 151 If the list is storing pointers (cf. `cxCollectionStoresPointers()`), the pointer `elem` is directly added to the list. | 157 If the list is storing pointers (cf. `cxCollectionStoresPointers()`), the pointer `elem` is directly added to the list. |
| 152 Otherwise, the contents at the location pointed to by `elem` are copied to the list's memory with the element size specified during creation of the list. | 158 Otherwise, the contents at the location pointed to by `elem` are copied to the list's memory with the element size specified during creation of the list. |
| 153 | 159 |
| 154 On the other hand, the `array` argument for `cxListAddArray()`, `cxListInsertArray()`, and `cxListInsertSortedArray()` | 160 On the other hand, the `array` argument for `cxListAddArray()`, `cxListInsertArray()`, `cxListInsertSortedArray()`, and `cxListInsertUniqueArray()` |
| 155 must always point to an array of elements to be added (i.e., either an array of pointers or an array of actual elements). | 161 must always point to an array of elements to be added (i.e., either an array of pointers or an array of actual elements). |
| 156 | 162 |
| 157 A special requirement for `cxListInsertSortedArray()` is, that the `array` must already be sorted. | 163 When calling `cxListInsertSortedArray()` or `cxListInsertUniqueArray()`, the `array` must already be sorted. |
| 164 | |
| 165 The return values of the array-inserting functions are the number of elements that have been successfully _processed_. | |
| 166 Usually this is equivalent to the number of inserted elements, except for `cxListInsertUniqueArray()`, | |
| 167 where the actual number of inserted elements may be less than the number of successfully processed elements. | |
| 158 | 168 |
| 159 > Implementations are required to optimize the insertion of a sorted array into a sorted list in linear time, | 169 > Implementations are required to optimize the insertion of a sorted array into a sorted list in linear time, |
| 160 > while inserting each element separately via `cxListInsertSorted()` may take quadratic time. | 170 > while inserting each element separately via `cxListInsertSorted()` may take quadratic time. |
| 161 | 171 |
| 162 > The functions `cxListInsertSorted()` and `cxListInsertSortedArray()` do neither check if the list is already sorted, nor do they actively sort the list. | 172 > The functions do not check if the list is already sorted, nor do they actively sort the list. |
| 173 > In debug builds, invoking the functions on unsorted lists may trigger an assertion. | |
| 163 > {style="note"} | 174 > {style="note"} |
| 164 | 175 |
| 165 ## Access and Find | 176 ## Access and Find |
| 166 | 177 |
| 167 <link-summary>Functions for searching and accessing elements.</link-summary> | 178 <link-summary>Functions for searching and accessing elements.</link-summary> |
