src/cx/iterator.h@7d4e31d295af
src/cx/iterator.h
Sat, 17 Feb 2024 20:51:27 +0100
- author
- Mike Becker <universe@uap-core.de>
- date
- Sat, 17 Feb 2024 20:51:27 +0100
- changeset 829
- 7d4e31d295af
- parent 759
- 475335643af4
- permissions
- -rw-r--r--
remove unnecessary flag_removal function
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 iterator.h
30 * \brief Interface for iterator implementations.
31 * \author Mike Becker
32 * \author Olaf Wintermann
33 * \copyright 2-Clause BSD License
34 */
36 #ifndef UCX_ITERATOR_H
37 #define UCX_ITERATOR_H
39 #include "common.h"
41 /**
42 * The base of mutating and non-mutating iterators.
43 */
44 struct cx_iterator_base_s {
45 /**
46 * True iff the iterator points to valid data.
47 */
48 __attribute__ ((__nonnull__))
49 bool (*valid)(void const *);
51 /**
52 * Returns a pointer to the current element.
53 *
54 * When valid returns false, the behavior of this function is undefined.
55 */
56 __attribute__ ((__nonnull__))
57 void *(*current)(void const *);
59 /**
60 * Original implementation in case the function needs to be wrapped.
61 */
62 __attribute__ ((__nonnull__))
63 void *(*current_impl)(void const *);
65 /**
66 * Advances the iterator.
67 *
68 * When valid returns false, the behavior of this function is undefined.
69 */
70 __attribute__ ((__nonnull__))
71 void (*next)(void *);
73 /**
74 * Indicates whether this iterator may remove elements.
75 */
76 bool mutating;
78 /**
79 * Internal flag for removing the current element when advancing.
80 */
81 bool remove;
82 };
84 /**
85 * Internal iterator struct - use CxMutIterator.
86 */
87 struct cx_mut_iterator_s {
89 /**
90 * The base properties of this iterator.
91 */
92 struct cx_iterator_base_s base;
94 /**
95 * Handle for the current element, if required.
96 */
97 void *elem_handle;
99 /**
100 * Handle for the source collection, if any.
101 */
102 void *src_handle;
104 /**
105 * Field for storing a key-value pair.
106 * May be used by iterators that iterate over k/v-collections.
107 */
108 struct {
109 /**
110 * A pointer to the key.
111 */
112 void const *key;
113 /**
114 * A pointer to the value.
115 */
116 void *value;
117 } kv_data;
119 /**
120 * Field for storing a slot number.
121 * May be used by iterators that iterate over multi-bucket collections.
122 */
123 size_t slot;
125 /**
126 * If the iterator is position-aware, contains the index of the element in the underlying collection.
127 * Otherwise, this field is usually uninitialized.
128 */
129 size_t index;
130 };
132 /**
133 * Mutating iterator value type.
134 *
135 * An iterator points to a certain element in an (possibly unbounded) chain of elements.
136 * Iterators that are based on collections (which have a defined "first" element), are supposed
137 * to be "position-aware", which means that they keep track of the current index within the collection.
138 *
139 * @note Objects that are pointed to by an iterator are mutable through that iterator. However, if the
140 * iterator is based on a collection and the underlying collection is mutated by other means than this iterator
141 * (e.g. elements added or removed), the iterator becomes invalid (regardless of what cxIteratorValid() returns)
142 * and MUST be re-obtained from the collection.
143 *
144 * @see CxIterator
145 */
146 typedef struct cx_mut_iterator_s CxMutIterator;
148 /**
149 * Internal iterator struct - use CxIterator.
150 */
151 struct cx_iterator_s {
153 /**
154 * The base properties of this iterator.
155 */
156 struct cx_iterator_base_s base;
158 /**
159 * Handle for the current element, if required.
160 */
161 void *elem_handle;
163 /**
164 * Handle for the source collection, if any.
165 */
166 void const *src_handle;
168 /**
169 * Field for storing a key-value pair.
170 * May be used by iterators that iterate over k/v-collections.
171 */
172 struct {
173 /**
174 * A pointer to the key.
175 */
176 void const *key;
177 /**
178 * A pointer to the value.
179 */
180 void *value;
181 } kv_data;
183 /**
184 * Field for storing a slot number.
185 * May be used by iterators that iterate over multi-bucket collections.
186 */
187 size_t slot;
189 /**
190 * If the iterator is position-aware, contains the index of the element in the underlying collection.
191 * Otherwise, this field is usually uninitialized.
192 */
193 size_t index;
194 };
196 /**
197 * Iterator value type.
198 * An iterator points to a certain element in a (possibly unbounded) chain of elements.
199 * Iterators that are based on collections (which have a defined "first" element), are supposed
200 * to be "position-aware", which means that they keep track of the current index within the collection.
201 *
202 * @note Objects that are pointed to by an iterator are always mutable through that iterator. However,
203 * this iterator cannot mutate the collection itself (add or remove elements) and any mutation of the
204 * collection by other means makes this iterator invalid (regardless of what cxIteratorValid() returns).
205 *
206 * @see CxMutIterator
207 */
208 typedef struct cx_iterator_s CxIterator;
210 /**
211 * Checks if the iterator points to valid data.
212 *
213 * This is especially false for past-the-end iterators.
214 *
215 * @param iter the iterator
216 * @return true iff the iterator points to valid data
217 */
218 #define cxIteratorValid(iter) (iter).base.valid(&(iter))
220 /**
221 * Returns a pointer to the current element.
222 *
223 * The behavior is undefined if this iterator is invalid.
224 *
225 * @param iter the iterator
226 * @return a pointer to the current element
227 */
228 #define cxIteratorCurrent(iter) (iter).base.current(&iter)
230 /**
231 * Advances the iterator to the next element.
232 *
233 * @param iter the iterator
234 */
235 #define cxIteratorNext(iter) (iter).base.next(&iter)
237 /**
238 * Flags the current element for removal, if this iterator is mutating.
239 *
240 * @param iter the iterator
241 */
242 #define cxIteratorFlagRemoval(iter) (iter).base.remove |= (iter).base.mutating
244 /**
245 * Loops over an iterator.
246 * @param type the type of the elements
247 * @param elem the name of the iteration variable
248 * @param iter the iterator
249 */
250 #define cx_foreach(type, elem, iter) \
251 for (type elem; cxIteratorValid(iter) && (elem = (type)cxIteratorCurrent(iter)) != NULL ; cxIteratorNext(iter))
253 #endif // UCX_ITERATOR_H
