Mercurial > hg > ucx / changeset

--- a/docs/Writerside/topics/tree.h.md	Fri Apr 04 00:10:08 2025 +0200
+++ b/docs/Writerside/topics/tree.h.md	Fri Apr 04 18:02:35 2025 +0200
@@ -243,11 +243,11 @@
 
 #define CX_TREE_SEARCH_INFINITE_DEPTH
 
-int cx_tree_search_data(const void *root, size_t depth,
+int cx_tree_search_data(const void *root, size_t max_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,
+int cx_tree_search(const void *root, size_t max_depth,
         const void *node, cx_tree_search_func sfunc,
         void **result, ptrdiff_t loc_children, ptrdiff_t loc_next);
         
@@ -257,9 +257,24 @@
         void *subtree_root, size_t max_depth);
 ```
 
-<warning>
-TODO: document low level functions
-</warning>
+The functions `cx_tree_search_data()` and `cx_tree_search()` are equivalent,
+except that `cx_tree_search_data()` compares a currently investigated node against the `data` with the specified `cx_tree_search_data_func`,
+and `cx_tree_search()` compares against a `node` with the specified `cx_tree_search_func`.
+
+Usually you the latter is rarely needed.
+It is used, for example, by `cx_tree_add()` to find the correct position where to add a freshly created node.
+
+The search proceeds as follows, starting with the `root` node:
+
+1. The current node is compared with `data` / `node` using the `sfunc`.
+2. If `sfunc` returns zero, a matching node has been found and the pointer to that node is stored at the location given by `result`.
+3. If `sfunc` returns a negative number, the entire subtree is skipped.
+4. If `sfunc` returns a positive number, the subtree is searched, unless the number is larger than the number of an already searched subtree. The best match will be stored  at the location given by `result`. 
+5. The return value will be the return value of the `sfunc` for node that was stored in the `result`, or a negative number when no match was found
+
+> If the `sfunc` implements some kind of metric, the search functions will return the best match in the tree with respect to that metric.
+> When a positive number is returned, it means, that a new node with the searched data could be added as a child of the found node.
+> This is exactly how `cx_tree_add()` finds the best position to add a node to the tree.
 
 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).