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