Mercurial > hg > ucx / changeset

--- a/docs/src/features.md	Fri Jul 07 17:11:15 2023 +0200
+++ b/docs/src/features.md	Fri Jul 07 17:28:07 2023 +0200
@@ -182,6 +182,24 @@
 
 *Header file:* [iterator.h](api/iterator_8h.html)
 
+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).
+
+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.
+This is, what the `CxMutIterator` is for.
+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 in your `next` method, or
+make the implementation of the `flag_removal` method always return `false`.
+
 ## Collection
 
 *Header file:* [collection.h](api/collection_8h.html)