comparison: docs/Writerside/topics/iterator.h.md
docs/Writerside/topics/iterator.h.md
- branch
- docs/3.1
- changeset 1141
- a06a2d27c043
- child 1142
- 9437530176bc
equal
deleted
inserted
replaced
| 1140:88a9ee79c102 | 1141:a06a2d27c043 |
|---|---|
| 1 # iterator.h | |
| 2 | |
| 3 In UCX 3 a new feature has been introduced to write own iterators, that work with the `cx_foreach` macro. | |
| 4 In previous UCX releases there were different hard-coded foreach macros for lists and maps that were not customizable. | |
| 5 Now, creating an iterator is as simple as creating a `CxIterator` struct and setting the fields in a meaningful way. | |
| 6 | |
| 7 You do not always need all fields in the iterator structure, depending on your use case. | |
| 8 Sometimes you only need the `index` (for example when iterating over simple lists), and other times you will need the | |
| 9 `slot` and `kv_data` fields (for example when iterating over maps). | |
| 10 | |
| 11 If the predefined fields are insufficient for your use case, you can alternatively create your own iterator structure | |
| 12 and place the `CX_ITERATOR_BASE` macro as first member of that structure. | |
| 13 | |
| 14 Usually an iterator is not mutating the collection it is iterating over. | |
| 15 In some programming languages it is even disallowed to change the collection while iterating with foreach. | |
| 16 But sometimes it is desirable to remove an element from the collection while iterating over it. | |
| 17 For this purpose, most collections allow the creation of a _mutating_ iterator. | |
| 18 The only differences are, that the `mutating` flag is `true` and the `src_handle` is not const. | |
| 19 On mutating iterators it is allowed to call the `cxFlagForRemoval()` function, which instructs the iterator to remove | |
| 20 the current element from the collection on the next call to `cxIteratorNext()` and clear the flag afterward. | |
| 21 If you are implementing your own iterator, it is up to you to implement this behavior. |
