92 * @param start_index the start index |
92 * @param start_index the start index |
93 * @param loc_advance the location of the pointer to advance |
93 * @param loc_advance the location of the pointer to advance |
94 * @param index the search index |
94 * @param index the search index |
95 * @return the node found at the specified index |
95 * @return the node found at the specified index |
96 */ |
96 */ |
97 void *cx_linked_list_at(void *start, size_t start_index, ptrdiff_t loc_advance, size_t index); |
97 void *cx_linked_list_at(void *start, size_t start_index, ptrdiff_t loc_advance, size_t index) |
|
98 __attribute__((__nonnull__)); |
98 |
99 |
99 /** |
100 /** |
100 * Finds the first node in a linked list. |
101 * Finds the first node in a linked list. |
101 * |
102 * |
102 * The function starts with the pointer denoted by \p node and traverses the list |
103 * The function starts with the pointer denoted by \p node and traverses the list |
103 * along a prev pointer whose location within the node struct is |
104 * along a prev pointer whose location within the node struct is |
104 * denoted by \p loc_prev. |
105 * denoted by \p loc_prev. |
105 * |
106 * |
106 * @param node a pointer to a node in the list |
107 * @param node a pointer to a node in the list |
107 * @param loc_prev the location of the \c prev pointer |
108 * @param loc_prev the location of the \c prev pointer |
108 * @return a pointer to the first node or \c NULL if \p node is \c NULL |
109 */ |
109 */ |
110 void *cx_linked_list_first(void *node, ptrdiff_t loc_prev) |
110 void *cx_linked_list_first(void *node, ptrdiff_t loc_prev); |
111 __attribute__((__nonnull__)); |
111 |
112 |
112 /** |
113 /** |
113 * Finds the last node in a linked list. |
114 * Finds the last node in a linked list. |
114 * |
115 * |
115 * The function starts with the pointer denoted by \p node and traverses the list |
116 * The function starts with the pointer denoted by \p node and traverses the list |
116 * along a next pointer whose location within the node struct is |
117 * along a next pointer whose location within the node struct is |
117 * denoted by \p loc_next. |
118 * denoted by \p loc_next. |
118 * |
119 * |
119 * @param node a pointer to a node in the list |
120 * @param node a pointer to a node in the list |
120 * @param loc_next the location of the \c next pointer |
121 * @param loc_next the location of the \c next pointer |
121 * @return a pointer to the last node or \c NULL if \p begin is \c NULL |
122 * @return a pointer to the last node |
122 */ |
123 */ |
123 void *cx_linked_list_last(void *node, ptrdiff_t loc_next); |
124 void *cx_linked_list_last(void *node, ptrdiff_t loc_next) |
|
125 __attribute__((__nonnull__)); |
124 |
126 |
125 /** |
127 /** |
126 * Finds the predecessor of a node in case it is not linked. |
128 * Finds the predecessor of a node in case it is not linked. |
127 * |
129 * |
128 * \remark If \p node is not contained in the list starting with \p begin, the behavior is undefined. |
130 * \remark If \p node is not contained in the list starting with \p begin, the behavior is undefined. |
130 * @param begin the node where to start the search |
132 * @param begin the node where to start the search |
131 * @param loc_next the location of the \c next pointer |
133 * @param loc_next the location of the \c next pointer |
132 * @param node the successor of the node to find |
134 * @param node the successor of the node to find |
133 * @return the node or \c NULL if \p node has no predecessor |
135 * @return the node or \c NULL if \p node has no predecessor |
134 */ |
136 */ |
135 void *cx_linked_list_prev(void *begin, ptrdiff_t loc_next, void *node); |
137 void *cx_linked_list_prev(void *begin, ptrdiff_t loc_next, void *node) |
|
138 __attribute__((__nonnull__)); |
136 |
139 |
137 /** |
140 /** |
138 * Adds a new node to a linked list. |
141 * Adds a new node to a linked list. |
139 * The node must not be part of any list already. |
142 * The node must not be part of any list already. |
140 * |
143 * |
141 * \remark One of the pointers \p begin and \p end may be \c NULL, but not both. |
144 * \remark One of the pointers \p begin or \p end may be \c NULL, but not both. |
142 * |
145 * |
143 * @param begin a pointer to the begin node pointer (if your list has one) |
146 * @param begin a pointer to the begin node pointer (if your list has one) |
144 * @param end a pointer to the end node pointer (if your list has one) |
147 * @param end a pointer to the end node pointer (if your list has one) |
145 * @param loc_prev the location of a \c prev pointer within your node struct (negative if your struct does not have one) |
148 * @param loc_prev the location of a \c prev pointer within your node struct (negative if your struct does not have one) |
146 * @param loc_next the location of a \c next pointer within your node struct (required) |
149 * @param loc_next the location of a \c next pointer within your node struct (required) |
147 * @param new_node a pointer to the node that shall be appended |
150 * @param new_node a pointer to the node that shall be appended |
148 */ |
151 */ |
149 void cx_linked_list_add(void **begin, void **end, ptrdiff_t loc_prev, ptrdiff_t loc_next, void *new_node); |
152 void cx_linked_list_add(void **begin, void **end, ptrdiff_t loc_prev, ptrdiff_t loc_next, void *new_node) |
|
153 __attribute__((__nonnull__(5))); |
150 |
154 |
151 /** |
155 /** |
152 * Prepends a new node to a linked list. |
156 * Prepends a new node to a linked list. |
153 * The node must not be part of any list already. |
157 * The node must not be part of any list already. |
154 * |
158 * |
155 * \remark One of the pointers \p begin and \p end may be \c NULL, but not both. |
159 * \remark One of the pointers \p begin or \p end may be \c NULL, but not both. |
156 * |
160 * |
157 * @param begin a pointer to the begin node pointer (if your list has one) |
161 * @param begin a pointer to the begin node pointer (if your list has one) |
158 * @param end a pointer to the end node pointer (if your list has one) |
162 * @param end a pointer to the end node pointer (if your list has one) |
159 * @param loc_prev the location of a \c prev pointer within your node struct (negative if your struct does not have one) |
163 * @param loc_prev the location of a \c prev pointer within your node struct (negative if your struct does not have one) |
160 * @param loc_next the location of a \c next pointer within your node struct (required) |
164 * @param loc_next the location of a \c next pointer within your node struct (required) |
161 * @param new_node a pointer to the node that shall be prepended |
165 * @param new_node a pointer to the node that shall be prepended |
162 */ |
166 */ |
163 void cx_linked_list_prepend(void **begin, void **end, ptrdiff_t loc_prev, ptrdiff_t loc_next, void *new_node); |
167 void cx_linked_list_prepend(void **begin, void **end, ptrdiff_t loc_prev, ptrdiff_t loc_next, void *new_node) |
|
168 __attribute__((__nonnull__(5))); |
164 |
169 |
165 /** |
170 /** |
166 * Removes a node from the linked list. |
171 * Removes a node from the linked list. |
167 * |
172 * |
168 * If the node to remove is the begin (resp. end) node of the list and if \p begin (resp. \p end) |
173 * If the node to remove is the begin (resp. end) node of the list and if \p begin (resp. \p end) |
179 * @param end a pointer to the end node pointer (optional) |
184 * @param end a pointer to the end node pointer (optional) |
180 * @param loc_prev the location of a \c prev pointer within your node struct (negative if your struct does not have one) |
185 * @param loc_prev the location of a \c prev pointer within your node struct (negative if your struct does not have one) |
181 * @param loc_next the location of a \c next pointer within your node struct (required) |
186 * @param loc_next the location of a \c next pointer within your node struct (required) |
182 * @param node the node to remove |
187 * @param node the node to remove |
183 */ |
188 */ |
184 void cx_linked_list_remove(void **begin, void **end, ptrdiff_t loc_prev, ptrdiff_t loc_next, void *node) |
189 void cx_linked_list_remove(void **begin, void **end, ptrdiff_t loc_prev, ptrdiff_t loc_next, void *node) |
185 __attribute__ ((nonnull(5))); |
190 __attribute__((__nonnull__(5))); |
186 |
191 |
187 |
192 |
188 /** |
193 /** |
189 * Determines the size of a linked list starting with \p node. |
194 * Determines the size of a linked list starting with \p node. |
190 * @param node the first node |
195 * @param node the first node |
223 * @param follow_ptr \c false if the pointer denoted by \p loc_data shall be passed to the \p cmp_func. |
228 * @param follow_ptr \c false if the pointer denoted by \p loc_data shall be passed to the \p cmp_func. |
224 * If \c true, the data at \p loc_data is dereferenced, assuming to be a pointer, and then passed to \p cmp_func. |
229 * If \c true, the data at \p loc_data is dereferenced, assuming to be a pointer, and then passed to \p cmp_func. |
225 * @param cmp_func the compare function defining the sort order |
230 * @param cmp_func the compare function defining the sort order |
226 */ |
231 */ |
227 void cx_linked_list_sort(void **begin, void **end, ptrdiff_t loc_prev, ptrdiff_t loc_next, |
232 void cx_linked_list_sort(void **begin, void **end, ptrdiff_t loc_prev, ptrdiff_t loc_next, |
228 ptrdiff_t loc_data, int follow_ptr, CxListComparator cmp_func); |
233 ptrdiff_t loc_data, int follow_ptr, CxListComparator cmp_func) |
|
234 __attribute__((__nonnull__(1, 7))); |
229 |
235 |
230 |
236 |
231 /** |
237 /** |
232 * Reverses the order of the nodes in a linked list. |
238 * Reverses the order of the nodes in a linked list. |
233 * |
239 * |
234 * @param begin a pointer to the begin node pointer (required) |
240 * @param begin a pointer to the begin node pointer (required) |
235 * @param end a pointer to the end node pointer (optional) |
241 * @param end a pointer to the end node pointer (optional) |
236 * @param loc_prev the location of a \c prev pointer within your node struct (negative if your struct does not have one) |
242 * @param loc_prev the location of a \c prev pointer within your node struct (negative if your struct does not have one) |
237 * @param loc_next the location of a \c next pointer within your node struct (required) |
243 * @param loc_next the location of a \c next pointer within your node struct (required) |
238 */ |
244 */ |
239 void cx_linked_list_reverse(void **begin, void **end, ptrdiff_t loc_prev, ptrdiff_t loc_next); |
245 void cx_linked_list_reverse(void **begin, void **end, ptrdiff_t loc_prev, ptrdiff_t loc_next) |
|
246 __attribute__((__nonnull__(1))); |
240 |
247 |
241 #ifdef __cplusplus |
248 #ifdef __cplusplus |
242 } /* extern "C" */ |
249 } /* extern "C" */ |
243 #endif |
250 #endif |
244 |
251 |