ucx: comparison src/cx/tree.h

-:192a440b99df
+:6540096c17b7
 ptrdiff_t loc_prev,
 ptrdiff_t loc_next
 );
 /**
+* 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
 * contains the given \p data or if one of the children might contain
 * the data.
 *
 * 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
 * return a positive number to indicate that a child node might contain the
 * searched item. On the other hand, if the node denotes a path that is not a
 * contains the same \p data as \p new_node or if one of the children might
 * contain the data.
 *
 * 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
 * return a positive number to indicate that a child node might contain the
 * searched item. On the other hand, if the node denotes a path that is not a
 * with the best match according to the \p sfunc (meaning: the return value of
 * \p sfunc which is closest to zero). If that is also ambiguous, an arbitrary
 * 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
 * @param loc_children offset in the node struct for the children linked list
 * @param loc_next offset in the node struct for the next pointer
 * contain any node that might be related to the searched data
 */
 __attribute__((__nonnull__))
 int cx_tree_search_data(
 const void *root,
+size_t depth,
 const void *data,
 cx_tree_search_data_func sfunc,
 void **result,
 ptrdiff_t loc_children,
 ptrdiff_t loc_next
 * with the best match according to the \p sfunc (meaning: the return value of
 * \p sfunc which is closest to zero). If that is also ambiguous, an arbitrary
 * 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
 * @param loc_children offset in the node struct for the children linked list
 * @param loc_next offset in the node struct for the next pointer
 * contain any node that might be related to the searched data
 */
 __attribute__((__nonnull__))
 int cx_tree_search(
 const void *root,
+size_t depth,
 const void *node,
 cx_tree_search_func sfunc,
 void **result,
 ptrdiff_t loc_children,
 ptrdiff_t loc_next
 * Member function for finding a node.
 */
 void *(*find)(
 struct cx_tree_s *tree,
 const void *subtree,
-const void *data
+const void *data,
+size_t depth
 );
 };
 /**
 * Common type for all tree implementations.
 __attribute__((__nonnull__))
 static inline void *cxTreeFind(
 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.
 *
 * \remark For this function to work, the tree needs a specified \c search_data
 * (see #cxTreeCreateWrapped()).
 *
 * @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);
 }
 /**
 * Determines the size of the specified subtree.
 *
 * If the node is not part of the tree, the behavior is undefined.
 *
 * @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()
 */
 __attribute__((__nonnull__, __warn_unused_result__))
 static inline CxTreeIterator cxTreeIterateSubtree(
 /**
 * Creates a depth-first iterator for the specified tree.
 *
 * @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()
 */
 __attribute__((__nonnull__, __warn_unused_result__))
 static inline CxTreeIterator cxTreeIterate(

Mercurial > hg > ucx / file comparison

comparison: src/cx/tree.h

src/cx/tree.h