Mon, 18 Dec 2023 14:25:10 +0100
update build instructions
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 */
36 #ifndef UCX_LIST_H
37 #define UCX_LIST_H
39 #include "common.h"
40 #include "collection.h"
42 #ifdef __cplusplus
43 extern "C" {
44 #endif
46 /**
47 * List class type.
48 */
49 typedef struct cx_list_class_s cx_list_class;
51 /**
52 * Structure for holding the base data of a list.
53 */
54 struct cx_list_s {
55 CX_COLLECTION_MEMBERS
56 /**
57 * The list class definition.
58 */
59 cx_list_class const *cl;
60 /**
61 * The actual implementation in case the list class is delegating.
62 */
63 cx_list_class const *climpl;
64 };
66 /**
67 * The class definition for arbitrary lists.
68 */
69 struct cx_list_class_s {
70 /**
71 * Destructor function.
72 *
73 * Implementations SHALL invoke the content destructor functions if provided
74 * and SHALL deallocate the list memory, if an allocator is provided.
75 */
76 void (*destructor)(struct cx_list_s *list);
78 /**
79 * Member function for inserting a single element.
80 * Implementors SHOULD see to performant implementations for corner cases.
81 */
82 int (*insert_element)(
83 struct cx_list_s *list,
84 size_t index,
85 void const *data
86 );
88 /**
89 * Member function for inserting multiple elements.
90 * Implementors SHOULD see to performant implementations for corner cases.
91 */
92 size_t (*insert_array)(
93 struct cx_list_s *list,
94 size_t index,
95 void const *data,
96 size_t n
97 );
99 /**
100 * Member function for inserting an element relative to an iterator position.
101 */
102 int (*insert_iter)(
103 struct cx_mut_iterator_s *iter,
104 void const *elem,
105 int prepend
106 );
108 /**
109 * Member function for removing an element.
110 */
111 int (*remove)(
112 struct cx_list_s *list,
113 size_t index
114 );
116 /**
117 * Member function for removing all elements.
118 */
119 void (*clear)(struct cx_list_s *list);
121 /**
122 * Member function for swapping two elements.
123 */
124 int (*swap)(
125 struct cx_list_s *list,
126 size_t i,
127 size_t j
128 );
130 /**
131 * Member function for element lookup.
132 */
133 void *(*at)(
134 struct cx_list_s const *list,
135 size_t index
136 );
138 /**
139 * Member function for finding an element.
140 */
141 ssize_t (*find)(
142 struct cx_list_s const *list,
143 void const *elem
144 );
146 /**
147 * Member function for sorting the list in-place.
148 */
149 void (*sort)(struct cx_list_s *list);
151 /**
152 * Member function for comparing this list to another list of the same type.
153 */
154 int (*compare)(
155 struct cx_list_s const *list,
156 struct cx_list_s const *other
157 );
159 /**
160 * Member function for reversing the order of the items.
161 */
162 void (*reverse)(struct cx_list_s *list);
164 /**
165 * Member function for returning an iterator pointing to the specified index.
166 */
167 struct cx_iterator_s (*iterator)(
168 struct cx_list_s const *list,
169 size_t index,
170 bool backward
171 );
172 };
174 /**
175 * Common type for all list implementations.
176 */
177 typedef struct cx_list_s CxList;
179 /**
180 * Advises the list to store copies of the objects (default mode of operation).
181 *
182 * Retrieving objects from this list will yield pointers to the copies stored
183 * within this list.
184 *
185 * @param list the list
186 * @see cxListStorePointers()
187 */
188 __attribute__((__nonnull__))
189 void cxListStoreObjects(CxList *list);
191 /**
192 * Advises the list to only store pointers to the objects.
193 *
194 * Retrieving objects from this list will yield the original pointers stored.
195 *
196 * @note This function forcibly sets the element size to the size of a pointer.
197 * Invoking this function on a non-empty list that already stores copies of
198 * objects is undefined.
199 *
200 * @param list the list
201 * @see cxListStoreObjects()
202 */
203 __attribute__((__nonnull__))
204 void cxListStorePointers(CxList *list);
206 /**
207 * Returns true, if this list is storing pointers instead of the actual data.
208 *
209 * @param list
210 * @return true, if this list is storing pointers
211 * @see cxListStorePointers()
212 */
213 __attribute__((__nonnull__))
214 static inline bool cxListIsStoringPointers(CxList const *list) {
215 return list->store_pointer;
216 }
218 /**
219 * Returns the number of elements currently stored in the list.
220 *
221 * @param list the list
222 * @return the number of currently stored elements
223 */
224 __attribute__((__nonnull__))
225 static inline size_t cxListSize(CxList const *list) {
226 return list->size;
227 }
229 /**
230 * Adds an item to the end of the list.
231 *
232 * @param list the list
233 * @param elem a pointer to the element to add
234 * @return zero on success, non-zero on memory allocation failure
235 * @see cxListAddArray()
236 */
237 __attribute__((__nonnull__))
238 static inline int cxListAdd(
239 CxList *list,
240 void const *elem
241 ) {
242 return list->cl->insert_element(list, list->size, elem);
243 }
245 /**
246 * Adds multiple items to the end of the list.
247 *
248 * This method is more efficient than invoking cxListAdd() multiple times.
249 *
250 * If there is not enough memory to add all elements, the returned value is
251 * less than \p n.
252 *
253 * If this list is storing pointers instead of objects \p array is expected to
254 * be an array of pointers.
255 *
256 * @param list the list
257 * @param array a pointer to the elements to add
258 * @param n the number of elements to add
259 * @return the number of added elements
260 */
261 __attribute__((__nonnull__))
262 static inline size_t cxListAddArray(
263 CxList *list,
264 void const *array,
265 size_t n
266 ) {
267 return list->cl->insert_array(list, list->size, array, n);
268 }
270 /**
271 * Inserts an item at the specified index.
272 *
273 * If \p index equals the list \c size, this is effectively cxListAdd().
274 *
275 * @param list the list
276 * @param index the index the element shall have
277 * @param elem a pointer to the element to add
278 * @return zero on success, non-zero on memory allocation failure
279 * or when the index is out of bounds
280 * @see cxListInsertAfter()
281 * @see cxListInsertBefore()
282 */
283 __attribute__((__nonnull__))
284 static inline int cxListInsert(
285 CxList *list,
286 size_t index,
287 void const *elem
288 ) {
289 return list->cl->insert_element(list, index, elem);
290 }
292 /**
293 * Inserts multiple items to the list at the specified index.
294 * If \p index equals the list size, this is effectively cxListAddArray().
295 *
296 * This method is usually more efficient than invoking cxListInsert()
297 * multiple times.
298 *
299 * If there is not enough memory to add all elements, the returned value is
300 * less than \p n.
301 *
302 * If this list is storing pointers instead of objects \p array is expected to
303 * be an array of pointers.
304 *
305 * @param list the list
306 * @param index the index where to add the elements
307 * @param array a pointer to the elements to add
308 * @param n the number of elements to add
309 * @return the number of added elements
310 */
311 __attribute__((__nonnull__))
312 static inline size_t cxListInsertArray(
313 CxList *list,
314 size_t index,
315 void const *array,
316 size_t n
317 ) {
318 return list->cl->insert_array(list, index, array, n);
319 }
321 /**
322 * Inserts an element after the current location of the specified iterator.
323 *
324 * The used iterator remains operational, but all other active iterators should
325 * be considered invalidated.
326 *
327 * If \p iter is not a list iterator, the behavior is undefined.
328 * If \p iter is a past-the-end iterator, the new element gets appended to the list.
329 *
330 * @param iter an iterator
331 * @param elem the element to insert
332 * @return zero on success, non-zero on memory allocation failure
333 * @see cxListInsert()
334 * @see cxListInsertBefore()
335 */
336 __attribute__((__nonnull__))
337 static inline int cxListInsertAfter(
338 CxMutIterator *iter,
339 void const *elem
340 ) {
341 return ((struct cx_list_s *) iter->src_handle)->cl->insert_iter(iter, elem, 0);
342 }
344 /**
345 * Inserts an element before the current location of the specified iterator.
346 *
347 * The used iterator remains operational, but all other active iterators should
348 * be considered invalidated.
349 *
350 * If \p iter is not a list iterator, the behavior is undefined.
351 * If \p iter is a past-the-end iterator, the new element gets appended to the list.
352 *
353 * @param iter an iterator
354 * @param elem the element to insert
355 * @return zero on success, non-zero on memory allocation failure
356 * @see cxListInsert()
357 * @see cxListInsertAfter()
358 */
359 __attribute__((__nonnull__))
360 static inline int cxListInsertBefore(
361 CxMutIterator *iter,
362 void const *elem
363 ) {
364 return ((struct cx_list_s *) iter->src_handle)->cl->insert_iter(iter, elem, 1);
365 }
367 /**
368 * Removes the element at the specified index.
369 *
370 * If an element destructor function is specified, it is called before
371 * removing the element.
372 *
373 * @param list the list
374 * @param index the index of the element
375 * @return zero on success, non-zero if the index is out of bounds
376 */
377 __attribute__((__nonnull__))
378 static inline int cxListRemove(
379 CxList *list,
380 size_t index
381 ) {
382 return list->cl->remove(list, index);
383 }
385 /**
386 * Removes all elements from this list.
387 *
388 * If an element destructor function is specified, it is called for each
389 * element before removing them.
390 *
391 * @param list the list
392 */
393 __attribute__((__nonnull__))
394 static inline void cxListClear(CxList *list) {
395 list->cl->clear(list);
396 }
398 /**
399 * Swaps two items in the list.
400 *
401 * Implementations should only allocate temporary memory for the swap, if
402 * it is necessary.
403 *
404 * @param list the list
405 * @param i the index of the first element
406 * @param j the index of the second element
407 * @return zero on success, non-zero if one of the indices is out of bounds
408 */
409 __attribute__((__nonnull__))
410 static inline int cxListSwap(
411 CxList *list,
412 size_t i,
413 size_t j
414 ) {
415 return list->cl->swap(list, i, j);
416 }
418 /**
419 * Returns a pointer to the element at the specified index.
420 *
421 * @param list the list
422 * @param index the index of the element
423 * @return a pointer to the element or \c NULL if the index is out of bounds
424 */
425 __attribute__((__nonnull__))
426 static inline void *cxListAt(
427 CxList *list,
428 size_t index
429 ) {
430 return list->cl->at(list, index);
431 }
433 /**
434 * Returns an iterator pointing to the item at the specified index.
435 *
436 * The returned iterator is position-aware.
437 *
438 * If the index is out of range, a past-the-end iterator will be returned.
439 *
440 * @param list the list
441 * @param index the index where the iterator shall point at
442 * @return a new iterator
443 */
444 __attribute__((__nonnull__, __warn_unused_result__))
445 static inline CxIterator cxListIteratorAt(
446 CxList const *list,
447 size_t index
448 ) {
449 return list->cl->iterator(list, index, false);
450 }
452 /**
453 * Returns a backwards iterator pointing to the item at the specified index.
454 *
455 * The returned iterator is position-aware.
456 *
457 * If the index is out of range, a past-the-end iterator will be returned.
458 *
459 * @param list the list
460 * @param index the index where the iterator shall point at
461 * @return a new iterator
462 */
463 __attribute__((__nonnull__, __warn_unused_result__))
464 static inline CxIterator cxListBackwardsIteratorAt(
465 CxList const *list,
466 size_t index
467 ) {
468 return list->cl->iterator(list, index, true);
469 }
471 /**
472 * Returns a mutating iterator pointing to the item at the specified index.
473 *
474 * The returned iterator is position-aware.
475 *
476 * If the index is out of range, a past-the-end iterator will be returned.
477 *
478 * @param list the list
479 * @param index the index where the iterator shall point at
480 * @return a new iterator
481 */
482 __attribute__((__nonnull__, __warn_unused_result__))
483 CxMutIterator cxListMutIteratorAt(
484 CxList *list,
485 size_t index
486 );
488 /**
489 * Returns a mutating backwards iterator pointing to the item at the
490 * specified index.
491 *
492 * The returned iterator is position-aware.
493 *
494 * If the index is out of range, a past-the-end iterator will be returned.
495 *
496 * @param list the list
497 * @param index the index where the iterator shall point at
498 * @return a new iterator
499 */
500 __attribute__((__nonnull__, __warn_unused_result__))
501 CxMutIterator cxListMutBackwardsIteratorAt(
502 CxList *list,
503 size_t index
504 );
506 /**
507 * Returns an iterator pointing to the first item of the list.
508 *
509 * The returned iterator is position-aware.
510 *
511 * If the list is empty, a past-the-end iterator will be returned.
512 *
513 * @param list the list
514 * @return a new iterator
515 */
516 __attribute__((__nonnull__, __warn_unused_result__))
517 static inline CxIterator cxListIterator(CxList const *list) {
518 return list->cl->iterator(list, 0, false);
519 }
521 /**
522 * Returns a mutating iterator pointing to the first item of the list.
523 *
524 * The returned iterator is position-aware.
525 *
526 * If the list is empty, a past-the-end iterator will be returned.
527 *
528 * @param list the list
529 * @return a new iterator
530 */
531 __attribute__((__nonnull__, __warn_unused_result__))
532 static inline CxMutIterator cxListMutIterator(CxList *list) {
533 return cxListMutIteratorAt(list, 0);
534 }
537 /**
538 * Returns a backwards iterator pointing to the last item of the list.
539 *
540 * The returned iterator is position-aware.
541 *
542 * If the list is empty, a past-the-end iterator will be returned.
543 *
544 * @param list the list
545 * @return a new iterator
546 */
547 __attribute__((__nonnull__, __warn_unused_result__))
548 static inline CxIterator cxListBackwardsIterator(CxList const *list) {
549 return list->cl->iterator(list, list->size - 1, true);
550 }
552 /**
553 * Returns a mutating backwards iterator pointing to the last item of the list.
554 *
555 * The returned iterator is position-aware.
556 *
557 * If the list is empty, a past-the-end iterator will be returned.
558 *
559 * @param list the list
560 * @return a new iterator
561 */
562 __attribute__((__nonnull__, __warn_unused_result__))
563 static inline CxMutIterator cxListMutBackwardsIterator(CxList *list) {
564 return cxListMutBackwardsIteratorAt(list, list->size - 1);
565 }
567 /**
568 * Returns the index of the first element that equals \p elem.
569 *
570 * Determining equality is performed by the list's comparator function.
571 *
572 * @param list the list
573 * @param elem the element to find
574 * @return the index of the element or a negative
575 * value when the element is not found
576 */
577 __attribute__((__nonnull__))
578 static inline ssize_t cxListFind(
579 CxList const *list,
580 void const *elem
581 ) {
582 return list->cl->find(list, elem);
583 }
585 /**
586 * Sorts the list in-place.
587 *
588 * \remark The underlying sort algorithm is implementation defined.
589 *
590 * @param list the list
591 */
592 __attribute__((__nonnull__))
593 static inline void cxListSort(CxList *list) {
594 list->cl->sort(list);
595 }
597 /**
598 * Reverses the order of the items.
599 *
600 * @param list the list
601 */
602 __attribute__((__nonnull__))
603 static inline void cxListReverse(CxList *list) {
604 list->cl->reverse(list);
605 }
607 /**
608 * Compares a list to another list of the same type.
609 *
610 * First, the list sizes are compared.
611 * If they match, the lists are compared element-wise.
612 *
613 * @param list the list
614 * @param other the list to compare to
615 * @return zero, if both lists are equal element wise,
616 * negative if the first list is smaller, positive if the first list is larger
617 */
618 __attribute__((__nonnull__))
619 int cxListCompare(
620 CxList const *list,
621 CxList const *other
622 );
624 /**
625 * Deallocates the memory of the specified list structure.
626 *
627 * Also calls content a destructor function, depending on the configuration
628 * in CxList.content_destructor_type.
629 *
630 * This function itself is a destructor function for the CxList.
631 *
632 * @param list the list which shall be destroyed
633 */
634 __attribute__((__nonnull__))
635 void cxListDestroy(CxList *list);
637 /**
638 * A shared instance of an empty list.
639 *
640 * Writing to that list is undefined.
641 */
642 extern CxList * const cxEmptyList;
645 #ifdef __cplusplus
646 } // extern "C"
647 #endif
649 #endif // UCX_LIST_H