Mercurial > hg > ucx / changeset

--- a/src/cx/tree.h	Sun Sep 29 22:45:43 2024 +0200
+++ b/src/cx/tree.h	Sun Sep 29 23:08:40 2024 +0200
@@ -750,28 +750,28 @@
      */
     size_t size;
 
-    /*
+    /**
      * Offset in the node struct for the parent pointer.
      */
     ptrdiff_t loc_parent;
 
-    /*
+    /**
      * Offset in the node struct for the children linked list.
      */
     ptrdiff_t loc_children;
 
-    /*
+    /**
      * Optional offset in the node struct for the pointer to the last child
      * in the linked list (negative if there is no such pointer).
      */
     ptrdiff_t loc_last_child;
 
-    /*
+    /**
      * Offset in the node struct for the previous sibling pointer.
      */
     ptrdiff_t loc_prev;
 
-    /*
+    /**
      * Offset in the node struct for the next sibling pointer.
      */
     ptrdiff_t loc_next;
@@ -861,6 +861,74 @@
  */
 typedef struct cx_tree_s CxTree;
 
+/**
+ * Creates a new tree structure based on the specified layout.
+ *
+ * The specified \p allocator will be used for creating the tree struct
+ * and SHALL be used by \p create_func to allocate memory for the nodes.
+ *
+ * @param allocator the allocator that shall be used
+ * @param create_func a function that creates new nodes
+ * @param search_func a function that compares two nodes
+ * @param loc_parent offset in the node struct for the parent pointer
+ * @param loc_children offset in the node struct for the children linked list
+ * @param loc_last_child optional offset in the node struct for the pointer to
+ * the last child in the linked list (negative if there is no such pointer)
+ * @param loc_prev offset in the node struct for the prev pointer
+ * @param loc_next offset in the node struct for the next pointer
+ * @return the new tree
+ * @see cxTreeCreateSimple()
+ */
+__attribute__((__nonnull__, __warn_unused_result__))
+CxTree *cxTreeCreate(
+        const CxAllocator *allocator,
+        cx_tree_node_create_func create_func,
+        cx_tree_search_func search_func,
+        ptrdiff_t loc_parent,
+        ptrdiff_t loc_children,
+        ptrdiff_t loc_last_child,
+        ptrdiff_t loc_prev,
+        ptrdiff_t loc_next
+);
+
+/**
+ * Creates a new tree structure based on a default layout.
+ *
+ * Nodes created by \p create_func MUST contain #cx_tree_node_base_s as first
+ * member (or at least respect the default offsets specified in the tree
+ * struct) and they MUST be allocated with the default stdlib allocator.
+ *
+ * \attention This function will also register a simple destructor which
+ * will free the nodes with the default stdlib allocator.
+ *
+ * @param create_func a function that creates new nodes
+ * @param search_func a function that compares two nodes
+ * @return the new tree
+ * @see cxTreeCreate()
+ */
+__attribute__((__nonnull__, __warn_unused_result__))
+static inline CxTree *cxTreeCreateSimple(
+        cx_tree_node_create_func create_func,
+        cx_tree_search_func search_func
+) {
+    return cxTreeCreate(cxDefaultAllocator,
+            create_func, search_func, cx_tree_node_base_layout);
+}
+
+/**
+ * Destroys the tree structure.
+ *
+ * \attention This function will only invoke the destructor functions
+ * on the nodes, if specified.
+ * It will NOT automatically free the nodes with the allocator, because that
+ * will cause a double-free in scenarios where this tree structure is wrapping
+ * a tree which memory is managed by someone else.
+ *
+ * @param tree the tree to destroy
+ */
+__attribute__((__nonnull__))
+void cxTreeDestroy(CxTree *tree);
+
 #ifdef __cplusplus
 } // extern "C"
 #endif