docs/Writerside/topics/iterator.h.md

# Iterators

<warning>
Outdated - Rewrite!
</warning>

In UCX 3 a new feature has been introduced to write own iterators, that work with the `cx_foreach` macro.
In previous UCX releases there were different hard-coded foreach macros for lists and maps that were not customizable.
Now, creating an iterator is as simple as creating a `CxIterator` struct and setting the fields in a meaningful way.

You do not always need all fields in the iterator structure, depending on your use case.
Sometimes you only need the `index` (for example when iterating over simple lists), and other times you will need the
`slot` and `kv_data` fields (for example when iterating over maps).

If the predefined fields are insufficient for your use case, you can alternatively create your own iterator structure
and place the `CX_ITERATOR_BASE` macro as first member of that structure.

Usually an iterator is not mutating the collection it is iterating over.
In some programming languages it is even disallowed to change the collection while iterating with foreach.
But sometimes it is desirable to remove an element from the collection while iterating over it.
For this purpose, most collections allow the creation of a _mutating_ iterator.
The only differences are, that the `mutating` flag is `true` and the `src_handle` is not const.
On mutating iterators it is allowed to call the `cxFlagForRemoval()` function, which instructs the iterator to remove
the current element from the collection on the next call to `cxIteratorNext()` and clear the flag afterward.
If you are implementing your own iterator, it is up to you to implement this behavior.

## Undocumented Symbols (TODO)
### cxIterator
### cxIteratorPtr
### cxMutIterator
### cxMutIteratorPtr