Mercurial > hg > ucx / file diff

--- a/src/cx/tree.h	Sun Oct 13 16:47:14 2024 +0200
+++ b/src/cx/tree.h	Sat Oct 19 13:08:06 2024 +0200
@@ -298,6 +298,11 @@
 );
 
 /**
+ * Macro that can be used instead of the magic value for infinite search depth.
+ */
+#define CX_TREE_SEARCH_INFINITE_DEPTH 0
+
+/**
  * Function pointer for a search function.
  *
  * A function of this kind shall check if the specified \p node
@@ -306,6 +311,8 @@
  *
  * The function should use the returned integer to indicate how close the
  * match is, where a negative number means that it does not match at all.
+ * Zero means exact match and a positive number is an implementation defined
+ * measure for the distance to an exact match.
  *
  * For example if a tree stores file path information, a node that is
  * describing a parent directory of a filename that is searched, shall
@@ -333,6 +340,8 @@
  *
  * The function should use the returned integer to indicate how close the
  * match is, where a negative number means that it does not match at all.
+ * Zero means exact match and a positive number is an implementation defined
+ * measure for the distance to an exact match.
  *
  * For example if a tree stores file path information, a node that is
  * describing a parent directory of a filename that is searched, shall
@@ -364,6 +373,7 @@
  * node matching the criteria is returned.
  *
  * @param root the root node
+ * @param depth the maximum depth (zero=indefinite, one=just root)
  * @param data the data to search for
  * @param sfunc the search function
  * @param result where the result shall be stored
@@ -376,6 +386,7 @@
 __attribute__((__nonnull__))
 int cx_tree_search_data(
         const void *root,
+        size_t depth,
         const void *data,
         cx_tree_search_data_func sfunc,
         void **result,
@@ -397,6 +408,7 @@
  * node matching the criteria is returned.
  *
  * @param root the root node
+* @param depth the maximum depth (zero=indefinite, one=just root)
  * @param node the node to search for
  * @param sfunc the search function
  * @param result where the result shall be stored
@@ -409,6 +421,7 @@
 __attribute__((__nonnull__))
 int cx_tree_search(
         const void *root,
+        size_t depth,
         const void *node,
         cx_tree_search_func sfunc,
         void **result,
@@ -839,7 +852,8 @@
     void *(*find)(
             struct cx_tree_s *tree,
             const void *subtree,
-            const void *data
+            const void *data,
+            size_t depth
     );
 };
 
@@ -1031,12 +1045,15 @@
         CxTree *tree,
         const void *data
 ) {
-    return tree->cl->find(tree, tree->root, data);
+    return tree->cl->find(tree, tree->root, data, 0);
 }
 
 /**
  * Searches the data in the specified subtree.
  *
+ * When \p max_depth is zero, the depth is not limited.
+ * The \p subtree_root itself is on depth 1 and its children have depth 2.
+ *
  * \note When \p subtree_root is not part of the \p tree, the behavior is
  * undefined.
  *
@@ -1047,15 +1064,17 @@
  * @param tree the tree
  * @param data the data to search for
  * @param subtree_root the node where to start
+ * @param max_depth the maximum search depth
  * @return the first matching node, or \c NULL when the data cannot be found
  */
 __attribute__((__nonnull__))
 static inline void *cxTreeFindInSubtree(
         CxTree *tree,
         const void *data,
-        void *subtree_root
+        void *subtree_root,
+        size_t max_depth
 ) {
-    return tree->cl->find(tree, subtree_root, data);
+    return tree->cl->find(tree, subtree_root, data, max_depth);
 }
 
 /**
@@ -1095,7 +1114,7 @@
  * @param tree the tree to iterate
  * @param node the node where to start
  * @param visit_on_exit true, if the iterator shall visit a node again when
- * leaving the sub-tree
+ * leaving the subtree
  * @return a tree iterator (depth-first)
  * @see cxTreeVisit()
  */
@@ -1133,7 +1152,7 @@
  *
  * @param tree the tree to iterate
  * @param visit_on_exit true, if the iterator shall visit a node again when
- * leaving the sub-tree
+ * leaving the subtree
  * @return a tree iterator (depth-first)
  * @see cxTreeVisit()
  */