comparison: docs/Writerside/topics/tree.h.md
docs/Writerside/topics/tree.h.md
- changeset 1255
- a9d730c8b94a
- parent 1254
- 6a342294499b
- child 1265
- 07d67421092a
equal
deleted
inserted
replaced
| 1254:6a342294499b | 1255:a9d730c8b94a |
|---|---|
| 84 ptrdiff_t loc_parent, | 84 ptrdiff_t loc_parent, |
| 85 ptrdiff_t loc_children, ptrdiff_t loc_last_child, | 85 ptrdiff_t loc_children, ptrdiff_t loc_last_child, |
| 86 ptrdiff_t loc_prev, ptrdiff_t loc_next); | 86 ptrdiff_t loc_prev, ptrdiff_t loc_next); |
| 87 ``` | 87 ``` |
| 88 | 88 |
| 89 <warning> | 89 The function `cxTreeCreate()` creates a `CxTree` structure |
| 90 TODO: document | 90 where each node created by the `create_func` has the layout specified by the offset arguments. |
| 91 </warning> | 91 The function `cxTreeCreateSimple()` is exactly the same, except that it assumes the `cx_tree_node_base_layout`. |
| 92 | |
| 93 In both cases the tree will be created empty, that is with no nodes, not even a root node. | |
| 94 On the other hand, `cxTreeCreateWrapped()` creates a `CxTree` structure with the specified layout and `root` node | |
| 95 where `root` may already be the root of a larger tree. | |
| 96 | |
| 97 Note, that a wrapped tree by default has no create or search functions assigned. | |
| 98 Therefore, if you wish to use one of the functions below that needs those function pointers set, | |
| 99 you will have to set them manually by assigning to the respective fields in the `CxTree` structure. | |
| 92 | 100 |
| 93 ## Add Nodes | 101 ## Add Nodes |
| 94 | 102 |
| 95 ```C | 103 ```C |
| 96 #include <cx/tree.h> | 104 #include <cx/tree.h> |
| 151 size_t cxTreeSubtreeDepth(CxTree *tree, void *subtree_root); | 159 size_t cxTreeSubtreeDepth(CxTree *tree, void *subtree_root); |
| 152 | 160 |
| 153 size_t cxTreeDepth(CxTree *tree); | 161 size_t cxTreeDepth(CxTree *tree); |
| 154 ``` | 162 ``` |
| 155 | 163 |
| 156 <warning> | 164 The function `cxTreeSubtreeSize()` counts all nodes belonging to the subtree starting with `subtree_root`. |
| 157 TODO: document | 165 |
| 158 </warning> | 166 The function `cxTreeSubtreeDepth()` reports the maximum depth of the subtree starting with `subtree_root`. |
| 167 If the `subtree_root` does not have any children, this results in a depth of one. | |
| 168 | |
| 169 The function `cxTreeDepth()` is equivalent to `cxTreeSubtreeDepth()` where `subtree_root` is the root node of the entire tree. | |
| 170 | |
| 171 > Passing a `NULL` pointer as `subtree_root` makes those functions return zero. | |
| 172 | |
| 173 > In the current UCX version there is no separate function `cxTreeSize()`, because | |
| 174 > the size attribute can be directly accessed in the `CxTree` structure. | |
| 175 > The next UCX version is planned to have also a function for accessing that attribute. | |
| 176 >{style="note"} | |
| 159 | 177 |
| 160 ## Search | 178 ## Search |
| 161 | 179 |
| 162 ```C | 180 ```C |
| 163 #include <cx/tree.h> | 181 #include <cx/tree.h> |
| 177 void *cxTreeFindInSubtree(CxTree *tree, const void *data, | 195 void *cxTreeFindInSubtree(CxTree *tree, const void *data, |
| 178 void *subtree_root, size_t max_depth); | 196 void *subtree_root, size_t max_depth); |
| 179 ``` | 197 ``` |
| 180 | 198 |
| 181 <warning> | 199 <warning> |
| 182 TODO: document | 200 TODO: document low level functions |
| 183 </warning> | 201 </warning> |
| 202 | |
| 203 The function `cxTreeFind()` uses the `search_data_func` of the `CxTree` | |
| 204 to find the `data` in the tree, and returns a pointer to the node when the data was found (or `NULL`, otherwise). | |
| 205 | |
| 206 The function `cxTreeFindInSubtree()` is equivalent, except that it restricts the search to nodes | |
| 207 in the subtree starting with (and including) `subtree_root`, and skipping all nodes below the `max_depth`. | |
| 208 Note, that the `max_depth` is specified in relation to the `subtree_root` and not in relation to the entire tree. | |
| 184 | 209 |
| 185 ## Iterator and Visitor | 210 ## Iterator and Visitor |
| 186 | 211 |
| 187 ```C | 212 ```C |
| 188 #include <cx/tree.h> | 213 #include <cx/tree.h> |
