Mercurial > hg > ucx / changeset

     1.1 --- a/src/cx/tree.h	Fri Feb 16 20:23:48 2024 +0100
     1.2 +++ b/src/cx/tree.h	Sat Feb 17 20:22:13 2024 +0100
     1.3 @@ -125,6 +125,14 @@
     1.4       * call cxTreeIteratorDispose().
     1.5       */
     1.6      void **stack;
     1.7 +    /**
     1.8 +     * Internal capacity of the stack.
     1.9 +     */
    1.10 +    size_t stack_capacity;
    1.11 +    /**
    1.12 +     * Current depth.
    1.13 +     */
    1.14 +    size_t depth;
    1.15  } CxTreeIterator;
    1.16  
    1.17  /**
    1.18 @@ -241,6 +249,42 @@
    1.19          ptrdiff_t loc_next
    1.20  );
    1.21  
    1.22 +/**
    1.23 + * Creates an iterator for a tree with the specified root node.
    1.24 + *
    1.25 + * The \p passes argument is supposed to be a combination of the flags
    1.26 + * #CX_TREE_ITERATOR_ENTER, #CX_TREE_ITERATOR_NEXT_CHILD, and #CX_TREE_ITERATOR_EXIT.
    1.27 + * Alternatively, the integer 1 is equivalent to just specifying #CX_TREE_ITERATOR_ENTER
    1.28 + * which will cause the iterator to pass every node only once (when entering the node).
    1.29 + *
    1.30 + * When #CX_TREE_ITERATOR_EXIT is set, the iterator will visit a parent node again,
    1.31 + * when \em every of it's children has been visited (including the case when the node does not have any children).
    1.32 + *
    1.33 + * When #CX_TREE_ITERATOR_NEXT_CHILD is set, the iterator will visit a parent node again,
    1.34 + * when advancing from one child to the next.
    1.35 + *
    1.36 + * @note A tree iterator needs to maintain a stack of visited nodes, which is allocated using stdlib malloc().
    1.37 + * When the iterator becomes invalid, this memory is automatically released. However, if you wish to cancel the
    1.38 + * iteration before the iterator becomes invalid by itself, you MUST call cxTreeIteratorDispose() manually to release
    1.39 + * the memory.
    1.40 + *
    1.41 + * @remark At the moment, the returned iterator does not support cxIteratorFlagRemoval().
    1.42 + *
    1.43 + * @param root the root node
    1.44 + * @param passes the passes this iterator shall perform
    1.45 + * @param loc_children offset in the node struct for the children linked list
    1.46 + * @param loc_next offset in the node struct for the next pointer
    1.47 + * @return the new tree iterator
    1.48 + * @see cxTreeIteratorDispose()
    1.49 + */
    1.50 +__attribute__((__nonnull__))
    1.51 +CxTreeIterator cx_tree_iterate(
    1.52 +        void const *root,
    1.53 +        int passes,
    1.54 +        ptrdiff_t loc_children,
    1.55 +        ptrdiff_t loc_next
    1.56 +);
    1.57 +
    1.58  #ifdef __cplusplus
    1.59  } // extern "C"
    1.60  #endif