Mercurial > hg > ucx / changeset

     1.1 --- a/src/cx/tree.h	Wed Feb 14 21:31:38 2024 +0100
     1.2 +++ b/src/cx/tree.h	Wed Feb 14 21:43:32 2024 +0100
     1.3 @@ -87,6 +87,29 @@
     1.4          ptrdiff_t loc_next
     1.5  );
     1.6  
     1.7 +/**
     1.8 + * Function pointer for a search function.
     1.9 + *
    1.10 + * A function of this kind shall check if the specified \p node
    1.11 + * contains the given \p data or if one of the children might contain
    1.12 + * the data.
    1.13 + *
    1.14 + * For example if a tree stores file path information, a node that is
    1.15 + * describing a parent directory of a filename that is searched, shall
    1.16 + * return 1 to indicate that a child node might contain the searched item.
    1.17 + * On the other hand, if the node denotes a path that is not a prefix of
    1.18 + * the searched filename, the function would return -1 to indicate that
    1.19 + * the search does not need to be continued in that branch.
    1.20 + *
    1.21 + * @param node the node that is currently investigated
    1.22 + * @param data the data that is searched for
    1.23 + *
    1.24 + * @return 0 if the node contains the data,
    1.25 + * 1 if one of the children might contain the data,
    1.26 + * -1 if neither the node, nor the children contains the data
    1.27 + */
    1.28 +int (*cx_tree_search_func)(void const *node, void const* data);
    1.29 +
    1.30  #ifdef __cplusplus
    1.31  } // extern "C"
    1.32  #endif