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 * @copyright 2-Clause BSD License
34 */
35
36 #ifndef UCX_LIST_H
37 #define UCX_LIST_H
38
39 #include "common.h"
40 #include "collection.h"
41
42 #ifdef __cplusplus
43 extern "C" {
44 #endif
45
46 /**
47 * List class type.
48 */
49 typedef struct cx_list_class_s cx_list_class;
50
51 /**
52 * Structure for holding the base data of a list.
53 */
54 struct cx_list_s {
55 /**
56 * Common members for collections.
57 */
58 CX_COLLECTION_BASE;
59 /**
60 * The list class definition.
61 */
62 const cx_list_class *cl;
63 /**
64 * The actual implementation in case the list class is delegating.
65 */
66 const cx_list_class *climpl;
67 };
68
69 /**
70 * The class definition for arbitrary lists.
71 */
72 struct cx_list_class_s {
73 /**
74 * Destructor function.
75 *
76 * Implementations SHALL invoke the content destructor functions if provided
77 * and SHALL deallocate the entire list memory.
78 */
79 void (*deallocate)(struct cx_list_s *list);
80
81 /**
82 * Member function for inserting a single element.
83 * Implementors SHOULD see to performant implementations for corner cases.
84 */
85 int (*insert_element)(
86 struct cx_list_s *list,
87 size_t index,
88 const void *data
89 );
90
91 /**
92 * Member function for inserting multiple elements.
93 * Implementors SHOULD see to performant implementations for corner cases.
94 *
95 * @see cx_list_default_insert_array()
96 */
97 size_t (*insert_array)(
98 struct cx_list_s *list,
99 size_t index,
100 const void *data,
101 size_t n
102 );
103
104 /**
105 * Member function for inserting sorted elements into a sorted list.
106 *
107 * @see cx_list_default_insert_sorted()
108 */
109 size_t (*insert_sorted)(
110 struct cx_list_s *list,
111 const void *sorted_data,
112 size_t n
113 );
114
115 /**
116 * Member function for inserting an element relative to an iterator position.
117 */
118 int (*insert_iter)(
119 struct cx_iterator_s *iter,
120 const void *elem,
121 int prepend
122 );
123
124 /**
125 * Member function for removing elements.
126 *
127 * Implementations SHALL check if @p targetbuf is set and copy the elements
128 * to the buffer without invoking any destructor.
129 * When @p targetbuf is not set, the destructors SHALL be invoked.
130 *
131 * The function SHALL return the actual number of elements removed, which
132 * might be lower than @p num when going out of bounds.
133 */
134 size_t (*remove)(
135 struct cx_list_s *list,
136 size_t index,
137 size_t num,
138 void *targetbuf
139 );
140
141 /**
142 * Member function for removing all elements.
143 */
144 void (*clear)(struct cx_list_s *list);
145
146 /**
147 * Member function for swapping two elements.
148 *
149 * @see cx_list_default_swap()
150 */
151 int (*swap)(
152 struct cx_list_s *list,
153 size_t i,
154 size_t j
155 );
156
157 /**
158 * Member function for element lookup.
159 */
160 void *(*at)(
161 const struct cx_list_s *list,
162 size_t index
163 );
164
165 /**
166 * Member function for finding and optionally removing an element.
167 */
168 ssize_t (*find_remove)(
169 struct cx_list_s *list,
170 const void *elem,
171 bool remove
172 );
173
174 /**
175 * Member function for sorting the list.
176 *
177 * @see cx_list_default_sort()
178 */
179 void (*sort)(struct cx_list_s *list);
180
181 /**
182 * Optional member function for comparing this list
183 * to another list of the same type.
184 * If set to @c NULL, comparison won't be optimized.
185 */
186 cx_attr_nonnull
187 int (*compare)(
188 const struct cx_list_s *list,
189 const struct cx_list_s *other
190 );
191
192 /**
193 * Member function for reversing the order of the items.
194 */
195 void (*reverse)(struct cx_list_s *list);
196
197 /**
198 * Member function for returning an iterator pointing to the specified index.
199 */
200 struct cx_iterator_s (*iterator)(
201 const struct cx_list_s *list,
202 size_t index,
203 bool backward
204 );
205 };
206
207 /**
208 * Default implementation of an array insert.
209 *
210 * This function uses the element insert function for each element of the array.
211 *
212 * Use this in your own list class if you do not want to implement an optimized
213 * version for your list.
214 *
215 * @param list the list
216 * @param index the index where to insert the data
217 * @param data a pointer to the array of data to insert
218 * @param n the number of elements to insert
219 * @return the number of elements actually inserted
220 */
221 cx_attr_nonnull
222 size_t cx_list_default_insert_array(
223 struct cx_list_s *list,
224 size_t index,
225 const void *data,
226 size_t n
227 );
228
229 /**
230 * Default implementation of a sorted insert.
231 *
232 * This function uses the array insert function to insert consecutive groups
233 * of sorted data.
234 *
235 * The source data @em must already be sorted wrt. the list's compare function.
236 *
237 * Use this in your own list class if you do not want to implement an optimized
238 * version for your list.
239 *
240 * @param list the list
241 * @param sorted_data a pointer to the array of pre-sorted data to insert
242 * @param n the number of elements to insert
243 * @return the number of elements actually inserted
244 */
245 cx_attr_nonnull
246 size_t cx_list_default_insert_sorted(
247 struct cx_list_s *list,
248 const void *sorted_data,
249 size_t n
250 );
251
252 /**
253 * Default unoptimized sort implementation.
254 *
255 * This function will copy all data to an array, sort the array with standard
256 * qsort, and then copy the data back to the list memory.
257 *
258 * Use this in your own list class if you do not want to implement an optimized
259 * version for your list.
260 *
261 * @param list the list that shall be sorted
262 */
263 cx_attr_nonnull
264 void cx_list_default_sort(struct cx_list_s *list);
265
266 /**
267 * Default unoptimized swap implementation.
268 *
269 * Use this in your own list class if you do not want to implement an optimized
270 * version for your list.
271 *
272 * @param list the list in which to swap
273 * @param i index of one element
274 * @param j index of the other element
275 * @retval zero success
276 * @retval non-zero when indices are out of bounds or memory
277 * allocation for the temporary buffer fails
278 */
279 cx_attr_nonnull
280 int cx_list_default_swap(struct cx_list_s *list, size_t i, size_t j);
281
282 /**
283 * Common type for all list implementations.
284 */
285 typedef struct cx_list_s CxList;
286
287 /**
288 * Advises the list to store copies of the objects (default mode of operation).
289 *
290 * Retrieving objects from this list will yield pointers to the copies stored
291 * within this list.
292 *
293 * @param list the list
294 * @see cxListStorePointers()
295 */
296 cx_attr_nonnull
297 void cxListStoreObjects(CxList *list);
298
299 /**
300 * Advises the list to only store pointers to the objects.
301 *
302 * Retrieving objects from this list will yield the original pointers stored.
303 *
304 * @note This function forcibly sets the element size to the size of a pointer.
305 * Invoking this function on a non-empty list that already stores copies of
306 * objects is undefined.
307 *
308 * @param list the list
309 * @see cxListStoreObjects()
310 */
311 cx_attr_nonnull
312 void cxListStorePointers(CxList *list);
313
314 /**
315 * Returns true, if this list is storing pointers instead of the actual data.
316 *
317 * @param list
318 * @return true, if this list is storing pointers
319 * @see cxListStorePointers()
320 */
321 cx_attr_nonnull
322 static inline bool cxListIsStoringPointers(const CxList *list) {
323 return list->collection.store_pointer;
324 }
325
326 /**
327 * Returns the number of elements currently stored in the list.
328 *
329 * @param list the list
330 * @return the number of currently stored elements
331 */
332 cx_attr_nonnull
333 static inline size_t cxListSize(const CxList *list) {
334 return list->collection.size;
335 }
336
337 /**
338 * Adds an item to the end of the list.
339 *
340 * @param list the list
341 * @param elem a pointer to the element to add
342 * @retval zero success
343 * @retval non-zero memory allocation failure
344 * @see cxListAddArray()
345 */
346 cx_attr_nonnull
347 static inline int cxListAdd(
348 CxList *list,
349 const void *elem
350 ) {
351 return list->cl->insert_element(list, list->collection.size, elem);
352 }
353
354 /**
355 * Adds multiple items to the end of the list.
356 *
357 * This method is more efficient than invoking cxListAdd() multiple times.
358 *
359 * If there is not enough memory to add all elements, the returned value is
360 * less than @p n.
361 *
362 * If this list is storing pointers instead of objects @p array is expected to
363 * be an array of pointers.
364 *
365 * @param list the list
366 * @param array a pointer to the elements to add
367 * @param n the number of elements to add
368 * @return the number of added elements
369 */
370 cx_attr_nonnull
371 static inline size_t cxListAddArray(
372 CxList *list,
373 const void *array,
374 size_t n
375 ) {
376 return list->cl->insert_array(list, list->collection.size, array, n);
377 }
378
379 /**
380 * Inserts an item at the specified index.
381 *
382 * If @p index equals the list @c size, this is effectively cxListAdd().
383 *
384 * @param list the list
385 * @param index the index the element shall have
386 * @param elem a pointer to the element to add
387 * @retval zero success
388 * @retval non-zero memory allocation failure or the index is out of bounds
389 * @see cxListInsertAfter()
390 * @see cxListInsertBefore()
391 */
392 cx_attr_nonnull
393 static inline int cxListInsert(
394 CxList *list,
395 size_t index,
396 const void *elem
397 ) {
398 return list->cl->insert_element(list, index, elem);
399 }
400
401 /**
402 * Inserts an item into a sorted list.
403 *
404 * @param list the list
405 * @param elem a pointer to the element to add
406 * @retval zero success
407 * @retval non-zero memory allocation failure
408 */
409 cx_attr_nonnull
410 static inline int cxListInsertSorted(
411 CxList *list,
412 const void *elem
413 ) {
414 const void *data = list->collection.store_pointer ? &elem : elem;
415 return list->cl->insert_sorted(list, data, 1) == 0;
416 }
417
418 /**
419 * Inserts multiple items to the list at the specified index.
420 * If @p index equals the list size, this is effectively cxListAddArray().
421 *
422 * This method is usually more efficient than invoking cxListInsert()
423 * multiple times.
424 *
425 * If there is not enough memory to add all elements, the returned value is
426 * less than @p n.
427 *
428 * If this list is storing pointers instead of objects @p array is expected to
429 * be an array of pointers.
430 *
431 * @param list the list
432 * @param index the index where to add the elements
433 * @param array a pointer to the elements to add
434 * @param n the number of elements to add
435 * @return the number of added elements
436 */
437 cx_attr_nonnull
438 static inline size_t cxListInsertArray(
439 CxList *list,
440 size_t index,
441 const void *array,
442 size_t n
443 ) {
444 return list->cl->insert_array(list, index, array, n);
445 }
446
447 /**
448 * Inserts a sorted array into a sorted list.
449 *
450 * This method is usually more efficient than inserting each element separately,
451 * because consecutive chunks of sorted data are inserted in one pass.
452 *
453 * If there is not enough memory to add all elements, the returned value is
454 * less than @p n.
455 *
456 * If this list is storing pointers instead of objects @p array is expected to
457 * be an array of pointers.
458 *
459 * @param list the list
460 * @param array a pointer to the elements to add
461 * @param n the number of elements to add
462 * @return the number of added elements
463 */
464 cx_attr_nonnull
465 static inline size_t cxListInsertSortedArray(
466 CxList *list,
467 const void *array,
468 size_t n
469 ) {
470 return list->cl->insert_sorted(list, array, n);
471 }
472
473 /**
474 * Inserts an element after the current location of the specified iterator.
475 *
476 * The used iterator remains operational, but all other active iterators should
477 * be considered invalidated.
478 *
479 * If @p iter is not a list iterator, the behavior is undefined.
480 * If @p iter is a past-the-end iterator, the new element gets appended to the list.
481 *
482 * @param iter an iterator
483 * @param elem the element to insert
484 * @retval zero success
485 * @retval non-zero memory allocation failure
486 * @see cxListInsert()
487 * @see cxListInsertBefore()
488 */
489 cx_attr_nonnull
490 static inline int cxListInsertAfter(
491 CxIterator *iter,
492 const void *elem
493 ) {
494 return ((struct cx_list_s *) iter->src_handle.m)->cl->insert_iter(iter, elem, 0);
495 }
496
497 /**
498 * Inserts an element before the current location of the specified iterator.
499 *
500 * The used iterator remains operational, but all other active iterators should
501 * be considered invalidated.
502 *
503 * If @p iter is not a list iterator, the behavior is undefined.
504 * If @p iter is a past-the-end iterator, the new element gets appended to the list.
505 *
506 * @param iter an iterator
507 * @param elem the element to insert
508 * @retval zero success
509 * @retval non-zero memory allocation failure
510 * @see cxListInsert()
511 * @see cxListInsertAfter()
512 */
513 cx_attr_nonnull
514 static inline int cxListInsertBefore(
515 CxIterator *iter,
516 const void *elem
517 ) {
518 return ((struct cx_list_s *) iter->src_handle.m)->cl->insert_iter(iter, elem, 1);
519 }
520
521 /**
522 * Removes the element at the specified index.
523 *
524 * If an element destructor function is specified, it is called before
525 * removing the element.
526 *
527 * @param list the list
528 * @param index the index of the element
529 * @retval zero success
530 * @retval non-zero index out of bounds
531 */
532 cx_attr_nonnull
533 static inline int cxListRemove(
534 CxList *list,
535 size_t index
536 ) {
537 return list->cl->remove(list, index, 1, NULL) == 0;
538 }
539
540 /**
541 * Removes and returns the element at the specified index.
542 *
543 * No destructor is called and instead the element is copied to the
544 * @p targetbuf which MUST be large enough to hold the removed element.
545 *
546 * @param list the list
547 * @param index the index of the element
548 * @param targetbuf a buffer where to copy the element
549 * @retval zero success
550 * @retval non-zero index out of bounds
551 */
552 cx_attr_nonnull
553 cx_attr_access_w(3)
554 static inline int cxListRemoveAndGet(
555 CxList *list,
556 size_t index,
557 void *targetbuf
558 ) {
559 return list->cl->remove(list, index, 1, targetbuf) == 0;
560 }
561
562 /**
563 * Removes multiple element starting at the specified index.
564 *
565 * If an element destructor function is specified, it is called for each
566 * element. It is guaranteed that the destructor is called before removing
567 * the element, however, due to possible optimizations it is neither guaranteed
568 * that the destructors are invoked for all elements before starting to remove
569 * them, nor that the element is removed immediately after the destructor call
570 * before proceeding to the next element.
571 *
572 * @param list the list
573 * @param index the index of the element
574 * @param num the number of elements to remove
575 * @return the actual number of removed elements
576 */
577 cx_attr_nonnull
578 static inline size_t cxListRemoveArray(
579 CxList *list,
580 size_t index,
581 size_t num
582 ) {
583 return list->cl->remove(list, index, num, NULL);
584 }
585
586 /**
587 * Removes and returns multiple element starting at the specified index.
588 *
589 * No destructor is called and instead the elements are copied to the
590 * @p targetbuf which MUST be large enough to hold all removed elements.
591 *
592 * @param list the list
593 * @param index the index of the element
594 * @param num the number of elements to remove
595 * @param targetbuf a buffer where to copy the elements
596 * @return the actual number of removed elements
597 */
598 cx_attr_nonnull
599 cx_attr_access_w(4)
600 static inline size_t cxListRemoveArrayAndGet(
601 CxList *list,
602 size_t index,
603 size_t num,
604 void *targetbuf
605 ) {
606 return list->cl->remove(list, index, num, targetbuf);
607 }
608
609 /**
610 * Removes all elements from this list.
611 *
612 * If element destructor functions are specified, they are called for each
613 * element before removing them.
614 *
615 * @param list the list
616 */
617 cx_attr_nonnull
618 static inline void cxListClear(CxList *list) {
619 list->cl->clear(list);
620 }
621
622 /**
623 * Swaps two items in the list.
624 *
625 * Implementations should only allocate temporary memory for the swap, if
626 * it is necessary.
627 *
628 * @param list the list
629 * @param i the index of the first element
630 * @param j the index of the second element
631 * @retval zero success
632 * @retval non-zero one of the indices is out of bounds
633 * or the swap needed extra memory but allocation failed
634 */
635 cx_attr_nonnull
636 static inline int cxListSwap(
637 CxList *list,
638 size_t i,
639 size_t j
640 ) {
641 return list->cl->swap(list, i, j);
642 }
643
644 /**
645 * Returns a pointer to the element at the specified index.
646 *
647 * @param list the list
648 * @param index the index of the element
649 * @return a pointer to the element or @c NULL if the index is out of bounds
650 */
651 cx_attr_nonnull
652 static inline void *cxListAt(
653 const CxList *list,
654 size_t index
655 ) {
656 return list->cl->at(list, index);
657 }
658
659 /**
660 * Returns an iterator pointing to the item at the specified index.
661 *
662 * The returned iterator is position-aware.
663 *
664 * If the index is out of range, a past-the-end iterator will be returned.
665 *
666 * @param list the list
667 * @param index the index where the iterator shall point at
668 * @return a new iterator
669 */
670 cx_attr_nonnull
671 cx_attr_nodiscard
672 static inline CxIterator cxListIteratorAt(
673 const CxList *list,
674 size_t index
675 ) {
676 return list->cl->iterator(list, index, false);
677 }
678
679 /**
680 * Returns a backwards iterator pointing to the item at the specified index.
681 *
682 * The returned iterator is position-aware.
683 *
684 * If the index is out of range, a past-the-end iterator will be returned.
685 *
686 * @param list the list
687 * @param index the index where the iterator shall point at
688 * @return a new iterator
689 */
690 cx_attr_nonnull
691 cx_attr_nodiscard
692 static inline CxIterator cxListBackwardsIteratorAt(
693 const CxList *list,
694 size_t index
695 ) {
696 return list->cl->iterator(list, index, true);
697 }
698
699 /**
700 * Returns a mutating iterator pointing to the item at the specified index.
701 *
702 * The returned iterator is position-aware.
703 *
704 * If the index is out of range, a past-the-end iterator will be returned.
705 *
706 * @param list the list
707 * @param index the index where the iterator shall point at
708 * @return a new iterator
709 */
710 cx_attr_nonnull
711 cx_attr_nodiscard
712 CxIterator cxListMutIteratorAt(
713 CxList *list,
714 size_t index
715 );
716
717 /**
718 * Returns a mutating backwards iterator pointing to the item at the
719 * specified index.
720 *
721 * The returned iterator is position-aware.
722 *
723 * If the index is out of range, a past-the-end iterator will be returned.
724 *
725 * @param list the list
726 * @param index the index where the iterator shall point at
727 * @return a new iterator
728 */
729 cx_attr_nonnull
730 cx_attr_nodiscard
731 CxIterator cxListMutBackwardsIteratorAt(
732 CxList *list,
733 size_t index
734 );
735
736 /**
737 * Returns an iterator pointing to the first item of the list.
738 *
739 * The returned iterator is position-aware.
740 *
741 * If the list is empty, a past-the-end iterator will be returned.
742 *
743 * @param list the list
744 * @return a new iterator
745 */
746 cx_attr_nonnull
747 cx_attr_nodiscard
748 static inline CxIterator cxListIterator(const CxList *list) {
749 return list->cl->iterator(list, 0, false);
750 }
751
752 /**
753 * Returns a mutating iterator pointing to the first item of the list.
754 *
755 * The returned iterator is position-aware.
756 *
757 * If the list is empty, a past-the-end iterator will be returned.
758 *
759 * @param list the list
760 * @return a new iterator
761 */
762 cx_attr_nonnull
763 cx_attr_nodiscard
764 static inline CxIterator cxListMutIterator(CxList *list) {
765 return cxListMutIteratorAt(list, 0);
766 }
767
768
769 /**
770 * Returns a backwards iterator pointing to the last item of the list.
771 *
772 * The returned iterator is position-aware.
773 *
774 * If the list is empty, a past-the-end iterator will be returned.
775 *
776 * @param list the list
777 * @return a new iterator
778 */
779 cx_attr_nonnull
780 cx_attr_nodiscard
781 static inline CxIterator cxListBackwardsIterator(const CxList *list) {
782 return list->cl->iterator(list, list->collection.size - 1, true);
783 }
784
785 /**
786 * Returns a mutating backwards iterator pointing to the last item of the list.
787 *
788 * The returned iterator is position-aware.
789 *
790 * If the list is empty, a past-the-end iterator will be returned.
791 *
792 * @param list the list
793 * @return a new iterator
794 */
795 cx_attr_nonnull
796 cx_attr_nodiscard
797 static inline CxIterator cxListMutBackwardsIterator(CxList *list) {
798 return cxListMutBackwardsIteratorAt(list, list->collection.size - 1);
799 }
800
801 /**
802 * Returns the index of the first element that equals @p elem.
803 *
804 * Determining equality is performed by the list's comparator function.
805 *
806 * @param list the list
807 * @param elem the element to find
808 * @return the index of the element or a negative
809 * value when the element is not found
810 */
811 cx_attr_nonnull
812 cx_attr_nodiscard
813 static inline ssize_t cxListFind(
814 const CxList *list,
815 const void *elem
816 ) {
817 return list->cl->find_remove((CxList*)list, elem, false);
818 }
819
820 /**
821 * Removes and returns the index of the first element that equals @p elem.
822 *
823 * Determining equality is performed by the list's comparator function.
824 *
825 * @param list the list
826 * @param elem the element to find and remove
827 * @return the index of the now removed element or a negative
828 * value when the element is not found or could not be removed
829 */
830 cx_attr_nonnull
831 static inline ssize_t cxListFindRemove(
832 CxList *list,
833 const void *elem
834 ) {
835 return list->cl->find_remove(list, elem, true);
836 }
837
838 /**
839 * Sorts the list.
840 *
841 * @remark The underlying sort algorithm is implementation defined.
842 *
843 * @param list the list
844 */
845 cx_attr_nonnull
846 static inline void cxListSort(CxList *list) {
847 list->cl->sort(list);
848 }
849
850 /**
851 * Reverses the order of the items.
852 *
853 * @param list the list
854 */
855 cx_attr_nonnull
856 static inline void cxListReverse(CxList *list) {
857 list->cl->reverse(list);
858 }
859
860 /**
861 * Compares a list to another list of the same type.
862 *
863 * First, the list sizes are compared.
864 * If they match, the lists are compared element-wise.
865 *
866 * @param list the list
867 * @param other the list to compare to
868 * @retval zero both lists are equal element wise
869 * @retval negative the first list is smaller
870 * or the first non-equal element in the first list is smaller
871 * @retval positive the first list is larger
872 * or the first non-equal element in the first list is larger
873 */
874 cx_attr_nonnull
875 cx_attr_nodiscard
876 int cxListCompare(
877 const CxList *list,
878 const CxList *other
879 );
880
881 /**
882 * Deallocates the memory of the specified list structure.
883 *
884 * Also calls the content destructor functions for each element, if specified.
885 *
886 * @param list the list which shall be freed
887 */
888 void cxListFree(CxList *list);
889
890 /**
891 * A shared instance of an empty list.
892 *
893 * Writing to that list is not allowed.
894 *
895 * You can use this is a placeholder for initializing CxList pointers
896 * for which you do not want to reserve memory right from the beginning.
897 */
898 extern CxList *const cxEmptyList;
899
900
901 #ifdef __cplusplus
902 } // extern "C"
903 #endif
904
905 #endif // UCX_LIST_H
906