Sun, 09 Apr 2023 19:06:16 +0200
reformat code
494
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
1 | /* |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
3 | * |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
4 | * Copyright 2021 Mike Becker, Olaf Wintermann All rights reserved. |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
5 | * |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
6 | * Redistribution and use in source and binary forms, with or without |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
7 | * modification, are permitted provided that the following conditions are met: |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
8 | * |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
9 | * 1. Redistributions of source code must retain the above copyright |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
10 | * notice, this list of conditions and the following disclaimer. |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
11 | * |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
12 | * 2. Redistributions in binary form must reproduce the above copyright |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
13 | * notice, this list of conditions and the following disclaimer in the |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
14 | * documentation and/or other materials provided with the distribution. |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
15 | * |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
16 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
17 | * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
18 | * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
19 | * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
20 | * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
21 | * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
22 | * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
23 | * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
24 | * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
25 | * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
26 | * POSSIBILITY OF SUCH DAMAGE. |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
27 | */ |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
28 | /** |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
29 | * \file iterator.h |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
30 | * \brief Interface for iterator implementations. |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
31 | * \author Mike Becker |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
32 | * \author Olaf Wintermann |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
33 | * \version 3.0 |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
34 | * \copyright 2-Clause BSD License |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
35 | */ |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
36 | |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
37 | #ifndef UCX_ITERATOR_H |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
38 | #define UCX_ITERATOR_H |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
39 | |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
40 | #include "common.h" |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
41 | |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
42 | /** |
630
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
43 | * The base of mutating and non-mutating iterators. |
494
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
44 | */ |
630
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
45 | struct cx_iterator_base_s { |
494
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
46 | /** |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
47 | * True iff the iterator points to valid data. |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
48 | */ |
551
2946e13c89a4
#189 implement map iterators
Mike Becker <universe@uap-core.de>
parents:
516
diff
changeset
|
49 | __attribute__ ((__nonnull__)) |
630
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
50 | bool (*valid)(void const *); |
494
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
51 | |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
52 | /** |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
53 | * Returns a pointer to the current element. |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
54 | */ |
551
2946e13c89a4
#189 implement map iterators
Mike Becker <universe@uap-core.de>
parents:
516
diff
changeset
|
55 | __attribute__ ((__nonnull__)) |
630
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
56 | void *(*current)(void const *); |
494
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
57 | |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
58 | /** |
641
d402fead3386
add new pointer list wrapper - resolves #234
Mike Becker <universe@uap-core.de>
parents:
630
diff
changeset
|
59 | * Original implementation in case the function needs to be wrapped. |
d402fead3386
add new pointer list wrapper - resolves #234
Mike Becker <universe@uap-core.de>
parents:
630
diff
changeset
|
60 | */ |
d402fead3386
add new pointer list wrapper - resolves #234
Mike Becker <universe@uap-core.de>
parents:
630
diff
changeset
|
61 | __attribute__ ((__nonnull__)) |
d402fead3386
add new pointer list wrapper - resolves #234
Mike Becker <universe@uap-core.de>
parents:
630
diff
changeset
|
62 | void *(*current_impl)(void const *); |
d402fead3386
add new pointer list wrapper - resolves #234
Mike Becker <universe@uap-core.de>
parents:
630
diff
changeset
|
63 | |
d402fead3386
add new pointer list wrapper - resolves #234
Mike Becker <universe@uap-core.de>
parents:
630
diff
changeset
|
64 | /** |
494
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
65 | * Advances the iterator. |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
66 | */ |
551
2946e13c89a4
#189 implement map iterators
Mike Becker <universe@uap-core.de>
parents:
516
diff
changeset
|
67 | __attribute__ ((__nonnull__)) |
630
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
68 | void (*next)(void *); |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
69 | |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
70 | /** |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
71 | * Flag current element for removal, if possible. |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
72 | */ |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
73 | __attribute__ ((__nonnull__)) |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
74 | bool (*flag_removal)(void *); |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
75 | |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
76 | /** |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
77 | * Indicates whether this iterator is muting. |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
78 | */ |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
79 | bool mutating; |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
80 | |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
81 | /** |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
82 | * Internal flag for removing the current element when advancing. |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
83 | */ |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
84 | bool remove; |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
85 | }; |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
86 | |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
87 | /** |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
88 | * Internal iterator struct - use CxMutIterator. |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
89 | */ |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
90 | struct cx_mut_iterator_s { |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
91 | |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
92 | /** |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
93 | * The base properties of this iterator. |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
94 | */ |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
95 | struct cx_iterator_base_s base; |
495
2856c74e18ba
add the feature to remove items during iteration
Mike Becker <universe@uap-core.de>
parents:
494
diff
changeset
|
96 | |
2856c74e18ba
add the feature to remove items during iteration
Mike Becker <universe@uap-core.de>
parents:
494
diff
changeset
|
97 | /** |
2856c74e18ba
add the feature to remove items during iteration
Mike Becker <universe@uap-core.de>
parents:
494
diff
changeset
|
98 | * Handle for the current element, if required. |
2856c74e18ba
add the feature to remove items during iteration
Mike Becker <universe@uap-core.de>
parents:
494
diff
changeset
|
99 | */ |
2856c74e18ba
add the feature to remove items during iteration
Mike Becker <universe@uap-core.de>
parents:
494
diff
changeset
|
100 | void *elem_handle; |
2856c74e18ba
add the feature to remove items during iteration
Mike Becker <universe@uap-core.de>
parents:
494
diff
changeset
|
101 | |
2856c74e18ba
add the feature to remove items during iteration
Mike Becker <universe@uap-core.de>
parents:
494
diff
changeset
|
102 | /** |
2856c74e18ba
add the feature to remove items during iteration
Mike Becker <universe@uap-core.de>
parents:
494
diff
changeset
|
103 | * Handle for the source collection, if any. |
2856c74e18ba
add the feature to remove items during iteration
Mike Becker <universe@uap-core.de>
parents:
494
diff
changeset
|
104 | */ |
2856c74e18ba
add the feature to remove items during iteration
Mike Becker <universe@uap-core.de>
parents:
494
diff
changeset
|
105 | void *src_handle; |
2856c74e18ba
add the feature to remove items during iteration
Mike Becker <universe@uap-core.de>
parents:
494
diff
changeset
|
106 | |
2856c74e18ba
add the feature to remove items during iteration
Mike Becker <universe@uap-core.de>
parents:
494
diff
changeset
|
107 | /** |
551
2946e13c89a4
#189 implement map iterators
Mike Becker <universe@uap-core.de>
parents:
516
diff
changeset
|
108 | * Field for storing a key-value pair. |
2946e13c89a4
#189 implement map iterators
Mike Becker <universe@uap-core.de>
parents:
516
diff
changeset
|
109 | * May be used by iterators that iterate over k/v-collections. |
2946e13c89a4
#189 implement map iterators
Mike Becker <universe@uap-core.de>
parents:
516
diff
changeset
|
110 | */ |
2946e13c89a4
#189 implement map iterators
Mike Becker <universe@uap-core.de>
parents:
516
diff
changeset
|
111 | struct { |
2946e13c89a4
#189 implement map iterators
Mike Becker <universe@uap-core.de>
parents:
516
diff
changeset
|
112 | /** |
2946e13c89a4
#189 implement map iterators
Mike Becker <universe@uap-core.de>
parents:
516
diff
changeset
|
113 | * A pointer to the key. |
2946e13c89a4
#189 implement map iterators
Mike Becker <universe@uap-core.de>
parents:
516
diff
changeset
|
114 | */ |
630
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
115 | void const *key; |
551
2946e13c89a4
#189 implement map iterators
Mike Becker <universe@uap-core.de>
parents:
516
diff
changeset
|
116 | /** |
2946e13c89a4
#189 implement map iterators
Mike Becker <universe@uap-core.de>
parents:
516
diff
changeset
|
117 | * A pointer to the value. |
2946e13c89a4
#189 implement map iterators
Mike Becker <universe@uap-core.de>
parents:
516
diff
changeset
|
118 | */ |
2946e13c89a4
#189 implement map iterators
Mike Becker <universe@uap-core.de>
parents:
516
diff
changeset
|
119 | void *value; |
2946e13c89a4
#189 implement map iterators
Mike Becker <universe@uap-core.de>
parents:
516
diff
changeset
|
120 | } kv_data; |
2946e13c89a4
#189 implement map iterators
Mike Becker <universe@uap-core.de>
parents:
516
diff
changeset
|
121 | |
2946e13c89a4
#189 implement map iterators
Mike Becker <universe@uap-core.de>
parents:
516
diff
changeset
|
122 | /** |
2946e13c89a4
#189 implement map iterators
Mike Becker <universe@uap-core.de>
parents:
516
diff
changeset
|
123 | * Field for storing a slot number. |
2946e13c89a4
#189 implement map iterators
Mike Becker <universe@uap-core.de>
parents:
516
diff
changeset
|
124 | * May be used by iterators that iterate over multi-bucket collections. |
2946e13c89a4
#189 implement map iterators
Mike Becker <universe@uap-core.de>
parents:
516
diff
changeset
|
125 | */ |
2946e13c89a4
#189 implement map iterators
Mike Becker <universe@uap-core.de>
parents:
516
diff
changeset
|
126 | size_t slot; |
2946e13c89a4
#189 implement map iterators
Mike Becker <universe@uap-core.de>
parents:
516
diff
changeset
|
127 | |
2946e13c89a4
#189 implement map iterators
Mike Becker <universe@uap-core.de>
parents:
516
diff
changeset
|
128 | /** |
495
2856c74e18ba
add the feature to remove items during iteration
Mike Becker <universe@uap-core.de>
parents:
494
diff
changeset
|
129 | * If the iterator is position-aware, contains the index of the element in the underlying collection. |
2856c74e18ba
add the feature to remove items during iteration
Mike Becker <universe@uap-core.de>
parents:
494
diff
changeset
|
130 | * Otherwise, this field is usually uninitialized. |
2856c74e18ba
add the feature to remove items during iteration
Mike Becker <universe@uap-core.de>
parents:
494
diff
changeset
|
131 | */ |
2856c74e18ba
add the feature to remove items during iteration
Mike Becker <universe@uap-core.de>
parents:
494
diff
changeset
|
132 | size_t index; |
630
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
133 | }; |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
134 | |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
135 | /** |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
136 | * Mutating iterator value type. |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
137 | * |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
138 | * An iterator points to a certain element in an (possibly unbounded) chain of elements. |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
139 | * Iterators that are based on collections (which have a defined "first" element), are supposed |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
140 | * to be "position-aware", which means that they keep track of the current index within the collection. |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
141 | * |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
142 | * @note Objects that are pointed to by an iterator are mutable through that iterator. However, if the |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
143 | * iterator is based on a collection and the underlying collection is mutated by other means than this iterator |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
144 | * (e.g. elements added or removed), the iterator becomes invalid (regardless of what cxIteratorValid() returns) |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
145 | * and MUST be re-obtained from the collection. |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
146 | * |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
147 | * @see CxIterator |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
148 | */ |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
149 | typedef struct cx_mut_iterator_s CxMutIterator; |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
150 | |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
151 | /** |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
152 | * Internal iterator struct - use CxIterator. |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
153 | */ |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
154 | struct cx_iterator_s { |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
155 | |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
156 | /** |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
157 | * The base properties of this iterator. |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
158 | */ |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
159 | struct cx_iterator_base_s base; |
495
2856c74e18ba
add the feature to remove items during iteration
Mike Becker <universe@uap-core.de>
parents:
494
diff
changeset
|
160 | |
2856c74e18ba
add the feature to remove items during iteration
Mike Becker <universe@uap-core.de>
parents:
494
diff
changeset
|
161 | /** |
630
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
162 | * Handle for the current element, if required. |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
163 | */ |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
164 | void *elem_handle; |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
165 | |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
166 | /** |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
167 | * Handle for the source collection, if any. |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
168 | */ |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
169 | void const *src_handle; |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
170 | |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
171 | /** |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
172 | * Field for storing a key-value pair. |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
173 | * May be used by iterators that iterate over k/v-collections. |
495
2856c74e18ba
add the feature to remove items during iteration
Mike Becker <universe@uap-core.de>
parents:
494
diff
changeset
|
174 | */ |
630
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
175 | struct { |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
176 | /** |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
177 | * A pointer to the key. |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
178 | */ |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
179 | void const *key; |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
180 | /** |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
181 | * A pointer to the value. |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
182 | */ |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
183 | void *value; |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
184 | } kv_data; |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
185 | |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
186 | /** |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
187 | * Field for storing a slot number. |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
188 | * May be used by iterators that iterate over multi-bucket collections. |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
189 | */ |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
190 | size_t slot; |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
191 | |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
192 | /** |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
193 | * If the iterator is position-aware, contains the index of the element in the underlying collection. |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
194 | * Otherwise, this field is usually uninitialized. |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
195 | */ |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
196 | size_t index; |
494
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
197 | }; |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
198 | |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
199 | /** |
500
eb9e7bd40a8e
do not hide pointers behind typedefs
Mike Becker <universe@uap-core.de>
parents:
497
diff
changeset
|
200 | * Iterator value type. |
eb9e7bd40a8e
do not hide pointers behind typedefs
Mike Becker <universe@uap-core.de>
parents:
497
diff
changeset
|
201 | * An iterator points to a certain element in an (possibly unbounded) chain of elements. |
eb9e7bd40a8e
do not hide pointers behind typedefs
Mike Becker <universe@uap-core.de>
parents:
497
diff
changeset
|
202 | * Iterators that are based on collections (which have a defined "first" element), are supposed |
eb9e7bd40a8e
do not hide pointers behind typedefs
Mike Becker <universe@uap-core.de>
parents:
497
diff
changeset
|
203 | * to be "position-aware", which means that they keep track of the current index within the collection. |
eb9e7bd40a8e
do not hide pointers behind typedefs
Mike Becker <universe@uap-core.de>
parents:
497
diff
changeset
|
204 | * |
630
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
205 | * @note Objects that are pointed to by an iterator are always mutable through that iterator. However, |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
206 | * this iterator cannot mutate the collection itself (add or remove elements) and any mutation of the |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
207 | * collection by other means make this iterator invalid (regardless of what cxIteratorValid() returns). |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
208 | * |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
209 | * @see CxMutIterator |
500
eb9e7bd40a8e
do not hide pointers behind typedefs
Mike Becker <universe@uap-core.de>
parents:
497
diff
changeset
|
210 | */ |
eb9e7bd40a8e
do not hide pointers behind typedefs
Mike Becker <universe@uap-core.de>
parents:
497
diff
changeset
|
211 | typedef struct cx_iterator_s CxIterator; |
eb9e7bd40a8e
do not hide pointers behind typedefs
Mike Becker <universe@uap-core.de>
parents:
497
diff
changeset
|
212 | |
eb9e7bd40a8e
do not hide pointers behind typedefs
Mike Becker <universe@uap-core.de>
parents:
497
diff
changeset
|
213 | /** |
494
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
214 | * Checks if the iterator points to valid data. |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
215 | * |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
216 | * This is especially false for past-the-end iterators. |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
217 | * |
630
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
218 | * @param iter the iterator |
494
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
219 | * @return true iff the iterator points to valid data |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
220 | */ |
630
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
221 | #define cxIteratorValid(iter) (iter).base.valid(&(iter)) |
494
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
222 | |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
223 | /** |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
224 | * Returns a pointer to the current element. |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
225 | * |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
226 | * The behavior is undefined if this iterator is invalid. |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
227 | * |
630
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
228 | * @param iter the iterator |
494
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
229 | * @return a pointer to the current element |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
230 | */ |
630
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
231 | #define cxIteratorCurrent(iter) (iter).base.current(&iter) |
494
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
232 | |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
233 | /** |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
234 | * Advances the iterator to the next element. |
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
235 | * |
630
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
236 | * @param iter the iterator |
494
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
237 | */ |
630
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
238 | #define cxIteratorNext(iter) (iter).base.next(&iter) |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
239 | |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
240 | /** |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
241 | * Flags the current element for removal. |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
242 | * |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
243 | * @param iter the iterator |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
244 | * @return false if this iterator cannot remove the element |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
245 | */ |
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
246 | #define cxIteratorFlagRemoval(iter) (iter).base.flag_removal(&iter) |
494
6ce8cfa10a96
add iterator interface + linked list iterator
Mike Becker <universe@uap-core.de>
parents:
diff
changeset
|
247 | |
496 | 248 | /** |
249 | * Loops over an iterator. | |
250 | * @param type the type of the elements | |
251 | * @param elem the name of the iteration variable | |
252 | * @param iter the iterator | |
253 | */ | |
254 | #define cx_foreach(type, elem, iter) \ | |
630
ac5e7f789048
separate iterators and mutating iterators
Mike Becker <universe@uap-core.de>
parents:
628
diff
changeset
|
255 | for (type elem; cxIteratorValid(iter) && (elem = (type)cxIteratorCurrent(iter)) != NULL ; cxIteratorNext(iter)) |
496 | 256 | |
628
1e2be40f0cb5
use //-style single line comments everywhere
Mike Becker <universe@uap-core.de>
parents:
551
diff
changeset
|
257 | #endif // UCX_ITERATOR_H |