Mercurial > hg > ucx / file diff

--- a/src/cx/tree.h	Wed Dec 31 13:39:55 2025 +0100
+++ b/src/cx/tree.h	Wed Dec 31 14:58:40 2025 +0100
@@ -484,6 +484,12 @@
  * The specified @p allocator will be used for creating the tree struct
  * @em and the nodes.
  *
+ * When you do not specify an existing @p root, the tree will be created
+ * empty. Additionally, cxFree() is registered as the advanced destructor for
+ * the tree so that all nodes that you will add to the tree are automatically
+ * freed together with the tree.
+ * When @p root is not @c NULL, no destructors are registered automatically.
+ *
  * @param allocator the allocator to use
  * (if @c NULL, the cxDefaultAllocator is assumed)
  * @param node_size the complete size of one node
@@ -720,12 +726,55 @@
 CX_EXTERN CX_NONNULL
 void *cxTreeAddData(CxTree *tree, void *parent, const void *data);
 
-CX_EXTERN CX_NODISCARD
+/**
+ * Creates a new node and adds it to the tree.
+ *
+ * @param tree the tree
+ * @param parent the parent node of the new node
+ * @return the added node or @c NULL when the allocation failed
+ */
+CX_EXTERN CX_NODISCARD CX_NONNULL
+void *cxTreeCreateNode(CxTree *tree, void *parent);
+
+/**
+ * Creates a new root node or returns the existing root node.
+ *
+ * @param tree the tree
+ * @return the new root node, the existing root node, or @c NULL when the allocation failed
+ * @see cxTreeCreateRootData()
+ */
+CX_EXTERN CX_NODISCARD CX_NONNULL
 void *cxTreeCreateRoot(CxTree *tree);
 
-CX_EXTERN CX_NODISCARD
+/**
+ * Creates a new root node or uses the existing root node and writes the specified data to that node.
+ *
+ * @note This function immediately returns @c NULL when @c loc_data was not initialized with a positive value.
+ *
+ * @param tree the tree
+ * @param data the data for the root node
+ * @return the new root node, the existing root node,
+ * or @c NULL when the allocation failed or the data location is not known
+ * @see cxTreeCreateRoot()
+ */
+CX_EXTERN CX_NODISCARD CX_NONNULL
 void *cxTreeCreateRootData(CxTree *tree, const void *data);
 
+/**
+ * Exchanges the root of the tree.
+ *
+ * @attention The old tree nodes might need to be deallocated by the caller.
+ * On the other hand, when the tree has destructors registered, keep in mind
+ * that they will be applied to the new tree.
+ * In particular, using cxTreeCreate() with a @c NULL root and setting the
+ * root with this function is @em not equivalent to creating the tree with
+ * a reference to an existing root because trees created without a root will
+ * have destructors registered.
+ *
+ * @param tree the tree
+ * @param new_root the new root node
+ * @return the old root node (or @c NULL when the tree was empty)
+ */
 CX_EXTERN CX_NONNULL_ARG(1) CX_NODISCARD
 void *cxTreeSetRoot(CxTree *tree, void *new_root);