comparison: src/cx/linked_list.h
src/cx/linked_list.h
- changeset 478
- 599770bb6314
- parent 477
- 73a93c7a56ae
- child 480
- e3be53a3354f
equal
deleted
inserted
replaced
| 477:73a93c7a56ae | 478:599770bb6314 |
|---|---|
| 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 |
