# HG changeset patch
# User Mike Becker <universe@uap-core.de>
# Date 1708197733 -3600
# Node ID 88fa3381206d99949f4a88eeb1df01a00ed6a3fb
# Parent  13b40a598d164da6b2c6f7f3759c95198e750d2e
improve tree iterator struct and add signature for a function that can create an iterator

relates to #371

diff -r 13b40a598d16 -r 88fa3381206d src/cx/tree.h
--- a/src/cx/tree.h	Fri Feb 16 20:23:48 2024 +0100
+++ b/src/cx/tree.h	Sat Feb 17 20:22:13 2024 +0100
@@ -125,6 +125,14 @@
      * call cxTreeIteratorDispose().
      */
     void **stack;
+    /**
+     * Internal capacity of the stack.
+     */
+    size_t stack_capacity;
+    /**
+     * Current depth.
+     */
+    size_t depth;
 } CxTreeIterator;
 
 /**
@@ -241,6 +249,42 @@
         ptrdiff_t loc_next
 );
 
+/**
+ * Creates an iterator for a tree with the specified root node.
+ *
+ * The \p passes argument is supposed to be a combination of the flags
+ * #CX_TREE_ITERATOR_ENTER, #CX_TREE_ITERATOR_NEXT_CHILD, and #CX_TREE_ITERATOR_EXIT.
+ * Alternatively, the integer 1 is equivalent to just specifying #CX_TREE_ITERATOR_ENTER
+ * which will cause the iterator to pass every node only once (when entering the node).
+ *
+ * When #CX_TREE_ITERATOR_EXIT is set, the iterator will visit a parent node again,
+ * when \em every of it's children has been visited (including the case when the node does not have any children).
+ *
+ * When #CX_TREE_ITERATOR_NEXT_CHILD is set, the iterator will visit a parent node again,
+ * when advancing from one child to the next.
+ *
+ * @note A tree iterator needs to maintain a stack of visited nodes, which is allocated using stdlib malloc().
+ * When the iterator becomes invalid, this memory is automatically released. However, if you wish to cancel the
+ * iteration before the iterator becomes invalid by itself, you MUST call cxTreeIteratorDispose() manually to release
+ * the memory.
+ *
+ * @remark At the moment, the returned iterator does not support cxIteratorFlagRemoval().
+ *
+ * @param root the root node
+ * @param passes the passes this iterator shall perform
+ * @param loc_children offset in the node struct for the children linked list
+ * @param loc_next offset in the node struct for the next pointer
+ * @return the new tree iterator
+ * @see cxTreeIteratorDispose()
+ */
+__attribute__((__nonnull__))
+CxTreeIterator cx_tree_iterate(
+        void const *root,
+        int passes,
+        ptrdiff_t loc_children,
+        ptrdiff_t loc_next
+);
+
 #ifdef __cplusplus
 } // extern "C"
 #endif