diff -r 25108c15e2d4 -r b4c3e0b4c3d5 docs/Writerside/topics/list.h.md --- a/docs/Writerside/topics/list.h.md Sun May 04 11:46:13 2025 +0200 +++ b/docs/Writerside/topics/list.h.md Sun May 04 12:15:03 2025 +0200 @@ -162,6 +162,10 @@ void *cxListAt(const CxList *list, size_t index); +void *cxListFirst(const CxList *list); + +void *cxListLast(const CxList *list); + int cxListSet(CxList *list, size_t index, const void *elem); size_t cxListFind(const CxList *list, const void *elem); @@ -179,6 +183,8 @@ If the list is storing pointers (i.e. `cxCollectionStoresPointers()` returns `true`), the pointer at the specified index is directly returned. Otherwise, a pointer to element at the specified index is returned. If the index is out-of-bounds, the function returns `NULL`. +The functions `cxListFirst()` and `cxListLast()` behave like `cxListAt()`, +accessing the first or the last valid index, respectively, and returning `NULL` when the list is empty. The function `cxListSet()` allows you to modify elements at a specific index in the list. This function replaces the element at the specified `index` with the value pointed to by `elem`. @@ -207,12 +213,20 @@ size_t cxListRemoveArray(CxList *list, size_t index, size_t num); +size_t cxListFindRemove(CxList *list, const void *elem); + int cxListRemoveAndGet(CxList *list, size_t index, void *targetbuf); +int cxListRemoveAndGetFirst(CxList *list, void *targetbuf); + +int cxListPopFront(CxList *list, void *targetbuf); + +int cxListRemoveAndLast(CxList *list, void *targetbuf); + +int cxListPop(CxList *list, void *targetbuf); + size_t cxListRemoveArrayAndGet(CxList *list, size_t index, size_t num, void *targetbuf); - -size_t cxListFindRemove(CxList *list, const void *elem); void cxListClear(CxList *list); ``` @@ -222,11 +236,16 @@ The function `cxListRemoveArray()` removes `num` elements starting at `index` and returns the number of elements that have been removed. For each removed element, the [destructor functions](collection.h.md#destructor-functions) are called. -On the other hand, `cxListRemoveAndGet()` and `cxListRemoveArrayAndGet()` do not invoke the destructor functions +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. +This will _also_ call destructor functions, if specified, so take special care when you continue to use `elem`. + +On the other hand, `cxListRemoveAndGet()` family of functions do not invoke the destructor functions and instead copy the elements into the `targetbuf`, which must be large enough to hold the removed elements. -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. -This will _also_ call destructor functions, if specified, so take special care when you continue to use `elem`. +> Note, that when the list was initialized with `CX_STORE_POINTERS`, +> the elements that will be copied to the `targetbuf` are the _pointers_. +> In contrast to other list functions, like `cxListAt()`, an automatic dereferencing does not happen here. +>{style="note"} The function `cxListClear()` simply removes all elements from the list, invoking the destructor functions. It behaves equivalently, but is usually more efficient than calling `cxListRemove()` for every index.