comparison: src/cx/tree.h
src/cx/tree.h
- changeset 1690
- 7d41291b3095
- parent 1681
- 56e76fbac167
- child 1692
- 56731bb98508
equal
deleted
inserted
replaced
| 1689:a5b7cf49dea7 | 1690:7d41291b3095 |
|---|---|
| 482 * Creates a new tree. | 482 * Creates a new tree. |
| 483 * | 483 * |
| 484 * The specified @p allocator will be used for creating the tree struct | 484 * The specified @p allocator will be used for creating the tree struct |
| 485 * @em and the nodes. | 485 * @em and the nodes. |
| 486 * | 486 * |
| 487 * When you do not specify an existing @p root, the tree will be created | |
| 488 * empty. Additionally, cxFree() is registered as the advanced destructor for | |
| 489 * the tree so that all nodes that you will add to the tree are automatically | |
| 490 * freed together with the tree. | |
| 491 * When @p root is not @c NULL, no destructors are registered automatically. | |
| 492 * | |
| 487 * @param allocator the allocator to use | 493 * @param allocator the allocator to use |
| 488 * (if @c NULL, the cxDefaultAllocator is assumed) | 494 * (if @c NULL, the cxDefaultAllocator is assumed) |
| 489 * @param node_size the complete size of one node | 495 * @param node_size the complete size of one node |
| 490 * @param elem_size the size of the payload stored in the node | 496 * @param elem_size the size of the payload stored in the node |
| 491 * (@c CX_STORE_POINTERS is also supported) | 497 * (@c CX_STORE_POINTERS is also supported) |
| 718 * @see cxTreeAdd() | 724 * @see cxTreeAdd() |
| 719 */ | 725 */ |
| 720 CX_EXTERN CX_NONNULL | 726 CX_EXTERN CX_NONNULL |
| 721 void *cxTreeAddData(CxTree *tree, void *parent, const void *data); | 727 void *cxTreeAddData(CxTree *tree, void *parent, const void *data); |
| 722 | 728 |
| 723 CX_EXTERN CX_NODISCARD | 729 /** |
| 730 * Creates a new node and adds it to the tree. | |
| 731 * | |
| 732 * @param tree the tree | |
| 733 * @param parent the parent node of the new node | |
| 734 * @return the added node or @c NULL when the allocation failed | |
| 735 */ | |
| 736 CX_EXTERN CX_NODISCARD CX_NONNULL | |
| 737 void *cxTreeCreateNode(CxTree *tree, void *parent); | |
| 738 | |
| 739 /** | |
| 740 * Creates a new root node or returns the existing root node. | |
| 741 * | |
| 742 * @param tree the tree | |
| 743 * @return the new root node, the existing root node, or @c NULL when the allocation failed | |
| 744 * @see cxTreeCreateRootData() | |
| 745 */ | |
| 746 CX_EXTERN CX_NODISCARD CX_NONNULL | |
| 724 void *cxTreeCreateRoot(CxTree *tree); | 747 void *cxTreeCreateRoot(CxTree *tree); |
| 725 | 748 |
| 726 CX_EXTERN CX_NODISCARD | 749 /** |
| 750 * Creates a new root node or uses the existing root node and writes the specified data to that node. | |
| 751 * | |
| 752 * @note This function immediately returns @c NULL when @c loc_data was not initialized with a positive value. | |
| 753 * | |
| 754 * @param tree the tree | |
| 755 * @param data the data for the root node | |
| 756 * @return the new root node, the existing root node, | |
| 757 * or @c NULL when the allocation failed or the data location is not known | |
| 758 * @see cxTreeCreateRoot() | |
| 759 */ | |
| 760 CX_EXTERN CX_NODISCARD CX_NONNULL | |
| 727 void *cxTreeCreateRootData(CxTree *tree, const void *data); | 761 void *cxTreeCreateRootData(CxTree *tree, const void *data); |
| 728 | 762 |
| 763 /** | |
| 764 * Exchanges the root of the tree. | |
| 765 * | |
| 766 * @attention The old tree nodes might need to be deallocated by the caller. | |
| 767 * On the other hand, when the tree has destructors registered, keep in mind | |
| 768 * that they will be applied to the new tree. | |
| 769 * In particular, using cxTreeCreate() with a @c NULL root and setting the | |
| 770 * root with this function is @em not equivalent to creating the tree with | |
| 771 * a reference to an existing root because trees created without a root will | |
| 772 * have destructors registered. | |
| 773 * | |
| 774 * @param tree the tree | |
| 775 * @param new_root the new root node | |
| 776 * @return the old root node (or @c NULL when the tree was empty) | |
| 777 */ | |
| 729 CX_EXTERN CX_NONNULL_ARG(1) CX_NODISCARD | 778 CX_EXTERN CX_NONNULL_ARG(1) CX_NODISCARD |
| 730 void *cxTreeSetRoot(CxTree *tree, void *new_root); | 779 void *cxTreeSetRoot(CxTree *tree, void *new_root); |
| 731 | 780 |
| 732 /** | 781 /** |
| 733 * A function that is invoked when a node needs to be re-linked to a new parent. | 782 * A function that is invoked when a node needs to be re-linked to a new parent. |
