Mercurial > hg > ucx / changeset

--- a/docs/Writerside/topics/tree.h.md	Thu Mar 20 20:12:53 2025 +0100
+++ b/docs/Writerside/topics/tree.h.md	Fri Mar 21 19:47:38 2025 +0100
@@ -86,9 +86,17 @@
         ptrdiff_t loc_prev, ptrdiff_t loc_next);
 ```
 
-<warning>
-TODO: document
-</warning>
+The function `cxTreeCreate()` creates a `CxTree` structure
+where each node created by the `create_func` has the layout specified by the offset arguments.
+The function `cxTreeCreateSimple()` is exactly the same, except that it assumes the `cx_tree_node_base_layout`.
+
+In both cases the tree will be created empty, that is with no nodes, not even a root node.
+On the other hand, `cxTreeCreateWrapped()` creates a `CxTree` structure with the specified layout and `root` node
+where `root` may already be the root of a larger tree.
+
+Note, that a wrapped tree by default has no create or search functions assigned.
+Therefore, if you wish to use one of the functions below that needs those function pointers set,
+you will have to set them manually by assigning to the respective fields in the `CxTree` structure.
 
 ## Add Nodes
 
@@ -153,9 +161,19 @@
 size_t cxTreeDepth(CxTree *tree);
 ```
 
-<warning>
-TODO: document
-</warning>
+The function `cxTreeSubtreeSize()` counts all nodes belonging to the subtree starting with `subtree_root`.
+
+The function `cxTreeSubtreeDepth()` reports the maximum depth of the subtree starting with `subtree_root`.
+If the `subtree_root` does not have any children, this results in a depth of one.
+
+The function `cxTreeDepth()` is equivalent to `cxTreeSubtreeDepth()` where `subtree_root` is the root node of the entire tree.
+
+> Passing a `NULL` pointer as `subtree_root` makes those functions return zero.
+
+> In the current UCX version there is no separate function `cxTreeSize()`, because
+> the size attribute can be directly accessed in the `CxTree` structure.
+> The next UCX version is planned to have also a function for accessing that attribute.
+>{style="note"}
 
 ## Search
 
@@ -179,9 +197,16 @@
 ```
 
 <warning>
-TODO: document
+TODO: document low level functions
 </warning>
 
+The function `cxTreeFind()` uses the `search_data_func` of the `CxTree`
+to find the `data` in the tree, and returns a pointer to the node when the data was found (or `NULL`, otherwise).
+
+The function `cxTreeFindInSubtree()` is equivalent, except that it restricts the search to nodes
+in the subtree starting with (and including) `subtree_root`, and skipping all nodes below the `max_depth`.
+Note, that the `max_depth` is specified in relation to the `subtree_root` and not in relation to the entire tree. 
+
 ## Iterator and Visitor
 
 ```C