Wed, 15 Feb 2023 16:48:11 +0100
implement backwards iterator - fixes #238
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 swapping two elements.
168 */
169 int (*swap)(
170 struct cx_list_s *list,
171 size_t i,
172 size_t j
173 );
175 /**
176 * Member function for element lookup.
177 */
178 void *(*at)(
179 struct cx_list_s const *list,
180 size_t index
181 );
183 /**
184 * Member function for finding an element.
185 */
186 size_t (*find)(
187 struct cx_list_s const *list,
188 void const *elem
189 );
191 /**
192 * Member function for sorting the list in place.
193 */
194 void (*sort)(struct cx_list_s *list);
196 /**
197 * Member function for comparing this list to another list of the same type.
198 */
199 int (*compare)(
200 struct cx_list_s const *list,
201 struct cx_list_s const *other
202 );
204 /**
205 * Member function for reversing the order of the items.
206 */
207 void (*reverse)(struct cx_list_s *list);
209 /**
210 * Member function for returning an iterator pointing to the specified index.
211 */
212 struct cx_iterator_s (*iterator)(
213 struct cx_list_s const *list,
214 size_t index,
215 bool backward
216 );
217 };
219 /**
220 * Common type for all list implementations.
221 */
222 typedef struct cx_list_s CxList;
224 /**
225 * Advises the list to store copies of the objects (default mode of operation).
226 *
227 * Retrieving objects from this list will yield pointers to the copies stored
228 * within this list.
229 *
230 * @param list the list
231 * @see cxListStorePointers()
232 */
233 __attribute__((__nonnull__))
234 void cxListStoreObjects(CxList *list);
236 /**
237 * Advises the list to only store pointers to the objects.
238 *
239 * Retrieving objects from this list will yield the original pointers stored.
240 *
241 * @note This function forcibly sets the element size to the size of a pointer.
242 * Invoking this function on a non-empty list that already stores copies of
243 * objects is undefined.
244 *
245 * @param list the list
246 * @see cxListStoreObjects()
247 */
248 __attribute__((__nonnull__))
249 void cxListStorePointers(CxList *list);
251 /**
252 * Returns true, if this list is storing pointers instead of the actual data.
253 *
254 * @param list
255 * @return
256 * @see cxListStorePointers()
257 */
258 __attribute__((__nonnull__))
259 bool cxListIsStoringPointers(CxList *list);
261 /**
262 * Adds an item to the end of the list.
263 *
264 * @param list the list
265 * @param elem a pointer to the element to add
266 * @return zero on success, non-zero on memory allocation failure
267 * @see cxListAddArray()
268 */
269 __attribute__((__nonnull__))
270 static inline int cxListAdd(
271 CxList *list,
272 void const *elem
273 ) {
274 return list->cl->insert_element(list, list->size, elem);
275 }
277 /**
278 * Adds multiple items to the end of the list.
279 *
280 * This method is more efficient than invoking cxListAdd() multiple times.
281 *
282 * If there is not enough memory to add all elements, the returned value is
283 * less than \p n.
284 *
285 * If this list is storing pointers instead of objects \p array is expected to
286 * be an array of pointers.
287 *
288 * @param list the list
289 * @param array a pointer to the elements to add
290 * @param n the number of elements to add
291 * @return the number of added elements
292 */
293 __attribute__((__nonnull__))
294 static inline size_t cxListAddArray(
295 CxList *list,
296 void const *array,
297 size_t n
298 ) {
299 return list->cl->insert_array(list, list->size, array, n);
300 }
302 /**
303 * Inserts an item at the specified index.
304 *
305 * If \p index equals the list \c size, this is effectively cxListAdd().
306 *
307 * @param list the list
308 * @param index the index the element shall have
309 * @param elem a pointer to the element to add
310 * @return zero on success, non-zero on memory allocation failure
311 * or when the index is out of bounds
312 * @see cxListInsertAfter()
313 * @see cxListInsertBefore()
314 */
315 __attribute__((__nonnull__))
316 static inline int cxListInsert(
317 CxList *list,
318 size_t index,
319 void const *elem
320 ) {
321 return list->cl->insert_element(list, index, elem);
322 }
324 /**
325 * Inserts multiple items to the list at the specified index.
326 * If \p index equals the list size, this is effectively cxListAddArray().
327 *
328 * This method is usually more efficient than invoking cxListInsert()
329 * multiple times.
330 *
331 * If there is not enough memory to add all elements, the returned value is
332 * less than \p n.
333 *
334 * If this list is storing pointers instead of objects \p array is expected to
335 * be an array of pointers.
336 *
337 * @param list the list
338 * @param index the index where to add the elements
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 cxListInsertArray(
345 CxList *list,
346 size_t index,
347 void const *array,
348 size_t n
349 ) {
350 return list->cl->insert_array(list, index, array, n);
351 }
353 /**
354 * Inserts an element after the current location of the specified iterator.
355 *
356 * The used iterator remains operational, but all other active iterators should
357 * be considered invalidated.
358 *
359 * If \p iter is not a list iterator, the behavior is undefined.
360 * If \p iter is a past-the-end iterator, the new element gets appended to the list.
361 *
362 * @param iter an iterator
363 * @param elem the element to insert
364 * @return zero on success, non-zero on memory allocation failure
365 * @see cxListInsert()
366 * @see cxListInsertBefore()
367 */
368 __attribute__((__nonnull__))
369 static inline int cxListInsertAfter(
370 CxMutIterator *iter,
371 void const *elem
372 ) {
373 return ((struct cx_list_s *) iter->src_handle)->cl->insert_iter(iter, elem, 0);
374 }
376 /**
377 * Inserts an element before the current location of the specified iterator.
378 *
379 * The used iterator remains operational, but all other active iterators should
380 * be considered invalidated.
381 *
382 * If \p iter is not a list iterator, the behavior is undefined.
383 * If \p iter is a past-the-end iterator, the new element gets appended to the list.
384 *
385 * @param iter an iterator
386 * @param elem the element to insert
387 * @return zero on success, non-zero on memory allocation failure
388 * @see cxListInsert()
389 * @see cxListInsertAfter()
390 */
391 __attribute__((__nonnull__))
392 static inline int cxListInsertBefore(
393 CxMutIterator *iter,
394 void const *elem
395 ) {
396 return ((struct cx_list_s *) iter->src_handle)->cl->insert_iter(iter, elem, 1);
397 }
399 /**
400 * Removes the element at the specified index.
401 * @param list the list
402 * @param index the index of the element
403 * @return zero on success, non-zero if the index is out of bounds
404 */
405 __attribute__((__nonnull__))
406 static inline int cxListRemove(
407 CxList *list,
408 size_t index
409 ) {
410 return list->cl->remove(list, index);
411 }
413 /**
414 * Swaps two items in the list.
415 *
416 * Implementations should only allocate temporary memory for the swap, if
417 * it is necessary.
418 *
419 * @param list the list
420 * @param i the index of the first element
421 * @param j the index of the second element
422 * @return zero on success, non-zero if one of the indices is out of bounds
423 */
424 __attribute__((__nonnull__))
425 static inline int cxListSwap(
426 CxList *list,
427 size_t i,
428 size_t j
429 ) {
430 return list->cl->swap(list, i, j);
431 }
433 /**
434 * Returns a pointer to the element at the specified index.
435 *
436 * @param list the list
437 * @param index the index of the element
438 * @return a pointer to the element or \c NULL if the index is out of bounds
439 */
440 __attribute__((__nonnull__))
441 static inline void *cxListAt(
442 CxList *list,
443 size_t index
444 ) {
445 return list->cl->at(list, index);
446 }
448 /**
449 * Returns an iterator pointing to the item at the specified index.
450 *
451 * The returned iterator is position-aware.
452 *
453 * If the index is out of range, a past-the-end iterator will be returned.
454 *
455 * @param list the list
456 * @param index the index where the iterator shall point at
457 * @return a new iterator
458 */
459 __attribute__((__nonnull__, __warn_unused_result__))
460 static inline CxIterator cxListIteratorAt(
461 CxList const *list,
462 size_t index
463 ) {
464 return list->cl->iterator(list, index, false);
465 }
467 /**
468 * Returns a backwards iterator pointing to the item at the specified index.
469 *
470 * The returned iterator is position-aware.
471 *
472 * If the index is out of range, a past-the-end iterator will be returned.
473 *
474 * @param list the list
475 * @param index the index where the iterator shall point at
476 * @return a new iterator
477 */
478 __attribute__((__nonnull__, __warn_unused_result__))
479 static inline CxIterator cxListBackwardsIteratorAt(
480 CxList const *list,
481 size_t index
482 ) {
483 return list->cl->iterator(list, index, true);
484 }
486 /**
487 * Returns a mutating iterator pointing to the item at the 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 cxListMutIteratorAt(
499 CxList *list,
500 size_t index
501 );
503 /**
504 * Returns a mutating backwards iterator pointing to the item at the
505 * specified index.
506 *
507 * The returned iterator is position-aware.
508 *
509 * If the index is out of range, a past-the-end iterator will be returned.
510 *
511 * @param list the list
512 * @param index the index where the iterator shall point at
513 * @return a new iterator
514 */
515 __attribute__((__nonnull__, __warn_unused_result__))
516 CxMutIterator cxListMutBackwardsIteratorAt(
517 CxList *list,
518 size_t index
519 );
521 /**
522 * Returns an 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 CxIterator cxListIterator(CxList const *list) {
533 return list->cl->iterator(list, 0, false);
534 }
536 /**
537 * Returns a mutating iterator pointing to the first item of the list.
538 *
539 * The returned iterator is position-aware.
540 *
541 * If the list is empty, a past-the-end iterator will be returned.
542 *
543 * @param list the list
544 * @return a new iterator
545 */
546 __attribute__((__nonnull__, __warn_unused_result__))
547 static inline CxMutIterator cxListMutIterator(CxList *list) {
548 return cxListMutIteratorAt(list, 0);
549 }
552 /**
553 * Returns a 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 CxIterator cxListBackwardsIterator(CxList const *list) {
564 return list->cl->iterator(list, list->size - 1, true);
565 }
567 /**
568 * Returns a mutating backwards iterator pointing to the last item of the list.
569 *
570 * The returned iterator is position-aware.
571 *
572 * If the list is empty, a past-the-end iterator will be returned.
573 *
574 * @param list the list
575 * @return a new iterator
576 */
577 __attribute__((__nonnull__, __warn_unused_result__))
578 static inline CxMutIterator cxListMutBackwardsIterator(CxList *list) {
579 return cxListMutBackwardsIteratorAt(list, list->size - 1);
580 }
582 /**
583 * Returns the index of the first element that equals \p elem.
584 *
585 * Determining equality is performed by the list's comparator function.
586 *
587 * @param list the list
588 * @param elem the element to find
589 * @return the index of the element or \c (size+1) if the element is not found
590 */
591 __attribute__((__nonnull__))
592 static inline size_t cxListFind(
593 CxList const *list,
594 void const *elem
595 ) {
596 return list->cl->find(list, elem);
597 }
599 /**
600 * Sorts the list in place.
601 *
602 * \remark The underlying sort algorithm is implementation defined.
603 *
604 * @param list the list
605 */
606 __attribute__((__nonnull__))
607 static inline void cxListSort(CxList *list) {
608 list->cl->sort(list);
609 }
611 /**
612 * Reverses the order of the items.
613 *
614 * @param list the list
615 */
616 __attribute__((__nonnull__))
617 static inline void cxListReverse(CxList *list) {
618 list->cl->reverse(list);
619 }
621 /**
622 * Compares a list to another list of the same type.
623 *
624 * First, the list sizes are compared.
625 * If they match, the lists are compared element-wise.
626 *
627 * @param list the list
628 * @param other the list to compare to
629 * @return zero, if both lists are equal element wise,
630 * negative if the first list is smaller, positive if the first list is larger
631 */
632 __attribute__((__nonnull__))
633 int cxListCompare(
634 CxList const *list,
635 CxList const *other
636 );
638 /**
639 * Deallocates the memory of the specified list structure.
640 *
641 * Also calls content a destructor function, depending on the configuration
642 * in CxList.content_destructor_type.
643 *
644 * This function itself is a destructor function for the CxList.
645 *
646 * @param list the list which shall be destroyed
647 */
648 __attribute__((__nonnull__))
649 void cxListDestroy(CxList *list);
651 #ifdef __cplusplus
652 } // extern "C"
653 #endif
655 #endif // UCX_LIST_H