comparison: src/cx/iterator.h
src/cx/iterator.h
- changeset 494
- 6ce8cfa10a96
- child 495
- 2856c74e18ba
equal
deleted
inserted
replaced
| 493:e3469b497eff | 494:6ce8cfa10a96 |
|---|---|
| 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 * \version 3.0 | |
| 34 * \copyright 2-Clause BSD License | |
| 35 */ | |
| 36 | |
| 37 #ifndef UCX_ITERATOR_H | |
| 38 #define UCX_ITERATOR_H | |
| 39 | |
| 40 #include "common.h" | |
| 41 | |
| 42 /** | |
| 43 * Iterator value type. | |
| 44 * An iterator points to a certain element in an (possibly unbounded) chain of elements. | |
| 45 * Iterators that are based on collections (which have a defined "first" element), are supposed | |
| 46 * to be "position-aware", which means that they keep track of the current index within the collection. | |
| 47 * | |
| 48 * @note Objects that are pointed to by an iterator are mutable through that iterator. However, if the | |
| 49 * iterator is based on a collection and the underlying collection is mutated (elements added or removed), | |
| 50 * the iterator becomes invalid (regardless of what cxIteratorValid() returns) and MUST be re-obtained | |
| 51 * from the collection. | |
| 52 */ | |
| 53 typedef struct cx_iterator_s CxIterator; | |
| 54 | |
| 55 /** | |
| 56 * Internal iterator struct - use CxIterator. | |
| 57 */ | |
| 58 struct cx_iterator_s { | |
| 59 /** | |
| 60 * If the iterator is position-aware, contains the index of the element in the underlying collection. | |
| 61 * Otherwise, this field is usually uninitialized. | |
| 62 */ | |
| 63 size_t index; | |
| 64 /** | |
| 65 * Internal data. | |
| 66 */ | |
| 67 void *data; | |
| 68 | |
| 69 /** | |
| 70 * True iff the iterator points to valid data. | |
| 71 */ | |
| 72 bool (*valid)(CxIterator const *) __attribute__ ((__nonnull__)); | |
| 73 | |
| 74 /** | |
| 75 * Returns a pointer to the current element. | |
| 76 */ | |
| 77 void *(*current)(CxIterator const *) __attribute__ ((__nonnull__)); | |
| 78 | |
| 79 /** | |
| 80 * Advances the iterator. | |
| 81 */ | |
| 82 void (*next)(CxIterator *) __attribute__ ((__nonnull__)); | |
| 83 }; | |
| 84 | |
| 85 /** | |
| 86 * Checks if the iterator points to valid data. | |
| 87 * | |
| 88 * This is especially false for past-the-end iterators. | |
| 89 * | |
| 90 * @param iter the iterator | |
| 91 * @return true iff the iterator points to valid data | |
| 92 */ | |
| 93 __attribute__ ((__nonnull__)) | |
| 94 static inline bool cxIteratorValid(CxIterator const *iter) { | |
| 95 return iter->valid(iter); | |
| 96 } | |
| 97 | |
| 98 /** | |
| 99 * Returns a pointer to the current element. | |
| 100 * | |
| 101 * The behavior is undefined if this iterator is invalid. | |
| 102 * | |
| 103 * @param iter the iterator | |
| 104 * @return a pointer to the current element | |
| 105 */ | |
| 106 __attribute__ ((__nonnull__)) | |
| 107 static inline void *cxIteratorCurrent(CxIterator const *iter) { | |
| 108 return iter->current(iter); | |
| 109 } | |
| 110 | |
| 111 /** | |
| 112 * Advances the iterator to the next element. | |
| 113 * | |
| 114 * @param iter the iterator | |
| 115 */ | |
| 116 __attribute__ ((__nonnull__)) | |
| 117 static inline void cxIteratorNext(CxIterator *iter) { | |
| 118 iter->next(iter); | |
| 119 } | |
| 120 | |
| 121 #endif /* UCX_ITERATOR_H */ |
