Mercurial > hg > ucx / changeset

--- a/docs/Writerside/topics/linked_list.h.md	Tue Dec 02 17:35:54 2025 +0100
+++ b/docs/Writerside/topics/linked_list.h.md	Wed Dec 03 00:01:17 2025 +0100
@@ -9,17 +9,33 @@
 ```C
 #include <cx/linked_list.h>
 
+typedef struct cx_linked_list_s cx_linked_list;
+
 CxList *cxLinkedListCreate(const CxAllocator *allocator,
         cx_compare_func comparator, size_t elem_size);
         
 CxList *cxLinkedListCreateSimple(size_t elem_size);
 ```
 
-The remaining content of this page concentrates on the low-level functions. 
+If you are using high-level linked lists to implement your own list structure,
+it might be necessary to store additional data in each node that does not belong to the elements.
+For this purpose, there exists the following function.
+
+```C
+void cx_linked_list_extra_data(cx_linked_list *list, size_t len);
+```
+
+It instructs the linked list to allocate `len` bytes of extra data when allocating a node.
+The location offset of the extra data is stored in the `loc_extra` field of the linked list.
+
+> The [key/value list](kv_list.h.md) uses this technique to store the `CxHashKey` as extra data in each node. 
 
 ## Basic Structure
 
-All functions described on this page work with nodes that have the following structure.
+This section and the remaining content of this page describe the low-level functions for linked lists.
+
+Those work with nodes that have the following structure.
+
 ```C
 struct node {
     node *next;
@@ -29,7 +45,7 @@
 ```
 
 Each node must have at least one pointer that contains the address of the subsequent node.
-Optionally, for doubly-linked lists, there may be a second pointer that points to the predecessor.
+Optionally, for doubly linked lists, there may be a second pointer that points to the predecessor.
 
 The functions usually expect a `loc_prev` and a `loc_next` offset.
 In the example structure from above you can obtain them with `offsetof(struct node, next)` and `offsetof(struct node, prev)`.
@@ -43,9 +59,9 @@
 In simple scenarios, you usually keep a pointer to the beginning of a list, and hence you would usually pass `NULL` to the `end` argument.
 If you are designing a stack-like linked-list, it may happen that you only want to store the last node of a list (the top of stack),
 hence passing `NULL` to the `begin` argument and the address of your top-of-stack pointer to the `end` argument.
-Either way, most functions allow you a big deal of flexibility - please still read the documentation of each function carefully to learn which combinations are allowed.
+Either way, most functions allow you a big deal of flexibility — please still read the documentation of each function carefully to learn which combinations are allowed.
 
-When you are working with a singly-linked list, it is still sometimes necessary to access the predecessor of a node.
+When you are working with a singly linked list, it is still sometimes necessary to access the predecessor of a node.
 In the absence of a `prev` pointer, the only chance is to start at the beginning of the list and search for that node.
 This is exactly what `cx_linked_list_prev()` does.
 ```C