comparison: src/cx/list.h
src/cx/list.h
- changeset 464
- 7fafc95968fc
- parent 460
- e075009b33b7
- child 469
- 0458bff0b1cd
equal
deleted
inserted
replaced
| 463:92721c8f9db3 | 464:7fafc95968fc |
|---|---|
| 42 | 42 |
| 43 #ifdef __cplusplus | 43 #ifdef __cplusplus |
| 44 extern "C" { | 44 extern "C" { |
| 45 #endif | 45 #endif |
| 46 | 46 |
| 47 /** | |
| 48 * A comparator function comparing two list elements. | |
| 49 */ | |
| 47 typedef int(*CxListComparator)(void const *left, void const *right); | 50 typedef int(*CxListComparator)(void const *left, void const *right); |
| 48 | 51 |
| 52 /** | |
| 53 * Internal type for the list structure - use CxList instead. | |
| 54 */ | |
| 49 typedef struct cx_list_s cx_list_s; | 55 typedef struct cx_list_s cx_list_s; |
| 50 | 56 |
| 57 /** | |
| 58 * The class definition for arbitrary lists. | |
| 59 */ | |
| 51 typedef struct { | 60 typedef struct { |
| 61 /** | |
| 62 * Member function for adding an element. | |
| 63 */ | |
| 52 int (*add)(cx_list_s *list, void *elem); | 64 int (*add)(cx_list_s *list, void *elem); |
| 53 | 65 |
| 66 /** | |
| 67 * Member function for inserting an element. | |
| 68 */ | |
| 54 int (*insert)(cx_list_s *list, size_t index, void *elem); | 69 int (*insert)(cx_list_s *list, size_t index, void *elem); |
| 55 | 70 |
| 71 /** | |
| 72 * Member function for removing an element. | |
| 73 */ | |
| 56 int (*remove)(cx_list_s *list, size_t index); | 74 int (*remove)(cx_list_s *list, size_t index); |
| 57 | 75 |
| 76 /** | |
| 77 * Member function for element lookup. | |
| 78 */ | |
| 58 void *(*at)(cx_list_s *list, size_t index); | 79 void *(*at)(cx_list_s *list, size_t index); |
| 59 | 80 |
| 81 /** | |
| 82 * Member function for finding an element. | |
| 83 */ | |
| 60 size_t (*find)(cx_list_s *list, void *elem); | 84 size_t (*find)(cx_list_s *list, void *elem); |
| 61 | 85 |
| 86 /** | |
| 87 * Member function for retrieving the last element. | |
| 88 */ | |
| 62 void *(*last)(cx_list_s *list); | 89 void *(*last)(cx_list_s *list); |
| 63 } cx_list_class; | 90 } cx_list_class; |
| 64 | 91 |
| 92 /** | |
| 93 * Structure for holding the base data of a list. | |
| 94 */ | |
| 65 struct cx_list_s { | 95 struct cx_list_s { |
| 96 /** | |
| 97 * The list class definition. | |
| 98 */ | |
| 66 cx_list_class *cl; | 99 cx_list_class *cl; |
| 100 /** | |
| 101 * The allocator to use. | |
| 102 */ | |
| 67 CxAllocator allocator; | 103 CxAllocator allocator; |
| 104 /** | |
| 105 * The comparator function for the elements. | |
| 106 */ | |
| 68 CxListComparator cmpfunc; | 107 CxListComparator cmpfunc; |
| 108 /** | |
| 109 * The size of each element (payload only). | |
| 110 */ | |
| 69 size_t itemsize; | 111 size_t itemsize; |
| 112 /** | |
| 113 * The size of the list (number of currently stored elements). | |
| 114 */ | |
| 70 size_t size; | 115 size_t size; |
| 116 /** | |
| 117 * The capacity of the list (maximum number of elements). | |
| 118 */ | |
| 71 size_t capacity; | 119 size_t capacity; |
| 72 }; | 120 }; |
| 73 | 121 |
| 122 /** | |
| 123 * Common type for all list implementations. | |
| 124 */ | |
| 74 typedef cx_list_s *CxList; | 125 typedef cx_list_s *CxList; |
| 75 | 126 |
| 127 /** | |
| 128 * Adds an item to the end of the list. | |
| 129 * | |
| 130 * \remark It is implementation defined whether | |
| 131 * the contents of the element are copied or the | |
| 132 * pointer is added to the list. In the latter case | |
| 133 * the \c itemsize of the list SHALL be \c sizeof(void*). | |
| 134 * | |
| 135 * @param list the list | |
| 136 * @param elem a pointer to the element to add | |
| 137 * @return zero on success, non-zero on memory allocation failure | |
| 138 */ | |
| 76 int cxListAdd(CxList list, void *elem); | 139 int cxListAdd(CxList list, void *elem); |
| 77 | 140 |
| 141 /** | |
| 142 * Inserts an item at the specified index. | |
| 143 * | |
| 144 * If \p index equals the list \c size, this is effectively cxListAdd(). | |
| 145 * | |
| 146 * \remark It is implementation defined whether | |
| 147 * the contents of the element are copied or the | |
| 148 * pointer is added to the list. In the latter case | |
| 149 * the \c itemsize of the list SHALL be \c sizeof(void*). | |
| 150 * | |
| 151 * @param list the list | |
| 152 * @param index the index the element shall have | |
| 153 * @param elem a pointer to the element to add | |
| 154 * @return zero on success, non-zero on memory allocation failure | |
| 155 * or when the index is out of bounds | |
| 156 */ | |
| 78 int cxListInsert(CxList list, size_t index, void *elem); | 157 int cxListInsert(CxList list, size_t index, void *elem); |
| 79 | 158 |
| 159 /** | |
| 160 * Removes the element at the specified index. | |
| 161 * @param list the list | |
| 162 * @param index the index of the element | |
| 163 * @return zero on success, non-zero if the index is out of bounds | |
| 164 */ | |
| 80 int cxListRemove(CxList list, size_t index); | 165 int cxListRemove(CxList list, size_t index); |
| 81 | 166 |
| 167 /** | |
| 168 * Returns a pointer to the element at the specified index. | |
| 169 * | |
| 170 * @param list the list | |
| 171 * @param index the index of the element | |
| 172 * @return a pointer to the element or \c NULL if the index is out of bounds | |
| 173 */ | |
| 82 void *cxListAt(CxList list, size_t index); | 174 void *cxListAt(CxList list, size_t index); |
| 83 | 175 |
| 176 /** | |
| 177 * Returns the index of the first element that equals \p elem. | |
| 178 * | |
| 179 * Determining equality is performed by the list's comparator function. | |
| 180 * | |
| 181 * @param list the list | |
| 182 * @param elem the element to find | |
| 183 * @return the index of the element or \c (size+1) if the element is not found | |
| 184 */ | |
| 84 size_t cxListFind(CxList list, void *elem); | 185 size_t cxListFind(CxList list, void *elem); |
| 85 | 186 |
| 187 /** | |
| 188 * Returns a pointer to the last element of the list. | |
| 189 * | |
| 190 * This is effectively the same as cxListAt() with \c index=size-1, but | |
| 191 * this implementation may be more efficient depending on the list structure | |
| 192 * and the conrecte implementation of cxListAt(). | |
| 193 * | |
| 194 * @param list the list | |
| 195 * @return a pointer to the last element or \c NULL if the list is empty | |
| 196 */ | |
| 86 void *cxListLast(CxList list); | 197 void *cxListLast(CxList list); |
| 87 | 198 |
| 88 #ifdef __cplusplus | 199 #ifdef __cplusplus |
| 89 } /* extern "C" */ | 200 } /* extern "C" */ |
| 90 #endif | 201 #endif |
