comparison: docs/Writerside/topics/tree.h.md
docs/Writerside/topics/tree.h.md
- changeset 1275
- 0f21abc52241
- parent 1273
- c35be6dc1667
equal
deleted
inserted
replaced
| 1274:03e9360e98f5 | 1275:0f21abc52241 |
|---|---|
| 188 cx_tree_search_func sfunc, cx_tree_node_create_func cfunc, | 188 cx_tree_search_func sfunc, cx_tree_node_create_func cfunc, |
| 189 void *cdata, void **cnode, void *root, | 189 void *cdata, void **cnode, void *root, |
| 190 ptrdiff_t loc_parent, | 190 ptrdiff_t loc_parent, |
| 191 ptrdiff_t loc_children, ptrdiff_t loc_last_child, | 191 ptrdiff_t loc_children, ptrdiff_t loc_last_child, |
| 192 ptrdiff_t loc_prev, ptrdiff_t loc_next); | 192 ptrdiff_t loc_prev, ptrdiff_t loc_next); |
| 193 | 193 ``` |
| 194 | |
| 195 The low-level function `cx_tree_link()` adds a `node` to a new `parent`, unlinking it from its previous parent, if required. | |
| 196 | |
| 197 The functions `cx_tree_add_array()` and `cx_tree_add_iter()` are equivalent, | |
| 198 except that the former adds `n` items of size `elem_size` from the `src` array, | |
| 199 and the latter adds _up to_ `n` items from the iterator `iter`. | |
| 200 For each element, the `cfun` is called with the element as first argument and the `cdata` context as second argument. | |
| 201 The `cfun` function is supposed to return a node for which then the `sfunc` is used to find the location where to insert the node. | |
| 202 If a node could not be added, because `sfunc` always returns a negative number, it is stored at the location where `failed` points to. | |
| 203 | |
| 204 > The functions `cx_tree_add_array()` and `cx_tree_add_iter()` are optimized for adding multiple nodes to | |
| 205 > the same subtree without starting the search all over from the root node. | |
| 206 > This behavior can be controlled with `cx_tree_add_look_around_depth`, which specifies for how many parent nodes | |
| 207 > the algorithm backtracks in the current subtree before restarting the search from the root node. | |
| 208 | |
| 209 The function `cx_tree_add()` is similar to the other add-functions, | |
| 210 except that it does only add one single item to the tree and always stores the created node at the location where `cnode` points to. | |
| 211 | |
| 212 > By design, the add-functions can only be used to add children to the tree. | |
| 213 > If you want to add a new root node, this is much easier by simply calling `cx_tree_link(newroot, oldroot, layout...)` . | |
| 214 | |
| 215 The following high-level functions can be used to add nodes to a `CxTree`. | |
| 216 | |
| 217 ```C | |
| 218 #include <cx/tree.h> | |
| 194 | 219 |
| 195 int cxTreeAddChild(CxTree *tree, void *parent, const void *data); | 220 int cxTreeAddChild(CxTree *tree, void *parent, const void *data); |
| 196 | 221 |
| 197 void cxTreeAddChildNode(CxTree *tree, void *parent, void *child); | 222 void cxTreeAddChildNode(CxTree *tree, void *parent, void *child); |
| 198 | 223 |
| 199 void cxTreeSetParent(CxTree *tree, void *parent, void *child); | 224 void cxTreeSetParent(CxTree *tree, void *parent, void *child); |
| 200 | 225 |
| 201 int cxTreeInsert(CxTree *tree, const void *data); | 226 int cxTreeInsert(CxTree *tree, const void *data); |
| 202 | 227 |
| 203 size_t cxTreeInsertIter(CxTree *tree, CxIteratorBase *iter, size_t n); | 228 size_t cxTreeInsertIter(CxTree *tree, CxIteratorBase *iter, size_t n); |
| 204 | 229 |
| 205 size_t cxTreeInsertArray(CxTree *tree, const void *data, | 230 size_t cxTreeInsertArray(CxTree *tree, const void *data, |
| 206 size_t elem_size, size_t n); | 231 size_t elem_size, size_t n); |
| 207 ``` | 232 ``` |
| 208 | 233 |
| 209 <warning> | 234 The functions `cxTreeAddChild()`, `cxTreeAddChildNode()`, and `cxTreeSetParent()` are similar to `cx_tree_link()`. |
| 210 TODO: document | 235 The difference between `cxTreeAddChild()` and `cxTreeAddChildNode()` is, |
| 211 </warning> | 236 that `cxTreeAddChild()` uses the `cx_tree_node_create_func` of the `CxTree` to create the node first, before adding it. |
| 237 The function returns non-zero in case the creation of the node fails. | |
| 238 The difference between `cxTreeSetParent()` and `cxTreeAddChildNode()` is, | |
| 239 that `cxTreeSetParent()` does not increase the tree size, when `child` already had a parent. | |
| 240 | |
| 241 > Use `cxTreeAddChildNode()` to add _new_ nodes to the tree and `cxTreeSetParent()` | |
| 242 > to relink a subtree of the `tree` with a new parent. | |
| 243 > | |
| 244 > Using `cxTreeSetParent()` on a `child` which already has a parent in a _different_ tree is a mistake. | |
| 245 | |
| 246 The functions `cxTreeInsert()`, `cxTreeInsertIter()`, and `cxTreeInsertArray()` behave | |
| 247 like `cx_tree_add()`, `cx_tree_add_iter()`, and `cx_tree_add_array()`. | |
| 248 As creation context `cdata` for the `cx_tree_node_create_func` a pointer to the `CxTree` is passed. | |
| 249 Instead of returning a `failed` node, like the low-level functions, the high-level functions automatically free the memory for the failed node. | |
| 212 | 250 |
| 213 ## Size and Depth | 251 ## Size and Depth |
| 214 | 252 |
| 215 ```C | 253 ```C |
| 216 #include <cx/tree.h> | 254 #include <cx/tree.h> |
