# HG changeset patch # User Mike Becker # Date 1688743687 -7200 # Node ID 2ed01495f838d8a7c3b65b0dbb63089d9efe0862 # Parent a3b5f27ad956b5a129233e8f9d96114164f530e1 add iterator documentation diff -r a3b5f27ad956 -r 2ed01495f838 docs/src/features.md --- 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)