ucx: comparison docs/Writerside/topics/tree.h.md

-:9a72258446cd
+:563033aa998c
 # Tree
-UCX provides several low-level function for working with arbitrary tree structures,
+UCX provides several low-level functions for working with arbitrary tree structures,
 as well as some high-level functions for trees that induce a certain order on the data they store.
 The following convenience macros allow you to declare and use simple tree structures.
 ```C
 The `CX_TREE_NODE_BASE` macro declares four pointers of type `Type*`:
 `parent`, `children`, `last_child`, `prev`, and `next`,
 which must be placed as first member into your struct.
-You can use it for example like this:
+You can use it, for example, like this:
 ```C
 typedef struct my_tree_node_s {
 CX_TREE_NODE_BASE(struct my_tree_node_s);
 int value;
 char *desc;
 If your wrapped tree structure does not have a `last_child` or a `prev` pointer,
 you may specify a negative location to indicate the missing pointer.
 All other pointers are mandatory and a non-negative location is expected.
-Note, that a wrapped tree by default has no create or search functions assigned.
+Note that a wrapped tree by default has no create or search functions assigned.
 Therefore, if you wish to use one of the functions below that needs those function pointers set,
 you will have to set them manually by assigning to the respective fields in the `CxTree` structure.
 ### Example for wrapping a libxml2 tree
 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`.
+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.
+> 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).
 #define cxTreeVisitorContinue(visitor)
 void cxTreeVisitorDispose(CxTreeVisitor *visitor);
 ```
-There are two different kind of iterators for trees.
+There are two different kinds of iterators for trees.
 The `CxTreeIterator` is performing a depth-first iteration with the capability of visiting a node twice:
 first when the iterator enters the node coming from its parent, and secondly when the iterator tracks back from its last child.
 This behavior is controlled via the `visit_on_exit` argument.
 When set to `true`, the iterators `exiting` flag can be checked during iteration to see whether the iterator is currently entering or leaving the node.
 The above [example](#example-for-wrapping-a-libxml2-tree) for iterating through an XML tree illustrates this.
 On the other hand, the `CxTreeVisitor` performs a breadth-first iteration and visits every node only once.
-Since tree iteration needs to keep track of a stack (depth-first) or queue (breadth-frist), internal memory is allocated.
+Since tree iteration needs to keep track of a stack (depth-first) or queue (breadth-first), internal memory is allocated.
-This memory is _automatically_ disposed when the iteration _completes_.
+This memory is _automatically_ disposed of when the iteration _completes_.
 If you break from the iteration early, you must call `cxTreeIteratorDispose()` or `cxTreeVisitorDispose()`, respectively, to deallocate the memory.
 > It is recommended to always invoke the dispose functions, even when it seems not necessary.
-> In the best case it just does nothing, but calling them guarantees that no memory can be leaking, even when your code changes in the future.
+> In the best case it just does nothing, but calling them guarantees that no memory can be leaking, even when your code will change in the future.
 >{style="note"}
 The macros `cxTreeIteratorContinue()` and `cxTreeVisitorContinue()` equivalently instruct the iterator/visitor to skip the subtree below the currently inspected node.
 ## Remove
 void cxTreeFree(CxTree *tree);
 ```
 The function `cxTreeDestroyNode()` first [removes](#remove) the `node` from the tree, like `cxTreeRemoveNode()`,
 and then invokes the [destructor functions](collection.h.md#destructor-functions).
-It is guaranteed, that the simple destructor is called before the advanced destructor.
+It is guaranteed that the simple destructor is called before the advanced destructor.
 If no destructor function is registered at all, the behavior is identical to `cxTreeRemoveNode()`.
-That means, this function does not deallocate the memory for the node on its own and leaves that entirely to the destructor functions.
+That means this function does not deallocate the memory for the node on its own and leaves that entirely to the destructor functions.
 The function `cxTreeDestroySubtree()` performs the above actions for the entire subtree starting with `node`.
-The order in which the destructor functions for the nodes of the subtree are called are determined by a [tree iterator](#iterator-and-visitor).
+The order in which the destructor functions for the nodes of the subtree are called is determined by a [tree iterator](#iterator-and-visitor).
 The function `cxTreeClear()` is a shorthand for invoking `cxTreeDestroySubtree()` on the root node of the tree.
 The function `cxTreeFree()` behaves like `cxTreeClear()` and then deallocates the memory for the `CxTree` structure.

Mercurial > hg > ucx / file comparison

comparison: docs/Writerside/topics/tree.h.md

docs/Writerside/topics/tree.h.md