comparison: docs/Writerside/topics/list.h.md
docs/Writerside/topics/list.h.md
- changeset 1315
- b4c3e0b4c3d5
- parent 1294
- 30d7ae76c76a
- child 1316
- c41538edfcef
equal
deleted
inserted
replaced
| 1314:25108c15e2d4 | 1315:b4c3e0b4c3d5 |
|---|---|
| 160 ```C | 160 ```C |
| 161 #include <cx/list.h> | 161 #include <cx/list.h> |
| 162 | 162 |
| 163 void *cxListAt(const CxList *list, size_t index); | 163 void *cxListAt(const CxList *list, size_t index); |
| 164 | 164 |
| 165 void *cxListFirst(const CxList *list); | |
| 166 | |
| 167 void *cxListLast(const CxList *list); | |
| 168 | |
| 165 int cxListSet(CxList *list, size_t index, const void *elem); | 169 int cxListSet(CxList *list, size_t index, const void *elem); |
| 166 | 170 |
| 167 size_t cxListFind(const CxList *list, const void *elem); | 171 size_t cxListFind(const CxList *list, const void *elem); |
| 168 | 172 |
| 169 size_t cxListFindRemove(CxList *list, const void *elem); | 173 size_t cxListFindRemove(CxList *list, const void *elem); |
| 177 | 181 |
| 178 The function `cxListAt()` accesses the element at the specified `index`. | 182 The function `cxListAt()` accesses the element at the specified `index`. |
| 179 If the list is storing pointers (i.e. `cxCollectionStoresPointers()` returns `true`), the pointer at the specified index is directly returned. | 183 If the list is storing pointers (i.e. `cxCollectionStoresPointers()` returns `true`), the pointer at the specified index is directly returned. |
| 180 Otherwise, a pointer to element at the specified index is returned. | 184 Otherwise, a pointer to element at the specified index is returned. |
| 181 If the index is out-of-bounds, the function returns `NULL`. | 185 If the index is out-of-bounds, the function returns `NULL`. |
| 186 The functions `cxListFirst()` and `cxListLast()` behave like `cxListAt()`, | |
| 187 accessing the first or the last valid index, respectively, and returning `NULL` when the list is empty. | |
| 182 | 188 |
| 183 The function `cxListSet()` allows you to modify elements at a specific index in the list. | 189 The function `cxListSet()` allows you to modify elements at a specific index in the list. |
| 184 This function replaces the element at the specified `index` with the value pointed to by `elem`. | 190 This function replaces the element at the specified `index` with the value pointed to by `elem`. |
| 185 If the list is storing values directly (not pointers), the contents at the memory location `elem` will be copied into the list. | 191 If the list is storing values directly (not pointers), the contents at the memory location `elem` will be copied into the list. |
| 186 If the list is storing pointers, the pointer value itself will be stored. | 192 If the list is storing pointers, the pointer value itself will be stored. |
| 205 | 211 |
| 206 int cxListRemove(CxList *list, size_t index); | 212 int cxListRemove(CxList *list, size_t index); |
| 207 | 213 |
| 208 size_t cxListRemoveArray(CxList *list, size_t index, size_t num); | 214 size_t cxListRemoveArray(CxList *list, size_t index, size_t num); |
| 209 | 215 |
| 216 size_t cxListFindRemove(CxList *list, const void *elem); | |
| 217 | |
| 210 int cxListRemoveAndGet(CxList *list, size_t index, void *targetbuf); | 218 int cxListRemoveAndGet(CxList *list, size_t index, void *targetbuf); |
| 219 | |
| 220 int cxListRemoveAndGetFirst(CxList *list, void *targetbuf); | |
| 221 | |
| 222 int cxListPopFront(CxList *list, void *targetbuf); | |
| 223 | |
| 224 int cxListRemoveAndLast(CxList *list, void *targetbuf); | |
| 225 | |
| 226 int cxListPop(CxList *list, void *targetbuf); | |
| 211 | 227 |
| 212 size_t cxListRemoveArrayAndGet(CxList *list, size_t index, size_t num, | 228 size_t cxListRemoveArrayAndGet(CxList *list, size_t index, size_t num, |
| 213 void *targetbuf); | 229 void *targetbuf); |
| 214 | |
| 215 size_t cxListFindRemove(CxList *list, const void *elem); | |
| 216 | 230 |
| 217 void cxListClear(CxList *list); | 231 void cxListClear(CxList *list); |
| 218 ``` | 232 ``` |
| 219 | 233 |
| 220 The function `cxListRemove()` removes the element at the specified index and returns zero, | 234 The function `cxListRemove()` removes the element at the specified index and returns zero, |
| 221 or returns non-zero if the index is out-of-bounds. | 235 or returns non-zero if the index is out-of-bounds. |
| 222 The function `cxListRemoveArray()` removes `num` elements starting at `index` and returns the number of elements that have been removed. | 236 The function `cxListRemoveArray()` removes `num` elements starting at `index` and returns the number of elements that have been removed. |
| 223 For each removed element, the [destructor functions](collection.h.md#destructor-functions) are called. | 237 For each removed element, the [destructor functions](collection.h.md#destructor-functions) are called. |
| 224 | 238 |
| 225 On the other hand, `cxListRemoveAndGet()` and `cxListRemoveArrayAndGet()` do not invoke the destructor functions | |
| 226 and instead copy the elements into the `targetbuf`, which must be large enough to hold the removed elements. | |
| 227 | |
| 228 The function `cxListFindRemove()` finds the first element within the list that is equivalent to the element pointed to by `elem` and removes it from the list. | 239 The function `cxListFindRemove()` finds the first element within the list that is equivalent to the element pointed to by `elem` and removes it from the list. |
| 229 This will _also_ call destructor functions, if specified, so take special care when you continue to use `elem`. | 240 This will _also_ call destructor functions, if specified, so take special care when you continue to use `elem`. |
| 241 | |
| 242 On the other hand, `cxListRemoveAndGet()` family of functions do not invoke the destructor functions | |
| 243 and instead copy the elements into the `targetbuf`, which must be large enough to hold the removed elements. | |
| 244 | |
| 245 > Note, that when the list was initialized with `CX_STORE_POINTERS`, | |
| 246 > the elements that will be copied to the `targetbuf` are the _pointers_. | |
| 247 > In contrast to other list functions, like `cxListAt()`, an automatic dereferencing does not happen here. | |
| 248 >{style="note"} | |
| 230 | 249 |
| 231 The function `cxListClear()` simply removes all elements from the list, invoking the destructor functions. | 250 The function `cxListClear()` simply removes all elements from the list, invoking the destructor functions. |
| 232 It behaves equivalently, but is usually more efficient than calling `cxListRemove()` for every index. | 251 It behaves equivalently, but is usually more efficient than calling `cxListRemove()` for every index. |
| 233 | 252 |
| 234 ## Iterators | 253 ## Iterators |
