Mercurial > hg > ucx / file diff

--- a/src/cx/iterator.h	Wed Jan 01 13:31:38 2025 +0100
+++ b/src/cx/iterator.h	Wed Jan 01 14:03:49 2025 +0100
@@ -230,11 +230,16 @@
  * The \p array can be \c NULL in which case the iterator will be immediately
  * initialized such that #cxIteratorValid() returns \c false.
  *
+ * This iterator yields the addresses of the array elements.
+ * If you want to iterator over an array of pointers, you can
+ * use cxIteratorPtr() to create an iterator which directly
+ * yields the stored pointers.
  *
  * @param array a pointer to the array (can be \c NULL)
  * @param elem_size the size of one array element
  * @param elem_count the number of elements in the array
  * @return an iterator for the specified array
+ * @see cxIteratorPtr()
  */
 cx_attr_nodiscard
 CxIterator cxIterator(
@@ -274,6 +279,46 @@
         bool remove_keeps_order
 );
 
+/**
+ * Creates an iterator for the specified plain pointer array.
+ *
+ * This iterator assumes that every element in the array is a pointer
+ * and yields exactly those pointers during iteration (while in contrast
+ * an iterator created with cxIterator() would return the addresses
+ * of those pointers within the array).
+ *
+ * @param array a pointer to the array (can be \c NULL)
+ * @param elem_count the number of elements in the array
+ * @return an iterator for the specified array
+ * @see cxIterator()
+ */
+cx_attr_nodiscard
+CxIterator cxIteratorPtr(
+        const void *array,
+        size_t elem_count
+);
+
+/**
+ * Creates a mutating iterator for the specified plain pointer array.
+ *
+ * This is the mutating variant of cxIteratorPtr(). See also
+ * cxMutIterator().
+ *
+ * @param array a pointer to the array (can be \c NULL)
+ * @param elem_count the number of elements in the array
+ * @param remove_keeps_order \c true if the order of elements must be preserved
+ * when removing an element
+ * @return an iterator for the specified array
+ * @see cxMutIterator()
+ * @see cxIteratorPtr()
+ */
+cx_attr_nodiscard
+CxIterator cxMutIteratorPtr(
+        void *array,
+        size_t elem_count,
+        bool remove_keeps_order
+);
+
 #ifdef __cplusplus
 } // extern "C"
 #endif