# HG changeset patch
# User Mike Becker <universe@uap-core.de>
# Date 1742320998 -3600
# Node ID 14c227b28a969968539c53c5cb3c71b343a72e47
# Parent  b4b248a8b2d6a29e86f2ea0f18950e6dafda6e0b
basic structure for tree.h documentation

relates to #451

diff -r b4b248a8b2d6 -r 14c227b28a96 docs/Writerside/topics/tree.h.md
--- a/docs/Writerside/topics/tree.h.md	Mon Mar 17 21:06:55 2025 +0100
+++ b/docs/Writerside/topics/tree.h.md	Tue Mar 18 19:03:18 2025 +0100
@@ -1,36 +1,221 @@
 # Tree
 
 <warning>
-New Feature - will be documented soon!
+TODO: intro text
+</warning>
+
+```C
+#include <cx/tree.h>
+
+typedef void *(*cx_tree_node_create_func)(
+        const void *data, void *context);
+
+typedef int (*cx_tree_search_data_func)(
+        const void *node, const void *data);
+
+typedef int (*cx_tree_search_func)(
+        const void *node, const void *new_node);
+
+typedef void (*cx_tree_relink_func)(
+        void *node, const void *old_parent, const void *new_parent);
+
+#define CX_TREE_NODE_BASE(type)
+
+#define cx_tree_node_base_layout
+```
+
+## Create
+
+```C
+#include <cx/tree.h>
+
+CxTree *cxTreeCreate(const CxAllocator *allocator,
+        cx_tree_node_create_func create_func,
+        cx_tree_search_func search_func,
+        cx_tree_search_data_func search_data_func,
+        ptrdiff_t loc_parent,
+        ptrdiff_t loc_children, ptrdiff_t loc_last_child,
+        ptrdiff_t loc_prev, ptrdiff_t loc_next);
+
+CxTree *cxTreeCreateSimple(const CxAllocator *allocator,
+        cx_tree_node_create_func create_func,
+        cx_tree_search_func search_func,
+        cx_tree_search_data_func search_data_func);
+
+CxTree *cxTreeCreateWrapped(const CxAllocator *allocator,
+        void *root,
+        ptrdiff_t loc_parent,
+        ptrdiff_t loc_children, ptrdiff_t loc_last_child,
+        ptrdiff_t loc_prev, ptrdiff_t loc_next);
+```
+
+<warning>
+TODO: document
+</warning>
+
+## Add Nodes
+
+```C
+#include <cx/tree.h>
+
+void cx_tree_link(void *parent, void *node, ptrdiff_t loc_parent,
+        ptrdiff_t loc_children, ptrdiff_t loc_last_child,
+        ptrdiff_t loc_prev, ptrdiff_t loc_next);
+
+extern unsigned int cx_tree_add_look_around_depth;
+
+size_t cx_tree_add_iter(struct cx_iterator_base_s *iter, size_t n,
+        cx_tree_search_func sfunc, cx_tree_node_create_func cfunc,
+        void *cdata, void **failed, void *root,
+        ptrdiff_t loc_parent,
+        ptrdiff_t loc_children, ptrdiff_t loc_last_child,
+        ptrdiff_t loc_prev, ptrdiff_t loc_next);
+        
+size_t cx_tree_add_array(const void *src, size_t n, size_t elem_size,
+        cx_tree_search_func sfunc, cx_tree_node_create_func cfunc,
+        void *cdata, void **failed, void *root,
+        ptrdiff_t loc_parent,
+        ptrdiff_t loc_children, ptrdiff_t loc_last_child,
+        ptrdiff_t loc_prev, ptrdiff_t loc_next);
+        
+int cx_tree_add(const void *src,
+        cx_tree_search_func sfunc, cx_tree_node_create_func cfunc,
+        void *cdata, void **cnode, void *root,
+        ptrdiff_t loc_parent,
+        ptrdiff_t loc_children, ptrdiff_t loc_last_child,
+        ptrdiff_t loc_prev, ptrdiff_t loc_next);
+
+
+int cxTreeAddChild(CxTree *tree, void *parent, const void *data);
+
+void cxTreeAddChildNode(CxTree *tree, void *parent, void *child);
+
+void cxTreeSetParent(CxTree *tree, void *parent, void *child);
+        
+int cxTreeInsert(CxTree *tree, const void *data);
+
+size_t cxTreeInsertIter(CxTree *tree, CxIteratorBase *iter, size_t n);
+
+size_t cxTreeInsertArray(CxTree *tree, const void *data,
+        size_t elem_size, size_t n);
+```
+
+<warning>
+TODO: document
 </warning>
 
