Sat, 26 Nov 2022 16:58:41 +0100
separate iterators and mutating iterators
Trade tons of code duplication for const-correctness.
1 /*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3 *
4 * Copyright 2021 Mike Becker, Olaf Wintermann All rights reserved.
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions are met:
8 *
9 * 1. Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * 2. Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26 * POSSIBILITY OF SUCH DAMAGE.
27 */
28 /**
29 * \file list.h
30 * \brief Interface for list implementations.
31 * \author Mike Becker
32 * \author Olaf Wintermann
33 * \version 3.0
34 * \copyright 2-Clause BSD License
35 */
37 #ifndef UCX_LIST_H
38 #define UCX_LIST_H
40 #include "common.h"
41 #include "allocator.h"
42 #include "iterator.h"
44 #ifdef __cplusplus
45 extern "C" {
46 #endif
48 /**
49 * A comparator function comparing two list elements.
50 */
51 typedef int(*CxListComparator)(
52 void const *left,
53 void const *right
54 );
56 /**
57 * List class type.
58 */
59 typedef struct cx_list_class_s cx_list_class;
61 /**
62 * Structure for holding the base data of a list.
63 */
64 struct cx_list_s {
65 /**
66 * The list class definition.
67 */
68 cx_list_class *cl;
69 /**
70 * The allocator to use.
71 */
72 CxAllocator const *allocator;
73 /**
74 * The comparator function for the elements.
75 */
76 CxListComparator cmpfunc;
77 /**
78 * The size of each element (payload only).
79 */
80 size_t itemsize;
81 /**
82 * The size of the list (number of currently stored elements).
83 */
84 size_t size;
85 /**
86 * The capacity of the list (maximum number of elements).
87 */
88 size_t capacity;
89 union {
90 /**
91 * An optional simple destructor for the list contents that admits the free() interface.
92 *
93 * @remark Set content_destructor_type to #CX_DESTRUCTOR_SIMPLE.
94 *
95 * @attention Read the documentation of the particular list implementation
96 * whether this destructor shall only destroy the contents or also free the memory.
97 */
98 cx_destructor_func simple_destructor;
99 /**
100 * An optional advanced destructor for the list contents providing additional data.
101 *
102 * @remark Set content_destructor_type to #CX_DESTRUCTOR_ADVANCED.
103 *
104 * @attention Read the documentation of the particular list implementation
105 * whether this destructor shall only destroy the contents or also free the memory.
106 */
107 cx_advanced_destructor advanced_destructor;
108 };
109 /**
110 * The type of destructor to use.
111 */
112 enum cx_destructor_type content_destructor_type;
113 };
115 /**
116 * The class definition for arbitrary lists.
117 */
118 struct cx_list_class_s {
119 /**
120 * Destructor function.
121 */
122 void (*destructor)(struct cx_list_s *list);
124 /**
125 * Member function for adding an element.
126 */
127 int (*add)(
128 struct cx_list_s *list,
129 void const *elem
130 );
132 /**
133 * Member function for adding multiple elements.
134 */
135 size_t (*add_array)(
136 struct cx_list_s *list,
137 void const *array,
138 size_t n
139 );
141 /**
142 * Member function for inserting an element.
143 */
144 int (*insert)(
145 struct cx_list_s *list,
146 size_t index,
147 void const *elem
148 );
150 /**
151 * Member function for inserting an element relative to an iterator position.
152 */
153 int (*insert_iter)(
154 struct cx_mut_iterator_s *iter,
155 void const *elem,
156 int prepend
157 );
159 /**
160 * Member function for removing an element.
161 */
162 int (*remove)(
163 struct cx_list_s *list,
164 size_t index
165 );
167 /**
168 * Member function for element lookup.
169 */
170 void *(*at)(
171 struct cx_list_s const *list,
172 size_t index
173 );
175 /**
176 * Member function for finding an element.
177 */
178 size_t (*find)(
179 struct cx_list_s const *list,
180 void const *elem
181 );
183 /**
184 * Member function for sorting the list in place.
185 */
186 void (*sort)(struct cx_list_s *list);
188 /**
189 * Member function for comparing this list to another list of the same type.
190 */
191 int (*compare)(
192 struct cx_list_s const *list,
193 struct cx_list_s const *other
194 );
196 /**
197 * Member function for reversing the order of the items.
198 */
199 void (*reverse)(struct cx_list_s *list);
201 /**
202 * Returns an iterator pointing to the specified index.
203 */
204 struct cx_iterator_s (*iterator)(
205 struct cx_list_s const *list,
206 size_t index
207 );
209 /**
210 * Returns a mutating iterator pointing to the specified index.
211 */
212 struct cx_mut_iterator_s (*mut_iterator)(
213 struct cx_list_s *list,
214 size_t index
215 );
216 };
218 /**
219 * Common type for all list implementations.
220 */
221 typedef struct cx_list_s CxList;
223 /**
224 * Adds an item to the end of the list.
225 *
226 * @param list the list
227 * @param elem a pointer to the element to add
228 * @return zero on success, non-zero on memory allocation failure
229 * @see cxListAddArray()
230 */
231 __attribute__((__nonnull__))
232 static inline int cxListAdd(
233 CxList *list,
234 void const *elem
235 ) {
236 return list->cl->add(list, elem);
237 }
239 /**
240 * Adds multiple items to the end of the list.
241 *
242 * This method is more efficient than invoking cxListAdd() multiple times.
243 *
244 * If there is not enough memory to add all elements, the returned value is
245 * less than \p n.
246 *
247 * @param list the list
248 * @param array a pointer to the elements to add
249 * @param n the number of elements to add
250 * @return the number of added elements
251 */
252 __attribute__((__nonnull__))
253 static inline size_t cxListAddArray(
254 CxList *list,
255 void const *array,
256 size_t n
257 ) {
258 return list->cl->add_array(list, array, n);
259 }
261 /**
262 * Inserts an item at the specified index.
263 *
264 * If \p index equals the list \c size, this is effectively cxListAdd().
265 *
266 * @param list the list
267 * @param index the index the element shall have
268 * @param elem a pointer to the element to add
269 * @return zero on success, non-zero on memory allocation failure
270 * or when the index is out of bounds
271 * @see cxListInsertAfter()
272 * @see cxListInsertBefore()
273 */
274 __attribute__((__nonnull__))
275 static inline int cxListInsert(
276 CxList *list,
277 size_t index,
278 void const *elem
279 ) {
280 return list->cl->insert(list, index, elem);
281 }
283 /**
284 * Inserts an element after the current location of the specified iterator.
285 *
286 * The used iterator remains operational, but all other active iterators should
287 * be considered invalidated.
288 *
289 * If \p iter is not a list iterator, the behavior is undefined.
290 * If \p iter is a past-the-end iterator, the new element gets appended to the list.
291 *
292 * @param iter an iterator
293 * @param elem the element to insert
294 * @return zero on success, non-zero on memory allocation failure
295 * @see cxListInsert()
296 * @see cxListInsertBefore()
297 */
298 __attribute__((__nonnull__))
299 static inline int cxListInsertAfter(
300 CxMutIterator *iter,
301 void const *elem
302 ) {
303 return ((struct cx_list_s *) iter->src_handle)->cl->insert_iter(iter, elem, 0);
304 }
306 /**
307 * Inserts an element before the current location of the specified iterator.
308 *
309 * The used iterator remains operational, but all other active iterators should
310 * be considered invalidated.
311 *
312 * If \p iter is not a list iterator, the behavior is undefined.
313 * If \p iter is a past-the-end iterator, the new element gets appended to the list.
314 *
315 * @param iter an iterator
316 * @param elem the element to insert
317 * @return zero on success, non-zero on memory allocation failure
318 * @see cxListInsert()
319 * @see cxListInsertAfter()
320 */
321 __attribute__((__nonnull__))
322 static inline int cxListInsertBefore(
323 CxMutIterator *iter,
324 void const *elem
325 ) {
326 return ((struct cx_list_s *) iter->src_handle)->cl->insert_iter(iter, elem, 1);
327 }
329 /**
330 * Removes the element at the specified index.
331 * @param list the list
332 * @param index the index of the element
333 * @return zero on success, non-zero if the index is out of bounds
334 */
335 __attribute__((__nonnull__))
336 static inline int cxListRemove(
337 CxList *list,
338 size_t index
339 ) {
340 return list->cl->remove(list, index);
341 }
343 /**
344 * Returns a pointer to the element at the specified index.
345 *
346 * @param list the list
347 * @param index the index of the element
348 * @return a pointer to the element or \c NULL if the index is out of bounds
349 */
350 __attribute__((__nonnull__))
351 static inline void *cxListAt(
352 CxList *list,
353 size_t index
354 ) {
355 return list->cl->at(list, index);
356 }
358 /**
359 * Returns an iterator pointing to the item at the specified index.
360 *
361 * The returned iterator is position-aware.
362 *
363 * If the index is out of range, a past-the-end iterator will be returned.
364 *
365 * @param list the list
366 * @param index the index where the iterator shall point at
367 * @return a new iterator
368 */
369 __attribute__((__nonnull__, __warn_unused_result__))
370 static inline CxIterator cxListIterator(
371 CxList const *list,
372 size_t index
373 ) {
374 return list->cl->iterator(list, index);
375 }
377 /**
378 * Returns a mutating iterator pointing to the item at the specified index.
379 *
380 * The returned iterator is position-aware.
381 *
382 * If the index is out of range, a past-the-end iterator will be returned.
383 *
384 * @param list the list
385 * @param index the index where the iterator shall point at
386 * @return a new iterator
387 */
388 __attribute__((__nonnull__, __warn_unused_result__))
389 static inline CxMutIterator cxListMutIterator(
390 CxList *list,
391 size_t index
392 ) {
393 return list->cl->mut_iterator(list, index);
394 }
396 /**
397 * Returns an iterator pointing to the first item of the list.
398 *
399 * The returned iterator is position-aware.
400 *
401 * If the list is empty, a past-the-end iterator will be returned.
402 *
403 * @param list the list
404 * @return a new iterator
405 */
406 __attribute__((__nonnull__, __warn_unused_result__))
407 static inline CxIterator cxListBegin(CxList const *list) {
408 return list->cl->iterator(list, 0);
409 }
411 /**
412 * Returns a mutating iterator pointing to the first item of the list.
413 *
414 * The returned iterator is position-aware.
415 *
416 * If the list is empty, a past-the-end iterator will be returned.
417 *
418 * @param list the list
419 * @return a new iterator
420 */
421 __attribute__((__nonnull__, __warn_unused_result__))
422 static inline CxMutIterator cxListBeginMut(CxList *list) {
423 return list->cl->mut_iterator(list, 0);
424 }
426 /**
427 * Returns the index of the first element that equals \p elem.
428 *
429 * Determining equality is performed by the list's comparator function.
430 *
431 * @param list the list
432 * @param elem the element to find
433 * @return the index of the element or \c (size+1) if the element is not found
434 */
435 __attribute__((__nonnull__))
436 static inline size_t cxListFind(
437 CxList const *list,
438 void const *elem
439 ) {
440 return list->cl->find(list, elem);
441 }
443 /**
444 * Sorts the list in place.
445 *
446 * \remark The underlying sort algorithm is implementation defined.
447 *
448 * @param list the list
449 */
450 __attribute__((__nonnull__))
451 static inline void cxListSort(CxList *list) {
452 list->cl->sort(list);
453 }
455 /**
456 * Reverses the order of the items.
457 *
458 * @param list the list
459 */
460 __attribute__((__nonnull__))
461 static inline void cxListReverse(CxList *list) {
462 list->cl->reverse(list);
463 }
465 /**
466 * Compares a list to another list of the same type.
467 *
468 * First, the list sizes are compared.
469 * If they match, the lists are compared element-wise.
470 *
471 * @param list the list
472 * @param other the list to compare to
473 * @return zero, if both lists are equal element wise,
474 * negative if the first list is smaller, positive if the first list is larger
475 */
476 __attribute__((__nonnull__))
477 int cxListCompare(
478 CxList const *list,
479 CxList const *other
480 );
482 /**
483 * Deallocates the memory of the specified list structure.
484 *
485 * Also calls content a destructor function, depending on the configuration
486 * in CxList.content_destructor_type.
487 *
488 * This function itself is a destructor function for the CxList.
489 *
490 * @param list the list which shall be destroyed
491 */
492 __attribute__((__nonnull__))
493 void cxListDestroy(CxList *list);
495 #ifdef __cplusplus
496 } // extern "C"
497 #endif
499 #endif // UCX_LIST_H