Mercurial > hg > ucx / changeset

     1.1 --- a/docs/src/features.md	Fri Jul 07 17:11:15 2023 +0200
     1.2 +++ b/docs/src/features.md	Fri Jul 07 17:28:07 2023 +0200
     1.3 @@ -182,6 +182,24 @@
     1.4  
     1.5  *Header file:* [iterator.h](api/iterator_8h.html)
     1.6  
     1.7 +In UCX 3 a new feature has been introduced to write own iterators, that work with the `cx_foreach` macro.
     1.8 +In previous UCX releases there were different hard-coded foreach macros for lists and maps that were not customizable.
     1.9 +Now, creating an iterator is as simple as creating a `CxIterator` struct and setting the fields in a meaningful way.
    1.10 +
    1.11 +You do not always need all fields in the iterator structure, depending on your use case.
    1.12 +Sometimes you only need the `index` (for example when iterating over simple lists), and other times you will need the
    1.13 +`slot` and `kv_data` fields (for example when iterating over maps).
    1.14 +
    1.15 +Usually an iterator is not mutating the collection it is iterating over.
    1.16 +In some programming languages it is even disallowed to change the collection while iterating with foreach.
    1.17 +But sometimes it is desirable to remove an element from the collection while iterating over it.
    1.18 +This is, what the `CxMutIterator` is for.
    1.19 +The only differences are, that the `mutating` flag is `true` and the `src_handle` is not const.
    1.20 +On mutating iterators it is allowed to call the `cxFlagForRemoval()` function, which instructs the iterator to remove
    1.21 +the current element from the collection on the next call to `cxIteratorNext()` and clear the flag afterward.
    1.22 +If you are implementing your own iterator, it is up to you to implement this behavior in your `next` method, or
    1.23 +make the implementation of the `flag_removal` method always return `false`.
    1.24 +
    1.25  ## Collection
    1.26  
    1.27  *Header file:* [collection.h](api/collection_8h.html)