ucx/cx/linked_list.h

changeset 818
bc782cca0759
parent 816
839fefbdedc7
equal deleted inserted replaced
817:22257f6d06a3 818:bc782cca0759
29 * \file linked_list.h 29 * \file linked_list.h
30 * \brief Linked list implementation. 30 * \brief Linked list implementation.
31 * \details Also provides several low-level functions for custom linked list implementations. 31 * \details Also provides several low-level functions for custom linked list implementations.
32 * \author Mike Becker 32 * \author Mike Becker
33 * \author Olaf Wintermann 33 * \author Olaf Wintermann
34 * \version 3.0
35 * \copyright 2-Clause BSD License 34 * \copyright 2-Clause BSD License
36 */ 35 */
37 36
38 #ifndef UCX_LINKED_LIST_H 37 #ifndef UCX_LINKED_LIST_H
39 #define UCX_LINKED_LIST_H 38 #define UCX_LINKED_LIST_H
44 #ifdef __cplusplus 43 #ifdef __cplusplus
45 extern "C" { 44 extern "C" {
46 #endif 45 #endif
47 46
48 /** 47 /**
49 * Set this flag to true, if you want to disable the use of SBO for 48 * The maximum item size that uses SBO swap instead of relinking.
50 * linked list swap operations. 49 */
51 */ 50 extern unsigned cx_linked_list_swap_sbo_size;
52 extern bool CX_DISABLE_LINKED_LIST_SWAP_SBO; 51
53 52 /**
54 /** 53 * Allocates a linked list for storing elements with \p elem_size bytes each.
55 * Allocates a linked list for storing elements with \p item_size bytes each. 54 *
56 * 55 * If \p elem_size is CX_STORE_POINTERS, the created list will be created as if
57 * If \p item_size is CX_STORE_POINTERS, the created list will be created as if 56 * cxListStorePointers() was called immediately after creation and the compare
58 * cxListStorePointers() was called immediately after creation. 57 * function will be automatically set to cx_cmp_ptr(), if none is given.
59 * 58 *
60 * @param allocator the allocator for allocating the list nodes 59 * @param allocator the allocator for allocating the list nodes
61 * (if \c NULL the cxDefaultAllocator will be used) 60 * (if \c NULL the cxDefaultAllocator will be used)
62 * @param comparator the comparator for the elements 61 * @param comparator the comparator for the elements
63 * (if \c NULL sort and find functions will not work) 62 * (if \c NULL, and the list is not storing pointers, sort and find
64 * @param item_size the size of each element in bytes 63 * functions will not work)
64 * @param elem_size the size of each element in bytes
65 * @return the created list 65 * @return the created list
66 */ 66 */
67 CxList *cxLinkedListCreate( 67 CxList *cxLinkedListCreate(
68 CxAllocator const *allocator, 68 CxAllocator const *allocator,
69 cx_compare_func comparator, 69 cx_compare_func comparator,
70 size_t item_size 70 size_t elem_size
71 ); 71 );
72 72
73 /** 73 /**
74 * Allocates a linked list for storing elements with \p item_size bytes each. 74 * Allocates a linked list for storing elements with \p elem_size bytes each.
75 * 75 *
76 * The list will use cxDefaultAllocator and no comparator function. If you want 76 * The list will use cxDefaultAllocator and no comparator function. If you want
77 * to call functions that need a comparator, you must either set one immediately 77 * to call functions that need a comparator, you must either set one immediately
78 * after list creation or use cxLinkedListCreate(). 78 * after list creation or use cxLinkedListCreate().
79 * 79 *
80 * If \p item_size is CX_STORE_POINTERS, the created list will be created as if 80 * If \p elem_size is CX_STORE_POINTERS, the created list will be created as if
81 * cxListStorePointers() was called immediately after creation. 81 * cxListStorePointers() was called immediately after creation and the compare
82 * 82 * function will be automatically set to cx_cmp_ptr().
83 * @param item_size the size of each element in bytes 83 *
84 * @param elem_size the size of each element in bytes
84 * @return the created list 85 * @return the created list
85 */ 86 */
86 #define cxLinkedListCreateSimple(item_size) \ 87 #define cxLinkedListCreateSimple(elem_size) \
87 cxLinkedListCreate(NULL, NULL, item_size) 88 cxLinkedListCreate(NULL, NULL, elem_size)
88 89
89 /** 90 /**
90 * Finds the node at a certain index. 91 * Finds the node at a certain index.
91 * 92 *
92 * This function can be used to start at an arbitrary position within the list. 93 * This function can be used to start at an arbitrary position within the list.
119 * @param cmp_func a compare function to compare \p elem against the node data 120 * @param cmp_func a compare function to compare \p elem against the node data
120 * @param elem a pointer to the element to find 121 * @param elem a pointer to the element to find
121 * @return the index of the element or a negative value if it could not be found 122 * @return the index of the element or a negative value if it could not be found
122 */ 123 */
123 ssize_t cx_linked_list_find( 124 ssize_t cx_linked_list_find(
125 void const *start,
126 ptrdiff_t loc_advance,
127 ptrdiff_t loc_data,
128 cx_compare_func cmp_func,
129 void const *elem
130 ) __attribute__((__nonnull__));
131
132 /**
133 * Finds the node containing an element within a linked list.
134 *
135 * @param result a pointer to the memory where the node pointer (or \c NULL if the element
136 * could not be found) shall be stored to
137 * @param start a pointer to the start node
138 * @param loc_advance the location of the pointer to advance
139 * @param loc_data the location of the \c data pointer within your node struct
140 * @param cmp_func a compare function to compare \p elem against the node data
141 * @param elem a pointer to the element to find
142 * @return the index of the element or a negative value if it could not be found
143 */
144 ssize_t cx_linked_list_find_node(
145 void **result,
124 void const *start, 146 void const *start,
125 ptrdiff_t loc_advance, 147 ptrdiff_t loc_advance,
126 ptrdiff_t loc_data, 148 ptrdiff_t loc_data,
127 cx_compare_func cmp_func, 149 cx_compare_func cmp_func,
128 void const *elem 150 void const *elem

mercurial