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