1.1 --- a/src/cx/linked_list.h Mon Dec 20 13:01:38 2021 +0100
1.2 +++ b/src/cx/linked_list.h Thu Dec 23 15:20:50 2021 +0100
1.3 @@ -55,7 +55,11 @@
1.4 * @param item_size the size of each element in bytes
1.5 * @return the created list
1.6 */
1.7 -CxList cxLinkedListCreate(CxAllocator allocator, CxListComparator comparator, size_t item_size);
1.8 +CxList cxLinkedListCreate(
1.9 + CxAllocator allocator,
1.10 + CxListComparator comparator,
1.11 + size_t item_size
1.12 +);
1.13
1.14 /**
1.15 * Allocates a linked list for storing pointers.
1.16 @@ -66,7 +70,10 @@
1.17 * @param comparator the comparator for the elements
1.18 * @return the created list
1.19 */
1.20 -CxList cxPointerLinkedListCreate(CxAllocator allocator, CxListComparator comparator);
1.21 +CxList cxPointerLinkedListCreate(
1.22 + CxAllocator allocator,
1.23 + CxListComparator comparator
1.24 +);
1.25
1.26 /**
1.27 * Deallocates the memory of the entire list.
1.28 @@ -94,8 +101,12 @@
1.29 * @param index the search index
1.30 * @return the node found at the specified index
1.31 */
1.32 -void *cx_linked_list_at(void *start, size_t start_index, ptrdiff_t loc_advance, size_t index)
1.33 -__attribute__((__nonnull__));
1.34 +void *cx_linked_list_at(
1.35 + void *start,
1.36 + size_t start_index,
1.37 + ptrdiff_t loc_advance,
1.38 + size_t index
1.39 +) __attribute__((__nonnull__));
1.40
1.41 /**
1.42 * Finds the index of an element within a linked list.
1.43 @@ -109,9 +120,14 @@
1.44 * @param elem a pointer to the element to find
1.45 * @return the index of the element or a past-one index if the element could not be found
1.46 */
1.47 -size_t cx_linked_list_find(void *start, ptrdiff_t loc_advance, ptrdiff_t loc_data, int follow_ptr,
1.48 - CxListComparator cmp_func, void *elem)
1.49 -__attribute__((__nonnull__));
1.50 +size_t cx_linked_list_find(
1.51 + void *start,
1.52 + ptrdiff_t loc_advance,
1.53 + ptrdiff_t loc_data,
1.54 + int follow_ptr,
1.55 + CxListComparator cmp_func,
1.56 + void *elem
1.57 +) __attribute__((__nonnull__));
1.58
1.59 /**
1.60 * Finds the first node in a linked list.
1.61 @@ -123,8 +139,10 @@
1.62 * @param node a pointer to a node in the list
1.63 * @param loc_prev the location of the \c prev pointer
1.64 */
1.65 -void *cx_linked_list_first(void *node, ptrdiff_t loc_prev)
1.66 -__attribute__((__nonnull__));
1.67 +void *cx_linked_list_first(
1.68 + void *node,
1.69 + ptrdiff_t loc_prev
1.70 +) __attribute__((__nonnull__));
1.71
1.72 /**
1.73 * Finds the last node in a linked list.
1.74 @@ -137,8 +155,10 @@
1.75 * @param loc_next the location of the \c next pointer
1.76 * @return a pointer to the last node
1.77 */
1.78 -void *cx_linked_list_last(void *node, ptrdiff_t loc_next)
1.79 -__attribute__((__nonnull__));
1.80 +void *cx_linked_list_last(
1.81 + void *node,
1.82 + ptrdiff_t loc_next
1.83 +) __attribute__((__nonnull__));
1.84
1.85 /**
1.86 * Finds the predecessor of a node in case it is not linked.
1.87 @@ -150,8 +170,11 @@
1.88 * @param node the successor of the node to find
1.89 * @return the node or \c NULL if \p node has no predecessor
1.90 */
1.91 -void *cx_linked_list_prev(void *begin, ptrdiff_t loc_next, void *node)
1.92 -__attribute__((__nonnull__));
1.93 +void *cx_linked_list_prev(
1.94 + void *begin,
1.95 + ptrdiff_t loc_next,
1.96 + void *node
1.97 +) __attribute__((__nonnull__));
1.98
1.99 /**
1.100 * Adds a new node to a linked list.
1.101 @@ -165,8 +188,13 @@
1.102 * @param loc_next the location of a \c next pointer within your node struct (required)
1.103 * @param new_node a pointer to the node that shall be appended
1.104 */
1.105 -void cx_linked_list_add(void **begin, void **end, ptrdiff_t loc_prev, ptrdiff_t loc_next, void *new_node)
1.106 -__attribute__((__nonnull__(5)));
1.107 +void cx_linked_list_add(
1.108 + void **begin,
1.109 + void **end,
1.110 + ptrdiff_t loc_prev,
1.111 + ptrdiff_t loc_next,
1.112 + void *new_node
1.113 +) __attribute__((__nonnull__(5)));
1.114
1.115 /**
1.116 * Prepends a new node to a linked list.
1.117 @@ -180,8 +208,98 @@
1.118 * @param loc_next the location of a \c next pointer within your node struct (required)
1.119 * @param new_node a pointer to the node that shall be prepended
1.120 */
1.121 -void cx_linked_list_prepend(void **begin, void **end, ptrdiff_t loc_prev, ptrdiff_t loc_next, void *new_node)
1.122 -__attribute__((__nonnull__(5)));
1.123 +void cx_linked_list_prepend(
1.124 + void **begin,
1.125 + void **end,
1.126 + ptrdiff_t loc_prev,
1.127 + ptrdiff_t loc_next,
1.128 + void *new_node
1.129 +) __attribute__((__nonnull__(5)));
1.130 +
1.131 +/**
1.132 + * Links two nodes.
1.133 + *
1.134 + * @param left the new predecessor of \p right
1.135 + * @param right the new successor of \p left
1.136 + * @param loc_prev the location of a \c prev pointer within your node struct (negative if your struct does not have one)
1.137 + * @param loc_next the location of a \c next pointer within your node struct (required)
1.138 + */
1.139 +void cx_linked_list_link(
1.140 + void *left,
1.141 + void *right,
1.142 + ptrdiff_t loc_prev,
1.143 + ptrdiff_t loc_next
1.144 +) __attribute__((__nonnull__));
1.145 +
1.146 +/**
1.147 + * Unlinks two nodes.
1.148 + *
1.149 + * If right is not the successor of left, the behavior is undefined.
1.150 + *
1.151 + * @param left the predecessor of \p right
1.152 + * @param right the successor of \p left
1.153 + * @param loc_prev the location of a \c prev pointer within your node struct (negative if your struct does not have one)
1.154 + * @param loc_next the location of a \c next pointer within your node struct (required)
1.155 + */
1.156 +void cx_linked_list_unlink(
1.157 + void *left,
1.158 + void *right,
1.159 + ptrdiff_t loc_prev,
1.160 + ptrdiff_t loc_next
1.161 +) __attribute__((__nonnull__));
1.162 +
1.163 +/**
1.164 + * Inserts a new node after a given node of a linked list.
1.165 + * The new node must not be part of any list already.
1.166 + *
1.167 + * \note If you specify \c NULL as the \p node to insert after, this function needs either the \p begin or
1.168 + * the \p end pointer to determine the start of the list. Then the new node will be prepended to the list.
1.169 + *
1.170 + * @param begin a pointer to the begin node pointer (if your list has one)
1.171 + * @param end a pointer to the end node pointer (if your list has one)
1.172 + * @param loc_prev the location of a \c prev pointer within your node struct (negative if your struct does not have one)
1.173 + * @param loc_next the location of a \c next pointer within your node struct (required)
1.174 + * @param node the node after which to insert (\c NULL if you want to prepend the node to the list)
1.175 + * @param new_node a pointer to the node that shall be prepended
1.176 + */
1.177 +void cx_linked_list_insert(
1.178 + void **begin,
1.179 + void **end,
1.180 + ptrdiff_t loc_prev,
1.181 + ptrdiff_t loc_next,
1.182 + void *node,
1.183 + void *new_node
1.184 +) __attribute__((__nonnull__(6)));
1.185 +
1.186 +/**
1.187 + * Inserts a chain of nodes after a given node of a linked list.
1.188 + * The chain must not be part of any list already.
1.189 + *
1.190 + * If you do not explicitly specify the end of the chain, it will be determined by traversing
1.191 + * the \c next pointer.
1.192 + *
1.193 + * \note If you specify \c NULL as the \p node to insert after, this function needs either the \p begin or
1.194 + * the \p end pointer to determine the start of the list. If only the \p end pointer is specified, you also need
1.195 + * to provide a valid \p loc_prev location.
1.196 + * Then the chain will be prepended to the list.
1.197 + *
1.198 + * @param begin a pointer to the begin node pointer (if your list has one)
1.199 + * @param end a pointer to the end node pointer (if your list has one)
1.200 + * @param loc_prev the location of a \c prev pointer within your node struct (negative if your struct does not have one)
1.201 + * @param loc_next the location of a \c next pointer within your node struct (required)
1.202 + * @param node the node after which to insert (\c NULL to prepend the chain to the list)
1.203 + * @param insert_begin a pointer to the first node of the chain that shall be inserted
1.204 + * @param insert_end a pointer to the last node of the chain (or NULL if the last node shall be determined)
1.205 + */
1.206 +void cx_linked_list_insert_chain(
1.207 + void **begin,
1.208 + void **end,
1.209 + ptrdiff_t loc_prev,
1.210 + ptrdiff_t loc_next,
1.211 + void *node,
1.212 + void *insert_begin,
1.213 + void *insert_end
1.214 +) __attribute__((__nonnull__(6)));
1.215
1.216 /**
1.217 * Removes a node from the linked list.
1.218 @@ -202,8 +320,13 @@
1.219 * @param loc_next the location of a \c next pointer within your node struct (required)
1.220 * @param node the node to remove
1.221 */
1.222 -void cx_linked_list_remove(void **begin, void **end, ptrdiff_t loc_prev, ptrdiff_t loc_next, void *node)
1.223 -__attribute__((__nonnull__(5)));
1.224 +void cx_linked_list_remove(
1.225 + void **begin,
1.226 + void **end,
1.227 + ptrdiff_t loc_prev,
1.228 + ptrdiff_t loc_next,
1.229 + void *node
1.230 +) __attribute__((__nonnull__(5)));
1.231
1.232
1.233 /**
1.234 @@ -212,7 +335,10 @@
1.235 * @param loc_next the location of the \c next pointer within the node struct
1.236 * @return the size of the list or zero if \p node is \c NULL
1.237 */
1.238 -size_t cx_linked_list_size(void *node, ptrdiff_t loc_next);
1.239 +size_t cx_linked_list_size(
1.240 + void *node,
1.241 + ptrdiff_t loc_next
1.242 +);
1.243
1.244 /**
1.245 * Sorts a linked list based on a comparison function.
1.246 @@ -245,10 +371,15 @@
1.247 * If \c true, the data at \p loc_data is assumed to be a pointer, dereferenced, and then passed to \p cmp_func.
1.248 * @param cmp_func the compare function defining the sort order
1.249 */
1.250 -void cx_linked_list_sort(void **begin, void **end, ptrdiff_t loc_prev, ptrdiff_t loc_next,
1.251 - ptrdiff_t loc_data, int follow_ptr, CxListComparator cmp_func)
1.252 -__attribute__((__nonnull__(1, 7)));
1.253 -
1.254 +void cx_linked_list_sort(
1.255 + void **begin,
1.256 + void **end,
1.257 + ptrdiff_t loc_prev,
1.258 + ptrdiff_t loc_next,
1.259 + ptrdiff_t loc_data,
1.260 + int follow_ptr,
1.261 + CxListComparator cmp_func
1.262 +) __attribute__((__nonnull__(1, 7)));
1.263
1.264 /**
1.265 * Reverses the order of the nodes in a linked list.
1.266 @@ -258,8 +389,12 @@
1.267 * @param loc_prev the location of a \c prev pointer within your node struct (negative if your struct does not have one)
1.268 * @param loc_next the location of a \c next pointer within your node struct (required)
1.269 */
1.270 -void cx_linked_list_reverse(void **begin, void **end, ptrdiff_t loc_prev, ptrdiff_t loc_next)
1.271 -__attribute__((__nonnull__(1)));
1.272 +void cx_linked_list_reverse(
1.273 + void **begin,
1.274 + void **end,
1.275 + ptrdiff_t loc_prev,
1.276 + ptrdiff_t loc_next
1.277 +) __attribute__((__nonnull__(1)));
1.278
1.279 #ifdef __cplusplus
1.280 } /* extern "C" */
