comparison: docs/Writerside/topics/tree.h.md
docs/Writerside/topics/tree.h.md
- changeset 1690
- 7d41291b3095
- parent 1681
- 56e76fbac167
- child 1694
- a2757c6427cc
equal
deleted
inserted
replaced
| 1689:a5b7cf49dea7 | 1690:7d41291b3095 |
|---|---|
| 122 | 122 |
| 123 void cx_tree_add(void *parent, void *node, ptrdiff_t loc_parent, | 123 void cx_tree_add(void *parent, void *node, ptrdiff_t loc_parent, |
| 124 ptrdiff_t loc_children, ptrdiff_t loc_last_child, | 124 ptrdiff_t loc_children, ptrdiff_t loc_last_child, |
| 125 ptrdiff_t loc_prev, ptrdiff_t loc_next); | 125 ptrdiff_t loc_prev, ptrdiff_t loc_next); |
| 126 | 126 |
| 127 void *cxTreeCreateRootData(CxTree *tree, const void *data); | |
| 128 | |
| 129 void *cxTreeCreateRoot(CxTree *tree, void *child); | |
| 130 | |
| 131 void *cxTreeCreateNode(CxTree *tree, void *parent); | |
| 132 | |
| 127 void *cxTreeAddData(CxTree *tree, void *parent, const void *data); | 133 void *cxTreeAddData(CxTree *tree, void *parent, const void *data); |
| 128 | 134 |
| 129 void cxTreeAddNode(CxTree *tree, void *parent, void *child); | 135 void cxTreeAddNode(CxTree *tree, void *parent, void *child); |
| 130 | 136 |
| 131 void cxTreeSetParent(CxTree *tree, void *parent, void *child); | 137 void cxTreeSetParent(CxTree *tree, void *parent, void *child); |
| 138 | |
| 139 void *cxTreeSetRoot(CxTree *tree, void *root); | |
| 132 ``` | 140 ``` |
| 133 | 141 |
| 134 The low-level function `cx_tree_add()` adds a `node` to a new `parent`, unlinking it from its previous parent, if required. | 142 The low-level function `cx_tree_add()` adds a `node` to a new `parent`, unlinking it from its previous parent, if required. |
| 143 | |
| 144 When you have created a high-level tree that is still empty, you can create a root node with `cxTreeCreateRoot()` or `cxTreeCreateRootData()`. | |
| 145 Both functions return an existing root node, if present, and `NULL` when the allocation of a new node failed. | |
| 135 | 146 |
| 136 The functions `cxTreeAddData()`, `cxTreeAddNode()`, and `cxTreeSetParent()` are similar to `cx_tree_add()`. | 147 The functions `cxTreeAddData()`, `cxTreeAddNode()`, and `cxTreeSetParent()` are similar to `cx_tree_add()`. |
| 137 The difference between `cxTreeAddData()` and `cxTreeAddNode()` is, | 148 The difference between `cxTreeAddData()` and `cxTreeAddNode()` is, |
| 138 that `cxTreeAddData()` uses the allocator of the `CxTree` to create the node first, before adding it. | 149 that `cxTreeAddData()` uses the allocator of the `CxTree` to create the node first, before adding it. |
| 139 The function returns `NULL` in case the creation of the node fails, or the created node when creation was successful. | 150 The function returns `NULL` in case the creation of the node fails, or the created node when creation was successful. |
| 140 The difference between `cxTreeSetParent()` and `cxTreeAddNode()` is, | 151 The difference between `cxTreeSetParent()` and `cxTreeAddNode()` is, |
| 141 that `cxTreeSetParent()` does not increase the tree size, when `child` already had a parent. | 152 that `cxTreeSetParent()` does not increase the tree size, when `child` already had a parent. |
| 142 | 153 |
| 154 When you want to use `cxTreeCreateRootData()` or `cxTreeAddData()`, | |
| 155 the `loc_data` parameter of `cxTreeCreate()` must have been set to a non-negative value. | |
| 156 Otherwise, the functions will return `NULL`. | |
| 157 | |
| 143 > Use `cxTreeAddNode()` to add _new_ nodes to the tree and `cxTreeSetParent()` | 158 > Use `cxTreeAddNode()` to add _new_ nodes to the tree and `cxTreeSetParent()` |
| 144 > to relink a subtree of the `tree` with a new parent. | 159 > to relink a subtree of the `tree` with a new parent. |
| 145 > | 160 > |
| 146 > Using `cxTreeSetParent()` on a `child` which already has a parent in a _different_ tree is a mistake. | 161 > Using `cxTreeSetParent()` on a `child` which already has a parent in a _different_ tree is a mistake. |
| 147 | 162 |
| 163 The function `cxTreeSetRoot()` returns the current root node of the tree, | |
| 164 or `NULL` when the tree is empty, and sets a new root node. | |
| 165 It is up to the caller to take care of a possibly necessary deallocation of the old tree nodes. | |
| 166 Also, keep in mind that the tree might have destructors registered which will be applied to the nodes belonging to the new root. | |
| 148 | 167 |
| 149 ## Size and Depth | 168 ## Size and Depth |
| 150 | 169 |
| 151 ```C | 170 ```C |
| 152 #include <cx/tree.h> | 171 #include <cx/tree.h> |
