--- a/docs/Writerside/topics/list.h.md Sun May 04 12:15:03 2025 +0200
+++ b/docs/Writerside/topics/list.h.md Sun May 04 17:22:30 2025 +0200
@@ -116,6 +116,10 @@
int cxListInsert(CxList *list, size_t index, const void *elem);
+void *cxListEmplace(CxList *list);
+
+void *cxListEmplaceAt(CxList *list, size_t index);
+
int cxListInsertSorted(CxList *list, const void *elem);
size_t cxListAddArray(CxList *list, const void *array, size_t n);
@@ -132,8 +136,13 @@
```
The function `cxListAdd()` appends the element `elem` to the list and returns zero on success or non-zero when allocating the memory for the element fails.
-Similarly, `cxListInsert()` adds the element at the specified `index`,
-and `cxListInsertSorted()` adds the element at the correct position so that the list remains sorted according to the list's compare function.
+Similarly, `cxListInsert()` adds the element at the specified `index`.
+
+The functions `cxListEmplace()` and `cxListEmplaceAt()` behave like `cxListAdd()` and `cxListInsert()`,
+except that they only allocate the memory and return a pointer to it, leaving it to the callee to copy the element data into it.
+Be aware that when the list is storing pointers, the allocated memory will be for the pointer, not the actual element's data.
+
+The function `cxListInsertSorted()` inserts the element at the correct position so that the list remains sorted according to the list's compare function.
When you are currently iterating through a list, you can insert elements before or after the current position of the iterator
with `cxListInsertBefore()` or `cxListInsertAfter()`, respectively.
@@ -405,7 +414,7 @@
|------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `clear` | Invoke destructor functions on all elements and remove them from the list. |
| `deallocate` | Invoke destructor functions on all elements and deallocate the entire list memory. |
-| `insert_element` | Insert a single element at the specified index. Return zero on success and non-zero on failure. |
+| `insert_element` | Insert a single element at the specified index. Return a pointer to the data of the inserted element or `NULL` on failure. |
| `insert_array` | Insert an array of elements starting at the specified index. Return the number of elements inserted. |
| `insert_sorted` | Insert an array of sorted elements into a sorted list. Return the number of elements inserted. |
| `insert_iter` | Insert a single element depending on the iterator position. The third argument to this function is zero when the element shall be inserted after the iterator position and non-zero if it shall be inserted before the iterator position. The implementation is also responsible for adjusting the iterator, respectively. |
