comparison: src/cx/iterator.h
src/cx/iterator.h
- changeset 500
- eb9e7bd40a8e
- parent 497
- b182a8b8a1af
- child 516
- 7bcea73303ce
equal
deleted
inserted
replaced
| 499:3dc9075df822 | 500:eb9e7bd40a8e |
|---|---|
| 38 #define UCX_ITERATOR_H | 38 #define UCX_ITERATOR_H |
| 39 | 39 |
| 40 #include "common.h" | 40 #include "common.h" |
| 41 | 41 |
| 42 /** | 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. | 43 * Internal iterator struct - use CxIterator. |
| 57 */ | 44 */ |
| 58 struct cx_iterator_s { | 45 struct cx_iterator_s { |
| 59 /** | 46 /** |
| 60 * True iff the iterator points to valid data. | 47 * True iff the iterator points to valid data. |
| 61 */ | 48 */ |
| 62 bool (*valid)(CxIterator const *) __attribute__ ((__nonnull__)); | 49 bool (*valid)(struct cx_iterator_s const *) __attribute__ ((__nonnull__)); |
| 63 | 50 |
| 64 /** | 51 /** |
| 65 * Returns a pointer to the current element. | 52 * Returns a pointer to the current element. |
| 66 */ | 53 */ |
| 67 void *(*current)(CxIterator const *) __attribute__ ((__nonnull__)); | 54 void *(*current)(struct cx_iterator_s const *) __attribute__ ((__nonnull__)); |
| 68 | 55 |
| 69 /** | 56 /** |
| 70 * Advances the iterator. | 57 * Advances the iterator. |
| 71 */ | 58 */ |
| 72 void (*next)(CxIterator *) __attribute__ ((__nonnull__)); | 59 void (*next)(struct cx_iterator_s *) __attribute__ ((__nonnull__)); |
| 73 | 60 |
| 74 /** | 61 /** |
| 75 * Handle for the current element, if required. | 62 * Handle for the current element, if required. |
| 76 */ | 63 */ |
| 77 void *elem_handle; | 64 void *elem_handle; |
| 92 * when the iterator advances. | 79 * when the iterator advances. |
| 93 * Has no effect on iterators that are not based on a collection. | 80 * Has no effect on iterators that are not based on a collection. |
| 94 */ | 81 */ |
| 95 bool remove; | 82 bool remove; |
| 96 }; | 83 }; |
| 84 | |
| 85 /** | |
| 86 * Iterator value type. | |
| 87 * An iterator points to a certain element in an (possibly unbounded) chain of elements. | |
| 88 * Iterators that are based on collections (which have a defined "first" element), are supposed | |
| 89 * to be "position-aware", which means that they keep track of the current index within the collection. | |
| 90 * | |
| 91 * @note Objects that are pointed to by an iterator are mutable through that iterator. However, if the | |
| 92 * iterator is based on a collection and the underlying collection is mutated (elements added or removed), | |
| 93 * the iterator becomes invalid (regardless of what cxIteratorValid() returns) and MUST be re-obtained | |
| 94 * from the collection. | |
| 95 */ | |
| 96 typedef struct cx_iterator_s CxIterator; | |
| 97 | 97 |
| 98 /** | 98 /** |
| 99 * Checks if the iterator points to valid data. | 99 * Checks if the iterator points to valid data. |
| 100 * | 100 * |
| 101 * This is especially false for past-the-end iterators. | 101 * This is especially false for past-the-end iterators. |
