--- a/docs/Writerside/topics/linked_list.h.md Wed Dec 31 15:25:30 2025 +0100
+++ b/docs/Writerside/topics/linked_list.h.md Wed Dec 31 16:01:08 2025 +0100
@@ -47,16 +47,16 @@
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)`.
-In all functions, `loc_prev` is optional in the sense, that when you do not have a `prev` pointer, you can specify a negative value.
+In all functions, `loc_prev` is optional in the sense that when you do not have a `prev` pointer, you can specify a negative value.
When a function expects a `loc_advance` offset, you can freely choose if you want to pass the offset of the `next` or the `prev` pointer,
depending on what you want to do.
If a function expects a `void** begin` and a `void** end` pointer, they are usually both optional, unless otherwise specified.
-If non-`NULL`, they point to the variables where the addresses of the first, or the last, node of a list are stored, respectively.
+If non-`NULL`, they point to the variables where the addresses of the first, or the last, node belonging to the list are stored, respectively.
When a list operation results in a new first (or last) node, the addresses are overwritten.
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.
+hence passing `NULL` to the `begin` and the address of your top-of-stack pointer to the `end`.
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.
@@ -91,7 +91,7 @@
ptrdiff_t loc_prev, ptrdiff_t loc_next);
```
-When you have two nodes `left` and `right` you can link or unlink them with the functions shown above.
+When you have two nodes `left` and `right`, you can link or unlink them with the functions shown above.
When linking `left` and `right` you should make sure that `left` as currently no successor and `right` has no predecessor,
because the pointers will be overwritten without unlinking possible existing links, first.
@@ -184,7 +184,7 @@
> it cannot take advantage of simply inserting the entire chain as-is, as the chain might need to be broken
> to maintain the sort order.
-The functions with the `_c` suffix are equivalent, except that they accept a `cx_compare_func2` with additional `context`.
+The functions with the `_c` suffix are equivalent, except that they accept a `cx_compare_func2` with an additional `context`.
## Access and Find
@@ -215,7 +215,7 @@
node in your list in case you are not keeping track of them separately.
They can start at an arbitrary node within the list.
-The function `cx_linked_list_at()` starts at an arbitrary node `start` which is _specified_ to have the index `start_index`,
+The function `cx_linked_list_at()` starts at an arbitrary node `start`, which is _specified_ to have the index `start_index`,
and finds the node at `index`.
If `index` is larger than `start_index`, you must pass the offset of the `next` pointer to `loc_advanced`.
On the other hand, if `index` is smaller than `start_index`, you must pass the offset of the `prev` pointer.
@@ -225,13 +225,13 @@
The function `cx_linked_list_find()` starts a search at the `start` node and compares each element with `elem`.
If `loc_data` is non-zero, the data-type of `elem` must be a pointer to data which is compatible to the data located at the specified offset in the node.
If `loc_data` is zero, `elem` is expected to point to a node structure (which is usually artificially created for the sake of comparison and not contained in the list).
-When the searched element is found, a pointer to the node is returned and the index (assuming `start` has index zero) is written to the optional `found_index`, if non-`NULL`.
+When the searched element is found, a pointer to the node is returned, and the index (assuming `start` has index zero) is written to the optional `found_index`, if non-`NULL`.
The function `cx_linked_list_find_c()` allows additional `context` for the compare function.
The size of a list, or sub-list, can be determined with `cx_linked_list_size()` which may start at an arbitrary `node´ in the list.
-> A creative way of using `cx_linked_list_size()` in doubly-linked lists is to use the offset of the `prev` pointer
+> A creative way of using `cx_linked_list_size()` in doubly linked lists is to use the offset of the `prev` pointer
> for `loc_next`, in which case the function will return the index of the node within the list plus one.
## Remove
@@ -257,11 +257,11 @@
The `prev` and `next` pointers of _all_ removed nodes are kept completely intact, allowing traversal within the removed chain,
as well as identifying the formerly adjacent nodes with the list from which the chain was removed.
-> Both `begin` and `end` pointers are optional, if you specify both `loc_prev` and `loc_next`.
+> Both `begin` and `end` pointers are optional if you specify both `loc_prev` and `loc_next`.
> In case your list does not have a `prev` pointer, specifying `begin` is mandatory (because there would be no other way to determine the predecessor of `node`).
>{style="note"}
-> While specifying _only_ `loc_prev` and `end` is technically illegal, you can simply swap roles
+> While specifying _only_ `loc_prev` and `end` is technically illegal, you can swap their roles
> and use the offset of your `prev` pointer as `loc_next` and the address of your `end` pointer as `begin`.
> The list is then traversed backwards, but otherwise everything works as expected.
@@ -291,7 +291,7 @@
The function `cx_linked_list_sort_c()` allows additional `context` for the compare function.
-> The `begin` pointer is required in all of the above functions while the `end` pointer is still optional.
+> The `begin` pointer is required in all the above functions, while the `end` pointer is still optional.
> {style="note"}
> Sorting uses [small buffer optimization](install.md#small-buffer-optimizations) for small list sizes.
@@ -323,7 +323,7 @@
and `loc_advance` is the offset of the `next` pointer.
But it is also possible to start with the _last_ node of both lists and use the `prev` pointer to compare them backwards.
-The `loc_data` offset is used to calculate the pointer that is passed to the `cmp_func`.
+The `loc_data` offset is used to calculate the pointer passed to the `cmp_func`.
This can either be the offset of a specific field in the struct or simply zero, in which case the pointers to the nodes themselves are passed to the compare function.
The function `cx_linked_list_compare_c()` allows additional `context` for the compare function.