src/cx/iterator.h

Sat, 22 Jan 2022 17:15:14 +0100

author
Mike Becker <universe@uap-core.de>
date
Sat, 22 Jan 2022 17:15:14 +0100
changeset 494
6ce8cfa10a96
child 495
2856c74e18ba
permissions
-rw-r--r--

add iterator interface + linked list iterator

universe@494 1 /*
universe@494 2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
universe@494 3 *
universe@494 4 * Copyright 2021 Mike Becker, Olaf Wintermann All rights reserved.
universe@494 5 *
universe@494 6 * Redistribution and use in source and binary forms, with or without
universe@494 7 * modification, are permitted provided that the following conditions are met:
universe@494 8 *
universe@494 9 * 1. Redistributions of source code must retain the above copyright
universe@494 10 * notice, this list of conditions and the following disclaimer.
universe@494 11 *
universe@494 12 * 2. Redistributions in binary form must reproduce the above copyright
universe@494 13 * notice, this list of conditions and the following disclaimer in the
universe@494 14 * documentation and/or other materials provided with the distribution.
universe@494 15 *
universe@494 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
universe@494 17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
universe@494 18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
universe@494 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
universe@494 20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
universe@494 21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
universe@494 22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
universe@494 23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
universe@494 24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
universe@494 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
universe@494 26 * POSSIBILITY OF SUCH DAMAGE.
universe@494 27 */
universe@494 28 /**
universe@494 29 * \file iterator.h
universe@494 30 * \brief Interface for iterator implementations.
universe@494 31 * \author Mike Becker
universe@494 32 * \author Olaf Wintermann
universe@494 33 * \version 3.0
universe@494 34 * \copyright 2-Clause BSD License
universe@494 35 */
universe@494 36
universe@494 37 #ifndef UCX_ITERATOR_H
universe@494 38 #define UCX_ITERATOR_H
universe@494 39
universe@494 40 #include "common.h"
universe@494 41
universe@494 42 /**
universe@494 43 * Iterator value type.
universe@494 44 * An iterator points to a certain element in an (possibly unbounded) chain of elements.
universe@494 45 * Iterators that are based on collections (which have a defined "first" element), are supposed
universe@494 46 * to be "position-aware", which means that they keep track of the current index within the collection.
universe@494 47 *
universe@494 48 * @note Objects that are pointed to by an iterator are mutable through that iterator. However, if the
universe@494 49 * iterator is based on a collection and the underlying collection is mutated (elements added or removed),
universe@494 50 * the iterator becomes invalid (regardless of what cxIteratorValid() returns) and MUST be re-obtained
universe@494 51 * from the collection.
universe@494 52 */
universe@494 53 typedef struct cx_iterator_s CxIterator;
universe@494 54
universe@494 55 /**
universe@494 56 * Internal iterator struct - use CxIterator.
universe@494 57 */
universe@494 58 struct cx_iterator_s {
universe@494 59 /**
universe@494 60 * If the iterator is position-aware, contains the index of the element in the underlying collection.
universe@494 61 * Otherwise, this field is usually uninitialized.
universe@494 62 */
universe@494 63 size_t index;
universe@494 64 /**
universe@494 65 * Internal data.
universe@494 66 */
universe@494 67 void *data;
universe@494 68
universe@494 69 /**
universe@494 70 * True iff the iterator points to valid data.
universe@494 71 */
universe@494 72 bool (*valid)(CxIterator const *) __attribute__ ((__nonnull__));
universe@494 73
universe@494 74 /**
universe@494 75 * Returns a pointer to the current element.
universe@494 76 */
universe@494 77 void *(*current)(CxIterator const *) __attribute__ ((__nonnull__));
universe@494 78
universe@494 79 /**
universe@494 80 * Advances the iterator.
universe@494 81 */
universe@494 82 void (*next)(CxIterator *) __attribute__ ((__nonnull__));
universe@494 83 };
universe@494 84
universe@494 85 /**
universe@494 86 * Checks if the iterator points to valid data.
universe@494 87 *
universe@494 88 * This is especially false for past-the-end iterators.
universe@494 89 *
universe@494 90 * @param iter the iterator
universe@494 91 * @return true iff the iterator points to valid data
universe@494 92 */
universe@494 93 __attribute__ ((__nonnull__))
universe@494 94 static inline bool cxIteratorValid(CxIterator const *iter) {
universe@494 95 return iter->valid(iter);
universe@494 96 }
universe@494 97
universe@494 98 /**
universe@494 99 * Returns a pointer to the current element.
universe@494 100 *
universe@494 101 * The behavior is undefined if this iterator is invalid.
universe@494 102 *
universe@494 103 * @param iter the iterator
universe@494 104 * @return a pointer to the current element
universe@494 105 */
universe@494 106 __attribute__ ((__nonnull__))
universe@494 107 static inline void *cxIteratorCurrent(CxIterator const *iter) {
universe@494 108 return iter->current(iter);
universe@494 109 }
universe@494 110
universe@494 111 /**
universe@494 112 * Advances the iterator to the next element.
universe@494 113 *
universe@494 114 * @param iter the iterator
universe@494 115 */
universe@494 116 __attribute__ ((__nonnull__))
universe@494 117 static inline void cxIteratorNext(CxIterator *iter) {
universe@494 118 iter->next(iter);
universe@494 119 }
universe@494 120
universe@494 121 #endif /* UCX_ITERATOR_H */

mercurial