# HG changeset patch # User Mike Becker # Date 1720037262 -7200 # Node ID 6367456bf2d9ca1d2c0ccd06b1bc3be83dcb6a61 # Parent d9ad7904c4c2aeb0469214217e377b3c14c5961f minor doc fixes diff -r d9ad7904c4c2 -r 6367456bf2d9 src/cx/tree.h --- a/src/cx/tree.h Sat Jun 08 20:08:09 2024 +0200 +++ b/src/cx/tree.h Wed Jul 03 22:07:42 2024 +0200 @@ -47,13 +47,16 @@ /** * A depth-first tree iterator. * - * This iterator is not position-aware in a strict sense, as it does not assume a particular order of elements in the - * tree. However, the iterator keeps track of the number of nodes it has passed in a counter variable. + * This iterator is not position-aware in a strict sense, as it does not assume + * a particular order of elements in the tree. However, the iterator keeps track + * of the number of nodes it has passed in a counter variable. * Each node, regardless of the number of passes, is counted only once. * - * @note Objects that are pointed to by an iterator are mutable through that iterator. However, if the - * underlying data structure is mutated by other means than this iterator (e.g. elements added or removed), - * the iterator becomes invalid (regardless of what cxIteratorValid() returns). + * @note Objects that are pointed to by an iterator are mutable through that + * iterator. However, if the + * underlying data structure is mutated by other means than this iterator (e.g. + * elements added or removed), the iterator becomes invalid (regardless of what + * cxIteratorValid() returns). * * @see CxIterator */ @@ -143,16 +146,21 @@ /** * A breadth-first tree iterator. * - * This iterator needs to maintain a visitor queue that will be automatically freed once the iterator becomes invalid. - * If you want to discard the iterator before, you MUST manually call cxTreeVisitorDispose(). + * This iterator needs to maintain a visitor queue that will be automatically + * freed once the iterator becomes invalid. + * If you want to discard the iterator before, you MUST manually call + * cxTreeVisitorDispose(). * - * This iterator is not position-aware in a strict sense, as it does not assume a particular order of elements in the - * tree. However, the iterator keeps track of the number of nodes it has passed in a counter variable. + * This iterator is not position-aware in a strict sense, as it does not assume + * a particular order of elements in the tree. However, the iterator keeps track + * of the number of nodes it has passed in a counter variable. * Each node, regardless of the number of passes, is counted only once. * - * @note Objects that are pointed to by an iterator are mutable through that iterator. However, if the - * underlying data structure is mutated by other means than this iterator (e.g. elements added or removed), - * the iterator becomes invalid (regardless of what cxIteratorValid() returns). + * @note Objects that are pointed to by an iterator are mutable through that + * iterator. However, if the + * underlying data structure is mutated by other means than this iterator (e.g. + * elements added or removed), the iterator becomes invalid (regardless of what + * cxIteratorValid() returns). * * @see CxIterator */ @@ -298,7 +306,7 @@ * 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 * prefix of the searched filename, the function would return -1 to indicate - * that * the search does not need to be continued in that branch. + * that the search does not need to be continued in that branch. * * @param node the node that is currently investigated * @param data the data that is searched for @@ -307,7 +315,7 @@ * positive if one of the children might contain the data, * negative if neither the node, nor the children contains the data */ -typedef int (*cx_tree_search_func)(void const *node, void const* data); +typedef int (*cx_tree_search_func)(void const *node, void const *data); /** @@ -346,15 +354,18 @@ /** * Creates a depth-first iterator for a tree with the specified root node. * - * @note A tree iterator needs to maintain a stack of visited nodes, which is allocated using stdlib malloc(). - * When the iterator becomes invalid, this memory is automatically released. However, if you wish to cancel the - * iteration before the iterator becomes invalid by itself, you MUST call cxTreeIteratorDispose() manually to release + * @note A tree iterator needs to maintain a stack of visited nodes, which is + * allocated using stdlib malloc(). + * When the iterator becomes invalid, this memory is automatically released. + * However, if you wish to cancel the iteration before the iterator becomes + * invalid by itself, you MUST call cxTreeIteratorDispose() manually to release * the memory. * * @remark The returned iterator does not support cxIteratorFlagRemoval(). * * @param root the root node - * @param visit_on_exit set to true, when the iterator shall visit a node again after processing all children + * @param visit_on_exit set to true, when the iterator shall visit a node again + * after processing all children * @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 * @return the new tree iterator @@ -371,9 +382,11 @@ /** * Creates a breadth-first iterator for a tree with the specified root node. * - * @note A tree visitor needs to maintain a queue of to be visited nodes, which is allocated using stdlib malloc(). - * When the visitor becomes invalid, this memory is automatically released. However, if you wish to cancel the - * iteration before the visitor becomes invalid by itself, you MUST call cxTreeVisitorDispose() manually to release + * @note A tree visitor needs to maintain a queue of to be visited nodes, which + * is allocated using stdlib malloc(). + * When the visitor becomes invalid, this memory is automatically released. + * However, if you wish to cancel the iteration before the visitor becomes + * invalid by itself, you MUST call cxTreeVisitorDispose() manually to release * the memory. * * @remark The returned iterator does not support cxIteratorFlagRemoval().