comparison: docs/Writerside/topics/linked_list.h.md
docs/Writerside/topics/linked_list.h.md
- changeset 1618
- ef7cab6eb131
- parent 1605
- 55b13f583356
equal
deleted
inserted
replaced
| 1617:d4385f35f8b0 | 1618:ef7cab6eb131 |
|---|---|
| 180 void *cx_linked_list_at(const void *start, | 180 void *cx_linked_list_at(const void *start, |
| 181 size_t start_index, ptrdiff_t loc_advance, size_t index); | 181 size_t start_index, ptrdiff_t loc_advance, size_t index); |
| 182 | 182 |
| 183 void *cx_linked_list_find(const void *start, | 183 void *cx_linked_list_find(const void *start, |
| 184 ptrdiff_t loc_advance, ptrdiff_t loc_data, | 184 ptrdiff_t loc_advance, ptrdiff_t loc_data, |
| 185 cx_compare_func cmp_func, | 185 const void *elem, size_t *found_index, |
| 186 const void *elem, size_t *found_index); | 186 cx_compare_func cmp_func); |
| 187 | |
| 188 void *cx_linked_list_find_c(const void *start, | |
| 189 ptrdiff_t loc_advance, ptrdiff_t loc_data, | |
| 190 const void *elem, size_t *found_index, | |
| 191 cx_compare_func2 cmp_func, void *context); | |
| 187 | 192 |
| 188 size_t cx_linked_list_size(const void *node, ptrdiff_t loc_next); | 193 size_t cx_linked_list_size(const void *node, ptrdiff_t loc_next); |
| 189 ``` | 194 ``` |
| 190 | 195 |
| 191 The functions `cx_linked_list_first()` and `cx_linked_list_last()` can be used to find the first, or last, | 196 The functions `cx_linked_list_first()` and `cx_linked_list_last()` can be used to find the first, or last, |
| 202 The function `cx_linked_list_find()` starts a search at the `start` node and compares each element with `elem`. | 207 The function `cx_linked_list_find()` starts a search at the `start` node and compares each element with `elem`. |
| 203 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. | 208 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. |
| 204 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). | 209 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). |
| 205 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`. | 210 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`. |
| 206 | 211 |
| 212 The function `cx_linked_list_find_c()` allows additional `context` for the compare function. | |
| 213 | |
| 207 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. | 214 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. |
| 208 | 215 |
| 209 > A creative way of using `cx_linked_list_size()` in doubly-linked lists is to use the offset of the `prev` pointer | 216 > A creative way of using `cx_linked_list_size()` in doubly-linked lists is to use the offset of the `prev` pointer |
| 210 > for `loc_next`, in which case the function will return the index of the node within the list plus one. | 217 > for `loc_next`, in which case the function will return the index of the node within the list plus one. |
| 211 | 218 |
| 249 ptrdiff_t loc_prev, ptrdiff_t loc_next); | 256 ptrdiff_t loc_prev, ptrdiff_t loc_next); |
| 250 | 257 |
| 251 void cx_linked_list_sort(void **begin, void **end, | 258 void cx_linked_list_sort(void **begin, void **end, |
| 252 ptrdiff_t loc_prev, ptrdiff_t loc_next, | 259 ptrdiff_t loc_prev, ptrdiff_t loc_next, |
| 253 ptrdiff_t loc_data, cx_compare_func cmp_func); | 260 ptrdiff_t loc_data, cx_compare_func cmp_func); |
| 261 | |
| 262 void cx_linked_list_sort_c(void **begin, void **end, | |
| 263 ptrdiff_t loc_prev, ptrdiff_t loc_next, | |
| 264 ptrdiff_t loc_data, cx_compare_func2 cmp_func, | |
| 265 void *context); | |
| 254 ``` | 266 ``` |
| 255 | 267 |
| 256 The function `cx_linked_list_reverse()` swaps all links of all nodes in the specified list, effectively reversing the order of elements. | 268 The function `cx_linked_list_reverse()` swaps all links of all nodes in the specified list, effectively reversing the order of elements. |
| 257 | 269 |
| 258 The function `cx_linked_list_sort()` uses a recursive _natural mergesort_ implementation to sort the list with respect to the specified `cmp_fnc`. | 270 The function `cx_linked_list_sort()` uses a recursive _natural mergesort_ implementation to sort the list with respect to the specified `cmp_fnc`. |
| 259 The non-negative `loc_data` offset is used to calculate the pointers that are passed to the compare function. | 271 The non-negative `loc_data` offset is used to calculate the pointers that are passed to the compare function. |
| 260 If you choose `loc_data` to be zero, the pointers to the nodes themselves are passed. | 272 If you choose `loc_data` to be zero, the pointers to the nodes themselves are passed. |
| 273 | |
| 274 The function `cx_linked_list_sort_c()` allows additional `context` for the compare function. | |
| 261 | 275 |
| 262 > The `begin` pointer is required in all of the above functions while the `end` pointer is still optional. | 276 > The `begin` pointer is required in all of the above functions while the `end` pointer is still optional. |
| 263 > {style="note"} | 277 > {style="note"} |
| 264 | 278 |
| 265 > Sorting uses [small buffer optimization](install.md#small-buffer-optimizations) for small list sizes. | 279 > Sorting uses [small buffer optimization](install.md#small-buffer-optimizations) for small list sizes. |
| 274 int cx_linked_list_compare( | 288 int cx_linked_list_compare( |
| 275 const void *begin_left, const void *begin_right, | 289 const void *begin_left, const void *begin_right, |
| 276 ptrdiff_t loc_advance, ptrdiff_t loc_data, | 290 ptrdiff_t loc_advance, ptrdiff_t loc_data, |
| 277 cx_compare_func cmp_func | 291 cx_compare_func cmp_func |
| 278 ); | 292 ); |
| 293 | |
| 294 int cx_linked_list_compare_c( | |
| 295 const void *begin_left, const void *begin_right, | |
| 296 ptrdiff_t loc_advance, ptrdiff_t loc_data, | |
| 297 cx_compare_func2 cmp_func, void *context | |
| 298 ); | |
| 279 ``` | 299 ``` |
| 280 | 300 |
| 281 For comparing two linked list, you need to specify where to start, | 301 For comparing two linked list, you need to specify where to start, |
| 282 and the offsets for the pointer to the next node and the data. | 302 and the offsets for the pointer to the next node and the data. |
| 283 | 303 |
| 285 and `loc_advance` is the offset of the `next` pointer. | 305 and `loc_advance` is the offset of the `next` pointer. |
| 286 But it is also possible to start with the _last_ node of both lists and use the `prev` pointer to compare them backwards. | 306 But it is also possible to start with the _last_ node of both lists and use the `prev` pointer to compare them backwards. |
| 287 | 307 |
| 288 The `loc_data` offset is used to calculate the pointer that is passed to the `cmp_fnc`. | 308 The `loc_data` offset is used to calculate the pointer that is passed to the `cmp_fnc`. |
| 289 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. | 309 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. |
| 310 | |
| 311 The function `cx_linked_list_compare_c()` allows additional `context` for the compare function. | |
| 290 | 312 |
| 291 <seealso> | 313 <seealso> |
| 292 <category ref="apidoc"> | 314 <category ref="apidoc"> |
| 293 <a href="https://ucx.sourceforge.io/api/linked__list_8h.html">linked_list.h</a> | 315 <a href="https://ucx.sourceforge.io/api/linked__list_8h.html">linked_list.h</a> |
| 294 </category> | 316 </category> |
