comparison: ucx/cx/iterator.h
ucx/cx/iterator.h
- changeset 854
- 1c8401ece69e
- parent 852
- 83fdf679df99
equal
deleted
inserted
replaced
| 853:2ad93ebdc8d9 | 854:1c8401ece69e |
|---|---|
| 45 /** | 45 /** |
| 46 * Common data for all iterators. | 46 * Common data for all iterators. |
| 47 */ | 47 */ |
| 48 struct cx_iterator_base_s { | 48 struct cx_iterator_base_s { |
| 49 /** | 49 /** |
| 50 * True iff the iterator points to valid data. | 50 * True if the iterator points to valid data. |
| 51 */ | 51 */ |
| 52 cx_attr_nonnull | |
| 53 bool (*valid)(const void *); | 52 bool (*valid)(const void *); |
| 54 | 53 |
| 55 /** | 54 /** |
| 56 * Returns a pointer to the current element. | 55 * Returns a pointer to the current element. |
| 57 * | 56 * |
| 58 * When valid returns false, the behavior of this function is undefined. | 57 * When valid returns false, the behavior of this function is undefined. |
| 59 */ | 58 */ |
| 60 cx_attr_nonnull | |
| 61 cx_attr_nodiscard | |
| 62 void *(*current)(const void *); | 59 void *(*current)(const void *); |
| 63 | 60 |
| 64 /** | 61 /** |
| 65 * Original implementation in case the function needs to be wrapped. | 62 * Original implementation in case the function needs to be wrapped. |
| 66 */ | 63 */ |
| 67 cx_attr_nonnull | |
| 68 cx_attr_nodiscard | |
| 69 void *(*current_impl)(const void *); | 64 void *(*current_impl)(const void *); |
| 70 | 65 |
| 71 /** | 66 /** |
| 72 * Advances the iterator. | 67 * Advances the iterator. |
| 73 * | 68 * |
| 74 * When valid returns false, the behavior of this function is undefined. | 69 * When valid returns false, the behavior of this function is undefined. |
| 75 */ | 70 */ |
| 76 cx_attr_nonnull | |
| 77 void (*next)(void *); | 71 void (*next)(void *); |
| 78 /** | 72 /** |
| 79 * Indicates whether this iterator may remove elements. | 73 * Indicates whether this iterator may remove elements. |
| 80 */ | 74 */ |
| 81 bool mutating; | 75 bool mutating; |
| 82 /** | 76 /** |
| 83 * Internal flag for removing the current element when advancing. | 77 * Internal flag for removing the current element when advancing. |
| 84 */ | 78 */ |
| 85 bool remove; | 79 bool remove; |
| 86 }; | 80 }; |
| 81 | |
| 82 /** | |
| 83 * Convenience type definition for the base structure of an iterator. | |
| 84 * @see #CX_ITERATOR_BASE | |
| 85 */ | |
| 86 typedef struct cx_iterator_base_s CxIteratorBase; | |
| 87 | 87 |
| 88 /** | 88 /** |
| 89 * Declares base attributes for an iterator. | 89 * Declares base attributes for an iterator. |
| 90 * Must be the first member of an iterator structure. | 90 * Must be the first member of an iterator structure. |
| 91 */ | 91 */ |
| 118 */ | 118 */ |
| 119 const void *c; | 119 const void *c; |
| 120 } src_handle; | 120 } src_handle; |
| 121 | 121 |
| 122 /** | 122 /** |
| 123 * Field for storing a key-value pair. | |
| 124 * May be used by iterators that iterate over k/v-collections. | |
| 125 */ | |
| 126 struct { | |
| 127 /** | |
| 128 * A pointer to the key. | |
| 129 */ | |
| 130 const void *key; | |
| 131 /** | |
| 132 * A pointer to the value. | |
| 133 */ | |
| 134 void *value; | |
| 135 } kv_data; | |
| 136 | |
| 137 /** | |
| 138 * Field for storing a slot number. | |
| 139 * May be used by iterators that iterate over multi-bucket collections. | |
| 140 */ | |
| 141 size_t slot; | |
| 142 | |
| 143 /** | |
| 144 * If the iterator is position-aware, contains the index of the element in the underlying collection. | 123 * If the iterator is position-aware, contains the index of the element in the underlying collection. |
| 145 * Otherwise, this field is usually uninitialized. | 124 * Otherwise, this field is usually uninitialized. |
| 146 */ | 125 */ |
| 147 size_t index; | 126 size_t index; |
| 148 | 127 |
| 172 typedef struct cx_iterator_s CxIterator; | 151 typedef struct cx_iterator_s CxIterator; |
| 173 | 152 |
| 174 /** | 153 /** |
| 175 * Checks if the iterator points to valid data. | 154 * Checks if the iterator points to valid data. |
| 176 * | 155 * |
| 177 * This is especially false for past-the-end iterators. | |
| 178 * | |
| 179 * @param iter the iterator | 156 * @param iter the iterator |
| 180 * @retval true if the iterator points to valid data | 157 * @retval true if the iterator points to valid data |
| 181 * @retval false if the iterator already moved past the end | 158 * @retval false if the iterator already moved past the end |
| 182 */ | 159 */ |
| 183 #define cxIteratorValid(iter) (iter).base.valid(&(iter)) | 160 #define cxIteratorValid(iter) (iter).base.valid(&(iter)) |
| 213 * Obtains a reference to an arbitrary iterator. | 190 * Obtains a reference to an arbitrary iterator. |
| 214 * | 191 * |
| 215 * This is useful for APIs that expect some iterator as an argument. | 192 * This is useful for APIs that expect some iterator as an argument. |
| 216 * | 193 * |
| 217 * @param iter the iterator | 194 * @param iter the iterator |
| 218 * @return (@c CxIterator*) a pointer to the iterator | 195 * @return (@c struct @c cx_iterator_base_s*) a pointer to the iterator |
| 219 */ | 196 */ |
| 220 #define cxIteratorRef(iter) &((iter).base) | 197 #define cxIteratorRef(iter) &((iter).base) |
| 221 | 198 |
| 222 /** | 199 /** |
| 223 * Loops over an iterator. | 200 * Loops over an iterator. |
| 246 * @param elem_count the number of elements in the array | 223 * @param elem_count the number of elements in the array |
| 247 * @return an iterator for the specified array | 224 * @return an iterator for the specified array |
| 248 * @see cxIteratorPtr() | 225 * @see cxIteratorPtr() |
| 249 */ | 226 */ |
| 250 cx_attr_nodiscard | 227 cx_attr_nodiscard |
| 228 cx_attr_export | |
| 251 CxIterator cxIterator( | 229 CxIterator cxIterator( |
| 252 const void *array, | 230 const void *array, |
| 253 size_t elem_size, | 231 size_t elem_size, |
| 254 size_t elem_count | 232 size_t elem_count |
| 255 ); | 233 ); |
| 276 * @param remove_keeps_order @c true if the order of elements must be preserved | 254 * @param remove_keeps_order @c true if the order of elements must be preserved |
| 277 * when removing an element | 255 * when removing an element |
| 278 * @return an iterator for the specified array | 256 * @return an iterator for the specified array |
| 279 */ | 257 */ |
| 280 cx_attr_nodiscard | 258 cx_attr_nodiscard |
| 259 cx_attr_export | |
| 281 CxIterator cxMutIterator( | 260 CxIterator cxMutIterator( |
| 282 void *array, | 261 void *array, |
| 283 size_t elem_size, | 262 size_t elem_size, |
| 284 size_t elem_count, | 263 size_t elem_count, |
| 285 bool remove_keeps_order | 264 bool remove_keeps_order |
| 297 * @param elem_count the number of elements in the array | 276 * @param elem_count the number of elements in the array |
| 298 * @return an iterator for the specified array | 277 * @return an iterator for the specified array |
| 299 * @see cxIterator() | 278 * @see cxIterator() |
| 300 */ | 279 */ |
| 301 cx_attr_nodiscard | 280 cx_attr_nodiscard |
| 281 cx_attr_export | |
| 302 CxIterator cxIteratorPtr( | 282 CxIterator cxIteratorPtr( |
| 303 const void *array, | 283 const void *array, |
| 304 size_t elem_count | 284 size_t elem_count |
| 305 ); | 285 ); |
| 306 | 286 |
| 317 * @return an iterator for the specified array | 297 * @return an iterator for the specified array |
| 318 * @see cxMutIterator() | 298 * @see cxMutIterator() |
| 319 * @see cxIteratorPtr() | 299 * @see cxIteratorPtr() |
| 320 */ | 300 */ |
| 321 cx_attr_nodiscard | 301 cx_attr_nodiscard |
| 302 cx_attr_export | |
| 322 CxIterator cxMutIteratorPtr( | 303 CxIterator cxMutIteratorPtr( |
| 323 void *array, | 304 void *array, |
| 324 size_t elem_count, | 305 size_t elem_count, |
| 325 bool remove_keeps_order | 306 bool remove_keeps_order |
| 326 ); | 307 ); |
