Mercurial > hg > ucx / file diff

--- a/docs/Writerside/topics/tree.h.md	Wed Dec 31 13:39:55 2025 +0100
+++ b/docs/Writerside/topics/tree.h.md	Wed Dec 31 14:58:40 2025 +0100
@@ -124,15 +124,26 @@
         ptrdiff_t loc_children, ptrdiff_t loc_last_child,
         ptrdiff_t loc_prev, ptrdiff_t loc_next);
 
+void *cxTreeCreateRootData(CxTree *tree, const void *data);
+
+void *cxTreeCreateRoot(CxTree *tree, void *child);
+
+void *cxTreeCreateNode(CxTree *tree, void *parent);
+        
 void *cxTreeAddData(CxTree *tree, void *parent, const void *data);
 
 void cxTreeAddNode(CxTree *tree, void *parent, void *child);
 
 void cxTreeSetParent(CxTree *tree, void *parent, void *child);
+
+void *cxTreeSetRoot(CxTree *tree, void *root);
 ```
 
 The low-level function `cx_tree_add()` adds a `node` to a new `parent`, unlinking it from its previous parent, if required.
 
+When you have created a high-level tree that is still empty, you can create a root node with `cxTreeCreateRoot()` or `cxTreeCreateRootData()`.
+Both functions return an existing root node, if present, and `NULL` when the allocation of a new node failed.
+
 The functions `cxTreeAddData()`, `cxTreeAddNode()`, and `cxTreeSetParent()` are similar to `cx_tree_add()`.
 The difference between `cxTreeAddData()` and `cxTreeAddNode()` is,
 that `cxTreeAddData()` uses the allocator of the `CxTree` to create the node first, before adding it.
@@ -140,11 +151,19 @@
 The difference between `cxTreeSetParent()` and `cxTreeAddNode()` is,
 that `cxTreeSetParent()` does not increase the tree size, when `child` already had a parent.
 
+When you want to use `cxTreeCreateRootData()` or `cxTreeAddData()`,
+the `loc_data` parameter of `cxTreeCreate()` must have been set to a non-negative value.
+Otherwise, the functions will return `NULL`.
+
 > Use `cxTreeAddNode()` to add _new_ nodes to the tree and `cxTreeSetParent()`
 > to relink a subtree of the `tree` with a new parent.
 > 
 > Using `cxTreeSetParent()` on a `child` which already has a parent in a _different_ tree is a mistake.
 
+The function `cxTreeSetRoot()` returns the current root node of the tree,
+or `NULL` when the tree is empty, and sets a new root node.
+It is up to the caller to take care of a possibly necessary deallocation of the old tree nodes.
+Also, keep in mind that the tree might have destructors registered which will be applied to the nodes belonging to the new root.
 
 ## Size and Depth