-<!--
-## Undocumented Symbols (TODO)
+## Size and Depth
+
+```C
+#include <cx/tree.h>
+
+size_t cxTreeSubtreeSize(CxTree *tree, void *subtree_root);
+
+size_t cxTreeSubtreeDepth(CxTree *tree, void *subtree_root);
+
+size_t cxTreeDepth(CxTree *tree);
+```
+
+<warning>
+TODO: document
+</warning>
+
+## Search
+
+```C
+#include <cx/tree.h>
+
+#define CX_TREE_SEARCH_INFINITE_DEPTH
+
+int cx_tree_search_data(const void *root, size_t depth,
+        const void *data, cx_tree_search_data_func sfunc,
+        void **result, ptrdiff_t loc_children, ptrdiff_t loc_next);
+
+int cx_tree_search(const void *root, size_t depth,
+        const void *node, cx_tree_search_func sfunc,
+        void **result, ptrdiff_t loc_children, ptrdiff_t loc_next);
+        
+void *cxTreeFind(CxTree *tree, const void *data);
+
+void *cxTreeFindInSubtree(CxTree *tree, const void *data,
+        void *subtree_root, size_t max_depth);
+```
+
+<warning>
+TODO: document
+</warning>
+
+## Iterator and Visitor
+
+```C
+#include <cx/tree.h>
+
+CxTreeIterator cx_tree_iterator(void *root, bool visit_on_exit,
+        ptrdiff_t loc_children, ptrdiff_t loc_next);
+
+CxTreeIterator cxTreeIterate(CxTree *tree, bool visit_on_exit);
+
+CxTreeIterator cxTreeIterateSubtree(CxTree *tree,
+        void *node, bool visit_on_exit);
+
+#define cxTreeIteratorContinue(iter)
 
-### cx_tree_add
-### cx_tree_add_array
-### cxTreeAddChild
-### cxTreeAddChildNode
-### cx_tree_add_iter
-### cx_tree_add_look_around_depth
-### cxTreeCreate
-### cxTreeCreateWrapped
-### cxTreeDepth
-### cxTreeDestroyNode
-### cxTreeDestroySubtree
-### cxTreeFree
-### cx_tree_iterator
-### cx_tree_link
-### cxTreeRemoveNode
-### cxTreeRemoveSubtree
-### cx_tree_search
-### cx_tree_search_data
-### cxTreeSetParent
-### cxTreeSubtreeDepth
-### cxTreeSubtreeSize
-### cx_tree_unlink
-### cx_tree_visitor
--->
+void cxTreeIteratorDispose(CxTreeIterator *iter);
+
+
+CxTreeVisitor cx_tree_visitor(void *root,
+        ptrdiff_t loc_children, ptrdiff_t loc_next);
+
+CxTreeVisitor cxTreeVisit(CxTree *tree);
+
+CxTreeVisitor cxTreeVisitSubtree(CxTree *tree, void *node)
+
+#define cxTreeVisitorContinue(visitor)
+
+void cxTreeVisitorDispose(CxTreeVisitor *visitor);
+```
+
+<warning>
+TODO: document
+</warning>
+
+## Remove
+
+```C
+#include <cx/tree.h>
+
+void cx_tree_unlink(void *node, ptrdiff_t loc_parent,
+        ptrdiff_t loc_children, ptrdiff_t loc_last_child,
+        ptrdiff_t loc_prev, ptrdiff_t loc_next);
+
+int cxTreeRemoveNode(CxTree *tree, void *node,
+        cx_tree_relink_func relink_func);
+
+void cxTreeRemoveSubtree(CxTree *tree, void *node);
+```
+
+<warning>
+TODO: document
+</warning>
+
+## Dispose
+
+```C
+#include <cx/tree.h>
+
+int cxTreeDestroyNode(CxTree *tree, void *node,
+        cx_tree_relink_func relink_func);
+
+void cxTreeDestroySubtree(CxTree *tree, void *node);
+
+void cxTreeClear(CxTree *tree);
+
+void cxTreeFree(CxTree *tree);
+```
+
+<warning>
+TODO: document
+</warning>
 
 <seealso>
 <category ref="apidoc">