152 On the other hand, `cxListInsertUnique()` inserts the element only if it is not already in the list. |
152 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. |
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. |
154 |
154 |
155 When you are currently iterating through a list, you can insert elements before or after the current position of the iterator |
155 When you are currently iterating through a list, you can insert elements before or after the current position of the iterator |
156 with `cxListInsertBefore()` or `cxListInsertAfter()`, respectively. |
156 with `cxListInsertBefore()` or `cxListInsertAfter()`, respectively. |
157 This _should_ be done with [mutating iterators](iterator.h.md#mutating-iterators) only, but is also defined for normal iterators. |
|
158 |
157 |
159 If the list is storing pointers (cf. `cxCollectionStoresPointers()`), the pointer `elem` is directly added to the list. |
158 If the list is storing pointers (cf. `cxCollectionStoresPointers()`), the pointer `elem` is directly added to the list. |
160 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. |
159 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. |
161 |
160 |
162 On the other hand, the `array` argument for `cxListAddArray()`, `cxListInsertArray()`, `cxListInsertSortedArray()`, and `cxListInsertUniqueArray()` |
161 On the other hand, the `array` argument for `cxListAddArray()`, `cxListInsertArray()`, `cxListInsertSortedArray()`, and `cxListInsertUniqueArray()` |
282 CxIterator cxListBackwardsIterator(const CxList *list); |
281 CxIterator cxListBackwardsIterator(const CxList *list); |
283 |
282 |
284 CxIterator cxListIteratorAt(const CxList *list, size_t index); |
283 CxIterator cxListIteratorAt(const CxList *list, size_t index); |
285 |
284 |
286 CxIterator cxListBackwardsIteratorAt(const CxList *list, size_t index); |
285 CxIterator cxListBackwardsIteratorAt(const CxList *list, size_t index); |
287 |
|
288 CxIterator cxListMutIterator(CxList *list); |
|
289 |
|
290 CxIterator cxListMutBackwardsIterator(CxList *list); |
|
291 |
|
292 CxIterator cxListMutIteratorAt(CxList *list, size_t index); |
|
293 |
|
294 CxIterator cxListMutBackwardsIteratorAt(CxList *list, size_t index); |
|
295 ``` |
286 ``` |
296 |
287 |
297 The functions `cxListIterator()` and `cxListBackwardsIterator()` create iterators |
288 The functions `cxListIterator()` and `cxListBackwardsIterator()` create iterators |
298 that start and the first or the last element in the list and iterate through the entire list. |
289 that start and the first or the last element in the list and iterate through the entire list. |
299 |
290 |
300 The functions `cxListIteratorAt()` and `cxListBackwardsIteratorAt()` start with the element at the specified index |
291 The functions `cxListIteratorAt()` and `cxListBackwardsIteratorAt()` start with the element at the specified index |
301 and iterate until the end, or the beginning of the list, respectively. |
292 and iterate until the end, or the beginning of the list, respectively. |
302 |
293 |
303 The functions with `Mut` in are equivalent, except that they create a [mutating iterator](iterator.h.md#mutating-iterators). |
294 Removing elements via an iterator will cause an invocation of the [destructor functions](collection.h.md#destructor-functions) for the removed element. |
304 Removing elements via a mutating iterator will cause an invocation of the [destructor functions](collection.h.md#destructor-functions) for the removed element. |
|
305 |
295 |
306 It is safe to specify an out-of-bounds index, or a `NULL` pointer, in which cases the returned iterator will behave like an iterator over an empty list. |
296 It is safe to specify an out-of-bounds index, or a `NULL` pointer, in which cases the returned iterator will behave like an iterator over an empty list. |
307 |
297 |
308 ## Reorder |
298 ## Reorder |
309 |
299 |