Mercurial > hg > ucx / changeset

--- a/docs/Writerside/topics/list.h.md	Mon Mar 03 21:41:59 2025 +0100
+++ b/docs/Writerside/topics/list.h.md	Tue Mar 04 18:20:36 2025 +0100
@@ -8,13 +8,22 @@
 
 UCX already comes with two common list implementations ([linked list](linked_list.h.md) and [array list](array_list.h.md))
 that should cover most use cases.
-But if you feel the need to implement an own list, you will find instructions [below](#implementing-own-list-structures).
+But if you feel the need to implement an own list, you will find instructions [below](#implement-own-list-structures).
+
+## Example
 
-## Overview
+<warning>
+TODO: add example how to work with lists
+</warning>
+
+> If you want to lazy-initialize lists, you can use the global `cxEmptyList` symbol as a placeholder instead of using a `NULL`-pointer.
+> While you *must not* insert items into that list, you can safely access this list or create iterators.
+> This allows you to write clean code without checking for `NULL`-pointer everywhere.
+> You still need to make sure that the placeholder is replaced with an actual list before inserting items.
+
+## Insert
 
 ```C
-size_t cxListSize(const CxList *list);
-
 int cxListAdd(CxList *list, const void *elem);
 
 size_t cxListAddArray(CxList *list, const void *array, size_t n);
@@ -32,7 +41,33 @@
 int cxListInsertAfter(CxIterator *iter, const void *elem);
 
 int cxListInsertBefore(CxIterator *iter, const void *elem);
+```
 
+<warning>
+TODO: add documentation
+</warning>
+
+## Access and Find
+
+```C
+size_t cxListSize(const CxList *list);
+
+void *cxListAt(const CxList *list, size_t index);
+
+size_t cxListFind(const CxList *list, const void *elem);
+
+size_t cxListFindRemove(CxList *list, const void *elem);
+
+bool cxListIndexValid(const CxList *list, size_t index);
+```
+
+<warning>
+TODO: add documentation
+</warning>
+
+## Remove
+
+```C
 int cxListRemove(CxList *list, size_t index);
 
 int cxListRemoveAndGet(CxList *list, size_t index, void *targetbuf);
@@ -43,19 +78,15 @@
         void *targetbuf);
 
 void cxListClear(CxList *list);
-
-int cxListSwap(CxList *list, size_t i, size_t j);
-
-void *cxListAt(const CxList *list, size_t index);
-
-CxIterator cxListIteratorAt(const CxList *list, size_t index);
+```
 
-CxIterator cxListBackwardsIteratorAt(const CxList *list, size_t index);
+<warning>
+TODO: add documentation
+</warning>
 
-CxIterator cxListMutIteratorAt(CxList *list, size_t index);
+## Iterators
 
-CxIterator cxListMutBackwardsIteratorAt(CxList *list, size_t index);
-
+```C
 CxIterator cxListIterator(const CxList *list);
 
 CxIterator cxListMutIterator(CxList *list);
@@ -64,25 +95,58 @@
 
 CxIterator cxListMutBackwardsIterator(CxList *list);
 
-size_t cxListFind(const CxList *list, const void *elem);
+CxIterator cxListIteratorAt(const CxList *list, size_t index);
+
+CxIterator cxListBackwardsIteratorAt(const CxList *list, size_t index);
+
+CxIterator cxListMutIteratorAt(CxList *list, size_t index);
+
+CxIterator cxListMutBackwardsIteratorAt(CxList *list, size_t index);
+```
 
-bool cxListIndexValid(const CxList *list, size_t index);
+<warning>
+TODO: add documentation
+</warning>
 
-size_t cxListFindRemove(CxList *list, const void *elem);
+## Reorder
+
+```C
+int cxListSwap(CxList *list, size_t i, size_t j);
 
 void cxListSort(CxList *list);
 
 void cxListReverse(CxList *list);
-
-int cxListCompare(const CxList *list, const CxList *other);
+```
 
-void cxListFree(CxList *list);
+<warning>
+TODO: add documentation
+</warning>
 
-extern CxList *const cxEmptyList;
+## Compare
+
+```C
+int cxListCompare(const CxList *list, const CxList *other);
 ```
 
+<warning>
+TODO: add documentation
+</warning>
 
-## Implementing own List Structures
+## Dispose
+
+```C
+void cxListFree(CxList *list);
+```
+
+<warning>
+TODO: add documentation
+</warning>
+
+## Implement own List Structures
+
+<warning>
+TODO: add documentation
+</warning>
 
 <seealso>
 <category ref="apidoc">