Mon, 20 Mar 2023 19:09:08 +0100
add unit test for cxListClear + fix destructor functions not always invoked with the correct pointer
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 const *cl;
69 /**
70 * The actual implementation in case the list class is delegating.
71 */
72 cx_list_class const *climpl;
73 /**
74 * The allocator to use.
75 */
76 CxAllocator const *allocator;
77 /**
78 * The comparator function for the elements.
79 */
80 CxListComparator cmpfunc;
81 /**
82 * The size of each element (payload only).
83 */
84 size_t itemsize;
85 /**
86 * The size of the list (number of currently stored elements).
87 */
88 size_t size;
89 /**
90 * The capacity of the list (maximum number of elements).
91 */
92 size_t capacity;
93 union {
94 /**
95 * An optional simple destructor for the list contents that admits the free() interface.
96 *
97 * @remark Set content_destructor_type to #CX_DESTRUCTOR_SIMPLE.
98 *
99 * @attention Read the documentation of the particular list implementation
100 * whether this destructor shall only destroy the contents or also free the memory.
101 */
102 cx_destructor_func simple_destructor;
103 /**
104 * An optional advanced destructor for the list contents providing additional data.
105 *
106 * @remark Set content_destructor_type to #CX_DESTRUCTOR_ADVANCED.
107 *
108 * @attention Read the documentation of the particular list implementation
109 * whether this destructor shall only destroy the contents or also free the memory.
110 */
111 cx_advanced_destructor advanced_destructor;
112 };
113 /**
114 * The type of destructor to use.
115 */
116 enum cx_destructor_type content_destructor_type;
117 };
119 /**
120 * The class definition for arbitrary lists.
121 */
122 struct cx_list_class_s {
123 /**
124 * Destructor function.
125 */
126 void (*destructor)(struct cx_list_s *list);
128 /**
129 * Member function for inserting a single elements.
130 * Implementors SHOULD see to performant implementations for corner cases.
131 */
132 int (*insert_element)(
133 struct cx_list_s *list,
134 size_t index,
135 void const *data
136 );
138 /**
139 * Member function for inserting multiple elements.
140 * Implementors SHOULD see to performant implementations for corner cases.
141 */
142 size_t (*insert_array)(
143 struct cx_list_s *list,
144 size_t index,
145 void const *data,
146 size_t n
147 );
149 /**
150 * Member function for inserting an element relative to an iterator position.
151 */
152 int (*insert_iter)(
153 struct cx_mut_iterator_s *iter,
154 void const *elem,
155 int prepend
156 );
158 /**
159 * Member function for removing an element.
160 */
161 int (*remove)(
162 struct cx_list_s *list,
163 size_t index
164 );
166 /**
167 * Member function for removing all elements.
168 */
169 void (*clear)(struct cx_list_s *list);
171 /**
172 * Member function for swapping two elements.
173 */
174 int (*swap)(
175 struct cx_list_s *list,
176 size_t i,
177 size_t j
178 );
180 /**
181 * Member function for element lookup.
182 */
183 void *(*at)(
184 struct cx_list_s const *list,
185 size_t index
186 );
188 /**
189 * Member function for finding an element.
190 */
191 size_t (*find)(
192 struct cx_list_s const *list,
193 void const *elem
194 );
196 /**
197 * Member function for sorting the list in place.
198 */
199 void (*sort)(struct cx_list_s *list);
201 /**
202 * Member function for comparing this list to another list of the same type.
203 */
204 int (*compare)(
205 struct cx_list_s const *list,
206 struct cx_list_s const *other
207 );
209 /**
210 * Member function for reversing the order of the items.
211 */
212 void (*reverse)(struct cx_list_s *list);
214 /**
215 * Member function for returning an iterator pointing to the specified index.
216 */
217 struct cx_iterator_s (*iterator)(
218 struct cx_list_s const *list,
219 size_t index,
220 bool backward
221 );
222 };
224 /**
225 * Common type for all list implementations.
226 */
227 typedef struct cx_list_s CxList;
229 /**
230 * Invokes the configured destructor function for a specific element.
231 *
232 * Usually only used by list implementations. There should be no need
233 * to invoke this function manually.
234 *
235 * @param list the list
236 * @param elem the element
237 */
238 __attribute__((__nonnull__))
239 void cx_list_invoke_destructor(
240 struct cx_list_s const *list,
241 void *elem
242 );
244 /**
245 * Invokes the simple destructor function for a specific element.
246 *
247 * Usually only used by list implementations. There should be no need
248 * to invoke this function manually.
249 *
250 * @param list the list
251 * @param elem the element
252 */
253 __attribute__((__nonnull__))
254 void cx_list_invoke_simple_destructor(
255 struct cx_list_s const *list,
256 void *elem
257 );
259 /**
260 * Invokes the advanced destructor function for a specific element.
261 *
262 * Usually only used by list implementations. There should be no need
263 * to invoke this function manually.
264 *
265 * @param list the list
266 * @param elem the element
267 */
268 __attribute__((__nonnull__))
269 void cx_list_invoke_advanced_destructor(
270 struct cx_list_s const *list,
271 void *elem
272 );
274 /**
275 * Advises the list to store copies of the objects (default mode of operation).
276 *
277 * Retrieving objects from this list will yield pointers to the copies stored
278 * within this list.
279 *
280 * @param list the list
281 * @see cxListStorePointers()
282 */
283 __attribute__((__nonnull__))
284 void cxListStoreObjects(CxList *list);
286 /**
287 * Advises the list to only store pointers to the objects.
288 *
289 * Retrieving objects from this list will yield the original pointers stored.
290 *
291 * @note This function forcibly sets the element size to the size of a pointer.
292 * Invoking this function on a non-empty list that already stores copies of
293 * objects is undefined.
294 *
295 * @param list the list
296 * @see cxListStoreObjects()
297 */
298 __attribute__((__nonnull__))
299 void cxListStorePointers(CxList *list);
301 /**
302 * Returns true, if this list is storing pointers instead of the actual data.
303 *
304 * @param list
305 * @return
306 * @see cxListStorePointers()
307 */
308 __attribute__((__nonnull__))
309 bool cxListIsStoringPointers(CxList const *list);
311 /**
312 * Adds an item to the end of the list.
313 *
314 * @param list the list
315 * @param elem a pointer to the element to add
316 * @return zero on success, non-zero on memory allocation failure
317 * @see cxListAddArray()
318 */
319 __attribute__((__nonnull__))
320 static inline int cxListAdd(
321 CxList *list,
322 void const *elem
323 ) {
324 return list->cl->insert_element(list, list->size, elem);
325 }
327 /**
328 * Adds multiple items to the end of the list.
329 *
330 * This method is more efficient than invoking cxListAdd() multiple times.
331 *
332 * If there is not enough memory to add all elements, the returned value is
333 * less than \p n.
334 *
335 * If this list is storing pointers instead of objects \p array is expected to
336 * be an array of pointers.
337 *
338 * @param list the list
339 * @param array a pointer to the elements to add
340 * @param n the number of elements to add
341 * @return the number of added elements
342 */
343 __attribute__((__nonnull__))
344 static inline size_t cxListAddArray(
345 CxList *list,
346 void const *array,
347 size_t n
348 ) {
349 return list->cl->insert_array(list, list->size, array, n);
350 }
352 /**
353 * Inserts an item at the specified index.
354 *
355 * If \p index equals the list \c size, this is effectively cxListAdd().
356 *
357 * @param list the list
358 * @param index the index the element shall have
359 * @param elem a pointer to the element to add
360 * @return zero on success, non-zero on memory allocation failure
361 * or when the index is out of bounds
362 * @see cxListInsertAfter()
363 * @see cxListInsertBefore()
364 */
365 __attribute__((__nonnull__))
366 static inline int cxListInsert(
367 CxList *list,
368 size_t index,
369 void const *elem
370 ) {
371 return list->cl->insert_element(list, index, elem);
372 }
374 /**
375 * Inserts multiple items to the list at the specified index.
376 * If \p index equals the list size, this is effectively cxListAddArray().
377 *
378 * This method is usually more efficient than invoking cxListInsert()
379 * multiple times.
380 *
381 * If there is not enough memory to add all elements, the returned value is
382 * less than \p n.
383 *
384 * If this list is storing pointers instead of objects \p array is expected to
385 * be an array of pointers.
386 *
387 * @param list the list
388 * @param index the index where to add the elements
389 * @param array a pointer to the elements to add
390 * @param n the number of elements to add
391 * @return the number of added elements
392 */
393 __attribute__((__nonnull__))
394 static inline size_t cxListInsertArray(
395 CxList *list,
396 size_t index,
397 void const *array,
398 size_t n
399 ) {
400 return list->cl->insert_array(list, index, array, n);
401 }
403 /**
404 * Inserts an element after the current location of the specified iterator.
405 *
406 * The used iterator remains operational, but all other active iterators should
407 * be considered invalidated.
408 *
409 * If \p iter is not a list iterator, the behavior is undefined.
410 * If \p iter is a past-the-end iterator, the new element gets appended to the list.
411 *
412 * @param iter an iterator
413 * @param elem the element to insert
414 * @return zero on success, non-zero on memory allocation failure
415 * @see cxListInsert()
416 * @see cxListInsertBefore()
417 */
418 __attribute__((__nonnull__))
419 static inline int cxListInsertAfter(
420 CxMutIterator *iter,
421 void const *elem
422 ) {
423 return ((struct cx_list_s *) iter->src_handle)->cl->insert_iter(iter, elem, 0);
424 }
426 /**
427 * Inserts an element before the current location of the specified iterator.
428 *
429 * The used iterator remains operational, but all other active iterators should
430 * be considered invalidated.
431 *
432 * If \p iter is not a list iterator, the behavior is undefined.
433 * If \p iter is a past-the-end iterator, the new element gets appended to the list.
434 *
435 * @param iter an iterator
436 * @param elem the element to insert
437 * @return zero on success, non-zero on memory allocation failure
438 * @see cxListInsert()
439 * @see cxListInsertAfter()
440 */
441 __attribute__((__nonnull__))
442 static inline int cxListInsertBefore(
443 CxMutIterator *iter,
444 void const *elem
445 ) {
446 return ((struct cx_list_s *) iter->src_handle)->cl->insert_iter(iter, elem, 1);
447 }
449 /**
450 * Removes the element at the specified index.
451 *
452 * If an element destructor function is specified, it is called before
453 * removing the element.
454 *
455 * @param list the list
456 * @param index the index of the element
457 * @return zero on success, non-zero if the index is out of bounds
458 */
459 __attribute__((__nonnull__))
460 static inline int cxListRemove(
461 CxList *list,
462 size_t index
463 ) {
464 return list->cl->remove(list, index);
465 }
467 /**
468 * Removes all elements from this list.
469 *
470 * If an element destructor function is specified, it is called for each
471 * element before removing them.
472 *
473 * @param list the list
474 */
475 __attribute__((__nonnull__))
476 static inline void cxListClear(CxList *list) {
477 list->cl->clear(list);
478 }
480 /**
481 * Swaps two items in the list.
482 *
483 * Implementations should only allocate temporary memory for the swap, if
484 * it is necessary.
485 *
486 * @param list the list
487 * @param i the index of the first element
488 * @param j the index of the second element
489 * @return zero on success, non-zero if one of the indices is out of bounds
490 */
491 __attribute__((__nonnull__))
492 static inline int cxListSwap(
493 CxList *list,
494 size_t i,
495 size_t j
496 ) {
497 return list->cl->swap(list, i, j);
498 }
500 /**
501 * Returns a pointer to the element at the specified index.
502 *
503 * @param list the list
504 * @param index the index of the element
505 * @return a pointer to the element or \c NULL if the index is out of bounds
506 */
507 __attribute__((__nonnull__))
508 static inline void *cxListAt(
509 CxList *list,
510 size_t index
511 ) {
512 return list->cl->at(list, index);
513 }
515 /**
516 * Returns an iterator pointing to the item at the specified index.
517 *
518 * The returned iterator is position-aware.
519 *
520 * If the index is out of range, a past-the-end iterator will be returned.
521 *
522 * @param list the list
523 * @param index the index where the iterator shall point at
524 * @return a new iterator
525 */
526 __attribute__((__nonnull__, __warn_unused_result__))
527 static inline CxIterator cxListIteratorAt(
528 CxList const *list,
529 size_t index
530 ) {
531 return list->cl->iterator(list, index, false);
532 }
534 /**
535 * Returns a backwards iterator pointing to the item at the specified index.
536 *
537 * The returned iterator is position-aware.
538 *
539 * If the index is out of range, a past-the-end iterator will be returned.
540 *
541 * @param list the list
542 * @param index the index where the iterator shall point at
543 * @return a new iterator
544 */
545 __attribute__((__nonnull__, __warn_unused_result__))
546 static inline CxIterator cxListBackwardsIteratorAt(
547 CxList const *list,
548 size_t index
549 ) {
550 return list->cl->iterator(list, index, true);
551 }
553 /**
554 * Returns a mutating iterator pointing to the item at the specified index.
555 *
556 * The returned iterator is position-aware.
557 *
558 * If the index is out of range, a past-the-end iterator will be returned.
559 *
560 * @param list the list
561 * @param index the index where the iterator shall point at
562 * @return a new iterator
563 */
564 __attribute__((__nonnull__, __warn_unused_result__))
565 CxMutIterator cxListMutIteratorAt(
566 CxList *list,
567 size_t index
568 );
570 /**
571 * Returns a mutating backwards iterator pointing to the item at the
572 * specified index.
573 *
574 * The returned iterator is position-aware.
575 *
576 * If the index is out of range, a past-the-end iterator will be returned.
577 *
578 * @param list the list
579 * @param index the index where the iterator shall point at
580 * @return a new iterator
581 */
582 __attribute__((__nonnull__, __warn_unused_result__))
583 CxMutIterator cxListMutBackwardsIteratorAt(
584 CxList *list,
585 size_t index
586 );
588 /**
589 * Returns an iterator pointing to the first item of the list.
590 *
591 * The returned iterator is position-aware.
592 *
593 * If the list is empty, a past-the-end iterator will be returned.
594 *
595 * @param list the list
596 * @return a new iterator
597 */
598 __attribute__((__nonnull__, __warn_unused_result__))
599 static inline CxIterator cxListIterator(CxList const *list) {
600 return list->cl->iterator(list, 0, false);
601 }
603 /**
604 * Returns a mutating iterator pointing to the first item of the list.
605 *
606 * The returned iterator is position-aware.
607 *
608 * If the list is empty, a past-the-end iterator will be returned.
609 *
610 * @param list the list
611 * @return a new iterator
612 */
613 __attribute__((__nonnull__, __warn_unused_result__))
614 static inline CxMutIterator cxListMutIterator(CxList *list) {
615 return cxListMutIteratorAt(list, 0);
616 }
619 /**
620 * Returns a backwards iterator pointing to the last item of the list.
621 *
622 * The returned iterator is position-aware.
623 *
624 * If the list is empty, a past-the-end iterator will be returned.
625 *
626 * @param list the list
627 * @return a new iterator
628 */
629 __attribute__((__nonnull__, __warn_unused_result__))
630 static inline CxIterator cxListBackwardsIterator(CxList const *list) {
631 return list->cl->iterator(list, list->size - 1, true);
632 }
634 /**
635 * Returns a mutating backwards iterator pointing to the last item of the list.
636 *
637 * The returned iterator is position-aware.
638 *
639 * If the list is empty, a past-the-end iterator will be returned.
640 *
641 * @param list the list
642 * @return a new iterator
643 */
644 __attribute__((__nonnull__, __warn_unused_result__))
645 static inline CxMutIterator cxListMutBackwardsIterator(CxList *list) {
646 return cxListMutBackwardsIteratorAt(list, list->size - 1);
647 }
649 /**
650 * Returns the index of the first element that equals \p elem.
651 *
652 * Determining equality is performed by the list's comparator function.
653 *
654 * @param list the list
655 * @param elem the element to find
656 * @return the index of the element or \c (size+1) if the element is not found
657 */
658 __attribute__((__nonnull__))
659 static inline size_t cxListFind(
660 CxList const *list,
661 void const *elem
662 ) {
663 return list->cl->find(list, elem);
664 }
666 /**
667 * Sorts the list in place.
668 *
669 * \remark The underlying sort algorithm is implementation defined.
670 *
671 * @param list the list
672 */
673 __attribute__((__nonnull__))
674 static inline void cxListSort(CxList *list) {
675 list->cl->sort(list);
676 }
678 /**
679 * Reverses the order of the items.
680 *
681 * @param list the list
682 */
683 __attribute__((__nonnull__))
684 static inline void cxListReverse(CxList *list) {
685 list->cl->reverse(list);
686 }
688 /**
689 * Compares a list to another list of the same type.
690 *
691 * First, the list sizes are compared.
692 * If they match, the lists are compared element-wise.
693 *
694 * @param list the list
695 * @param other the list to compare to
696 * @return zero, if both lists are equal element wise,
697 * negative if the first list is smaller, positive if the first list is larger
698 */
699 __attribute__((__nonnull__))
700 int cxListCompare(
701 CxList const *list,
702 CxList const *other
703 );
705 /**
706 * Deallocates the memory of the specified list structure.
707 *
708 * Also calls content a destructor function, depending on the configuration
709 * in CxList.content_destructor_type.
710 *
711 * This function itself is a destructor function for the CxList.
712 *
713 * @param list the list which shall be destroyed
714 */
715 __attribute__((__nonnull__))
716 void cxListDestroy(CxList *list);
718 #ifdef __cplusplus
719 } // extern "C"
720 #endif
722 #endif // UCX_LIST_H