Mercurial > hg > ucx / file diff

--- 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.