Mercurial > hg > ucx / file diff

--- a/docs/Writerside/topics/iterator.h.md	Fri Oct 17 15:04:56 2025 +0200
+++ b/docs/Writerside/topics/iterator.h.md	Fri Oct 17 16:53:24 2025 +0200
@@ -27,23 +27,18 @@
 #include <cx/iterator.h>
 
 CxIterator cxIterator(const void *array,
-        size_t elem_size, size_t elem_count);
-        
-CxIterator cxMutIterator(void *array,
-        size_t elem_size, size_t elem_count, bool remove_keeps_order);
-        
-CxIterator cxIteratorPtr(const void *array, size_t elem_count);
-        
-CxIterator cxMutIteratorPtr(void *array, size_t elem_count,
+        size_t elem_size, size_t elem_count,
+        bool remove_keeps_order);
+       
+CxIterator cxIteratorPtr(const void *array,
+        size_t elem_count,
         bool remove_keeps_order);
 ```
 
 The `cxIterator()` function creates an iterator over the elements of `array` where
 each element is `elem_size` bytes large and the array contains a total of `elem_count` elements.
-The `cxMutIterator()` function creates an equivalent [mutating iterator](#mutating-iterators). 
 
-The `cxIteratorPtr()` and `cxMutIteratorPtr()` functions are equivalent to
-the `cxIteratorPtr()` and `cxMutIteratorPtr()`, except they assume `sizeof(void*)` as the `elem_size`.
+The `cxIteratorPtr()` function is equivalent to `cxIterator()`, except it assumes `sizeof(void*)` as the `elem_size`.
 
 The UCX collections also define functions for creating iterators over their items.
 You can read more about them in the respective Sections of the documentation.
@@ -86,15 +81,13 @@
 > You should read the documentation of the function creating the iterator to learn
 > what exactly the iterator is iterating over.
 
-## Mutating Iterators
+## Removing Elements via Iterators
 
 Usually an iterator is not mutating the collection it is iterating over.
 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.
-On mutating iterators the `mutating` flag in the base structure is set to `true`,
-and 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.
+For this purpose, most collections allow to use `cxIteratorFlagRemoval()`, which instructs the iterator to remove
+the current element from the collection on the next call to `cxIteratorNext()`.
 If you are implementing your own iterator, it is up to you to implement this behavior.
 
 ## Passing Iterators to Functions
@@ -127,9 +120,10 @@
 struct cx_iterator_base_s {
     bool (*valid)(const void *);
     void *(*current)(const void *);
+    void (*next)(void *);
     void *(*current_impl)(const void *);
-    void (*next)(void *);
-    bool mutating;
+    void (*next_impl)(void *);
+    bool allow_remove;
     bool remove;
 };
 
@@ -139,14 +133,17 @@
 The `valid` function indicates whether the iterator is currently pointing to an element in the collection.
 The `current` function is supposed to return that element,
 and the `next` function shall advance the iterator to the next element.
-The booleans `mutating` and `remove` are used for [mutating iterators](#mutating-iterators) as explained above.
 
-Iterators may be wrapped in which case the original implementation can be stored in `current_impl` and
-called by a wrapper implementation pointed to by `current`.
+The booleans `allow_remove` and `remove` are used for [removing elements](#removing-elements-via-iterators) as explained above.
+When an iterator is created, the `allow_remove` field is set to indicate if removal of elements is supported.
+The `remove` field is set to indicate if the current element should be removed on the next call to `next()` (see `cxIteratorFlagRemoval()`).
+
+Iterators may be wrapped in which case the original implementation can be stored in `current_impl` and `next_impl`.
+They can then be called by a wrapper implementation pointed to by `current` and `next`, respectively.
 This can be useful when you want to support the `store_pointer` field of the [](collection.h.md) API.
 
 A specialized, simple, and fast iterator over an array of a certain type
-that does not support mutation can be implemented as follows:
+that does not support removing elements can be implemented as follows:
 ```C
 #include <cx/iterator.h>
 
@@ -184,7 +181,7 @@
     iter.base.current = my_foo_iter_current;
     iter.base.next = my_foo_iter_next;
     iter.base.remove = false;
-    iter.base.mutating = false;
+    iter.base.allow_remove = false;
     
     // custom fields
     iter.index = 0;