ucx: comparison src/cx/tree.h

-:e8f354a25ac8
+:68754c7de906
 /**
 * Releases internal memory of the given tree iterator.
 * @param iter the iterator
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 static inline void cxTreeIteratorDispose(CxTreeIterator *iter) {
 free(iter->stack);
 iter->stack = NULL;
 }
 /**
 * Releases internal memory of the given tree visitor.
 * @param visitor the visitor
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 static inline void cxTreeVisitorDispose(CxTreeVisitor *visitor) {
 struct cx_tree_visitor_queue_s *q = visitor->queue_next;
 while (q != NULL) {
 struct cx_tree_visitor_queue_s *next = q->next;
 free(q);
 * the last child in the linked list (negative if there is no such pointer)
 * @param loc_prev optional offset in the node struct for the prev pointer
 * @param loc_next offset in the node struct for the next pointer
 * @see cx_tree_unlink()
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 void cx_tree_link(
 void *restrict parent,
 void *restrict node,
 ptrdiff_t loc_parent,
 ptrdiff_t loc_children,
 * the last child in the linked list (negative if there is no such pointer)
 * @param loc_prev optional offset in the node struct for the prev pointer
 * @param loc_next offset in the node struct for the next pointer
 * @see cx_tree_link()
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 void cx_tree_unlink(
 void *node,
 ptrdiff_t loc_parent,
 ptrdiff_t loc_children,
 ptrdiff_t loc_last_child,
 *
 * @return 0 if the node contains the data,
 * positive if one of the children might contain the data,
 * negative if neither the node, nor the children contains the data
 */
+cx_attr_nonnull
 typedef int (*cx_tree_search_data_func)(const void *node, const void *data);
 /**
 * Function pointer for a search function.
 *
 * @return 0 if \p node contains the same data as \p new_node,
 * positive if one of the children might contain the data,
 * negative if neither the node, nor the children contains the data
 */
+cx_attr_nonnull
 typedef int (*cx_tree_search_func)(const void *node, const void *new_node);
 /**
 * Searches for data in a tree.
 *
 * @param loc_next offset in the node struct for the next pointer
 * @return zero if the node was found exactly, positive if a node was found that
 * could contain the node (but doesn't right now), negative if the tree does not
 * contain any node that might be related to the searched data
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
+cx_attr_access_w(5)
 int cx_tree_search_data(
 const void *root,
 size_t depth,
 const void *data,
 cx_tree_search_data_func sfunc,
 * @param loc_next offset in the node struct for the next pointer
 * @return zero if the node was found exactly, positive if a node was found that
 * could contain the node (but doesn't right now), negative if the tree does not
 * contain any node that might be related to the searched data
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
+cx_attr_access_w(5)
 int cx_tree_search(
 const void *root,
 size_t depth,
 const void *node,
 cx_tree_search_func sfunc,
 * @param loc_children offset in the node struct for the children linked list
 * @param loc_next offset in the node struct for the next pointer
 * @return the new tree iterator
 * @see cxTreeIteratorDispose()
 */
+cx_attr_nodiscard
 CxTreeIterator cx_tree_iterator(
 void *root,
 bool visit_on_exit,
 ptrdiff_t loc_children,
 ptrdiff_t loc_next
 * @param loc_children offset in the node struct for the children linked list
 * @param loc_next offset in the node struct for the next pointer
 * @return the new tree visitor
 * @see cxTreeVisitorDispose()
 */
+cx_attr_nodiscard
 CxTreeVisitor cx_tree_visitor(
 void *root,
 ptrdiff_t loc_children,
 ptrdiff_t loc_next
 );
 * created node or \c NULL when allocation fails.
 *
 * \note the function may leave the node pointers in the struct uninitialized.
 * The caller is responsible to set them according to the intended use case.
 */
+cx_attr_nonnull_arg(1)
 typedef void *(*cx_tree_node_create_func)(const void *, void *);
 /**
 * The local search depth for a new subtree when adding multiple elements.
 * The default value is 3.
 * @param loc_prev optional offset in the node struct for the prev pointer
 * @param loc_next offset in the node struct for the next pointer
 * @return the number of nodes created and added
 * @see cx_tree_add()
 */
-__attribute__((__nonnull__(1, 3, 4, 6, 7)))
+cx_attr_nonnull_arg(1, 3, 4, 6, 7)
+cx_attr_access_w(6)
 size_t cx_tree_add_iter(
 struct cx_iterator_base_s *iter,
 size_t num,
 cx_tree_search_func sfunc,
 cx_tree_node_create_func cfunc,
 * @param loc_prev optional offset in the node struct for the prev pointer
 * @param loc_next offset in the node struct for the next pointer
 * @return the number of array elements successfully processed
 * @see cx_tree_add()
 */
-__attribute__((__nonnull__(1, 4, 5, 7, 8)))
+cx_attr_nonnull_arg(1, 4, 5, 7, 8)
+cx_attr_access_w(7)
 size_t cx_tree_add_array(
 const void *src,
 size_t num,
 size_t elem_size,
 cx_tree_search_func sfunc,
 * @param loc_prev optional offset in the node struct for the prev pointer
 * @param loc_next offset in the node struct for the next pointer
 * @return zero when a new node was created and added to the tree,
 * non-zero otherwise
 */
-__attribute__((__nonnull__(1, 2, 3, 5, 6)))
+cx_attr_nonnull_arg(1, 2, 3, 5, 6)
+cx_attr_access_w(5)
 int cx_tree_add(
 const void *src,
 cx_tree_search_func sfunc,
 cx_tree_node_create_func cfunc,
 void *cdata,
 * Member function for inserting a single element.
 *
 * Implementations SHALL NOT simply invoke \p insert_many as this comes
 * with too much overhead.
 */
+cx_attr_nonnull
 int (*insert_element)(
 struct cx_tree_s *tree,
 const void *data
 );
 * Member function for inserting multiple elements.
 *
 * Implementations SHALL avoid to perform a full search in the tree for
 * every element even though the source data MAY be unsorted.
 */
+cx_attr_nonnull
 size_t (*insert_many)(
 struct cx_tree_s *tree,
 struct cx_iterator_base_s *iter,
 size_t n
 );
 /**
 * Member function for finding a node.
 */
+cx_attr_nonnull
 void *(*find)(
 struct cx_tree_s *tree,
 const void *subtree,
 const void *data,
 size_t depth
 /**
 * Common type for all tree implementations.
 */
 typedef struct cx_tree_s CxTree;
+/**
+* Destroys a node and it's subtree.
+*
+* It is guaranteed that the simple destructor is invoked before
+* the advanced destructor, starting with the leaf nodes of the subtree.
+*
+* When this function is invoked on the root node of the tree, it destroys the
+* tree contents, but - in contrast to #cxTreeDestroy() - not the tree
+* structure, leaving an empty tree behind.
+*
+* \note The destructor function, if any, will \em not be invoked. That means
+* you will need to free the removed subtree by yourself, eventually.
+*
+* \attention This function will not free the memory of the nodes with the
+* tree's allocator, because that is usually done by the advanced destructor
+* and would therefore result in a double-free.
+*
+* @param tree the tree
+* @param node the node to remove
+* @see cxTreeDestroy()
+*/
+cx_attr_nonnull
+void cxTreeDestroySubtree(CxTree *tree, void *node);
+/**
+* Destroys the tree contents.
+*
+* It is guaranteed that the simple destructor is invoked before
+* the advanced destructor, starting with the leaf nodes of the subtree.
+*
+* This is a convenience macro for invoking #cxTreeDestroySubtree() on the
+* root node of the tree.
+*
+* \attention Be careful when calling this function when no destructor function
+* is registered that actually frees the memory of nodes. In that case you will
+* need a reference to the (former) root node of the tree somewhere or
+* otherwise you will be leaking memory.
+*
+* @param tree the tree
+* @see cxTreeDestroySubtree()
+*/
+#define cxTreeClear(tree) cxTreeDestroySubtree(tree, tree->root)
+/**
+* Destroys the tree structure.
+*
+* The destructor functions are invoked for each node, starting with the leaf
+* nodes.
+* It is guaranteed that for each node the simple destructor is invoked before
+* the advanced destructor.
+*
+* \attention This function will only invoke the destructor functions
+* on the nodes.
+* It will NOT additionally free the nodes with the tree's allocator, because
+* that would cause a double-free in most scenarios where the advanced
+* destructor is already freeing the memory.
+*
+* @param tree the tree to destroy
+*/
+static inline void cxTreeDestroy(CxTree *tree) {
+if (tree == NULL) return;
+if (tree->root != NULL) {
+cxTreeClear(tree);
+}
+cxFree(tree->allocator, tree);
+}
 /**
 * Creates a new tree structure based on the specified layout.
 *
 * The specified \p allocator will be used for creating the tree struct
 * @param loc_next offset in the node struct for the next pointer
 * @return the new tree
 * @see cxTreeCreateSimple()
 * @see cxTreeCreateWrapped()
 */
-__attribute__((__nonnull__, __warn_unused_result__))
+cx_attr_nonnull
+cx_attr_nodiscard
+cx_attr_malloc
+cx_attr_dealloc(cxTreeDestroy, 1)
 CxTree *cxTreeCreate(
 const CxAllocator *allocator,
 cx_tree_node_create_func create_func,
 cx_tree_search_func search_func,
 cx_tree_search_data_func search_data_func,
 * @param search_func a function that compares two nodes
 * @param search_data_func a function that compares a node with data
 * @return the new tree
 * @see cxTreeCreate()
 */
-__attribute__((__nonnull__, __warn_unused_result__))
+#define cxTreeCreateSimple(\
-static inline CxTree *cxTreeCreateSimple(
+allocator, create_func, search_func, search_data_func \
-const CxAllocator *allocator,
+) cxTreeCreate(allocator, create_func, search_func, search_data_func, \
-cx_tree_node_create_func create_func,
+cx_tree_node_base_layout)
-cx_tree_search_func search_func,
-cx_tree_search_data_func search_data_func
-) {
-return cxTreeCreate(
-allocator,
-create_func,
-search_func,
-search_data_func,
-cx_tree_node_base_layout
-);
-}
 /**
 * Creates a new tree structure based on an existing tree.
 *
 * The specified \p allocator will be used for creating the tree struct.
 * @param loc_prev optional offset in the node struct for the prev pointer
 * @param loc_next offset in the node struct for the next pointer
 * @return the new tree
 * @see cxTreeCreate()
 */
-__attribute__((__nonnull__, __warn_unused_result__))
+cx_attr_nonnull
+cx_attr_nodiscard
+cx_attr_malloc
+cx_attr_dealloc(cxTreeDestroy, 1)
 CxTree *cxTreeCreateWrapped(
 const CxAllocator *allocator,
 void *root,
 ptrdiff_t loc_parent,
 ptrdiff_t loc_children,
 *
 * @param tree the tree
 * @param data the data to insert
 * @return zero on success, non-zero on failure
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 static inline int cxTreeInsert(
 CxTree *tree,
 const void *data
 ) {
 return tree->cl->insert_element(tree, data);
 * @param tree the tree
 * @param iter the iterator providing the elements
 * @param n the maximum number of elements to insert
 * @return the number of elements that could be successfully inserted
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 static inline size_t cxTreeInsertIter(
 CxTree *tree,
 struct cx_iterator_base_s *iter,
 size_t n
 ) {
 * @param data the array of data to insert
 * @param elem_size the size of each element in the array
 * @param n the number of elements in the array
 * @return the number of elements that could be successfully inserted
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 static inline size_t cxTreeInsertArray(
 CxTree *tree,
 const void *data,
 size_t elem_size,
 size_t n
 *
 * @param tree the tree
 * @param data the data to search for
 * @return the first matching node, or \c NULL when the data cannot be found
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
+cx_attr_nodiscard
 static inline void *cxTreeFind(
 CxTree *tree,
 const void *data
 ) {
 return tree->cl->find(tree, tree->root, data, 0);
 * @param data the data to search for
 * @param subtree_root the node where to start
 * @param max_depth the maximum search depth
 * @return the first matching node, or \c NULL when the data cannot be found
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
+cx_attr_nodiscard
 static inline void *cxTreeFindInSubtree(
 CxTree *tree,
 const void *data,
 void *subtree_root,
 size_t max_depth
 *
 * @param tree the tree
 * @param subtree_root the root node of the subtree
 * @return the number of nodes in the specified subtree
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
+cx_attr_nodiscard
 size_t cxTreeSubtreeSize(CxTree *tree, void *subtree_root);
 /**
 * Determines the depth of the specified subtree.
 *
 * @param tree the tree
 * @param subtree_root the root node of the subtree
 * @return the tree depth including the \p subtree_root
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
+cx_attr_nodiscard
 size_t cxTreeSubtreeDepth(CxTree *tree, void *subtree_root);
 /**
 * Determines the depth of the entire tree.
 *
 * @param tree the tree
 * @return the tree depth, counting the root as one
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
+cx_attr_nodiscard
 size_t cxTreeDepth(CxTree *tree);
 /**
 * Creates a depth-first iterator for the specified tree starting in \p node.
 *
 * @param visit_on_exit true, if the iterator shall visit a node again when
 * leaving the subtree
 * @return a tree iterator (depth-first)
 * @see cxTreeVisit()
 */
-__attribute__((__nonnull__, __warn_unused_result__))
+cx_attr_nonnull
+cx_attr_nodiscard
 static inline CxTreeIterator cxTreeIterateSubtree(
 CxTree *tree,
 void *node,
 bool visit_on_exit
 ) {
 * @param tree the tree to iterate
 * @param node the node where to start
 * @return a tree visitor (a.k.a. breadth-first iterator)
 * @see cxTreeIterate()
 */
-__attribute__((__nonnull__, __warn_unused_result__))
+cx_attr_nonnull
+cx_attr_nodiscard
 static inline CxTreeVisitor cxTreeVisitSubtree(CxTree *tree, void *node) {
 return cx_tree_visitor(
 node, tree->loc_children, tree->loc_next
 );
 }
 * @param visit_on_exit true, if the iterator shall visit a node again when
 * leaving the subtree
 * @return a tree iterator (depth-first)
 * @see cxTreeVisit()
 */
-__attribute__((__nonnull__, __warn_unused_result__))
+cx_attr_nonnull
+cx_attr_nodiscard
 static inline CxTreeIterator cxTreeIterate(
 CxTree *tree,
 bool visit_on_exit
 ) {
 return cxTreeIterateSubtree(tree, tree->root, visit_on_exit);
 *
 * @param tree the tree to iterate
 * @return a tree visitor (a.k.a. breadth-first iterator)
 * @see cxTreeIterate()
 */
-__attribute__((__nonnull__, __warn_unused_result__))
+cx_attr_nonnull
+cx_attr_nodiscard
 static inline CxTreeVisitor cxTreeVisit(CxTree *tree) {
 return cxTreeVisitSubtree(tree, tree->root);
 }
 /**
 * @param tree the tree
 * @param parent the (new) parent of the child
 * @param child the node to add
 * @see cxTreeAddChildNode()
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 void cxTreeSetParent(
 CxTree *tree,
 void *parent,
 void *child
 );
 * @param tree the tree
 * @param parent the parent of the node to add
 * @param child the node to add
 * @see cxTreeSetParent()
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 void cxTreeAddChildNode(
 CxTree *tree,
 void *parent,
 void *child
 );
 * @param parent the parent node of the new node
 * @param data the data that will be submitted to the create function
 * @return zero when the new node was created, non-zero on allocation failure
 * @see cxTreeInsert()
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 int cxTreeAddChild(
 CxTree *tree,
 void *parent,
 const void *data
 );
 *
 * @param node the affected node
 * @param old_parent the old parent of the node
 * @param new_parent the new parent of the node
 */
+cx_attr_nonnull
 typedef void (*cx_tree_relink_func)(
 void *node,
 const void *old_parent,
 const void *new_parent
 );
 * @param node the node to remove (must not be the root node)
 * @param relink_func optional callback to update the content of each re-linked
 * node
 * @return zero on success, non-zero if \p node is the root node of the tree
 */
-__attribute__((__nonnull__(1,2)))
+cx_attr_nonnull_arg(1, 2)
 int cxTreeRemoveNode(
 CxTree *tree,
 void *node,
 cx_tree_relink_func relink_func
 );
 * you will need to free the removed subtree by yourself, eventually.
 *
 * @param tree the tree
 * @param node the node to remove
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 void cxTreeRemoveSubtree(CxTree *tree, void *node);
 /**
 * Destroys a node and re-links its children to its former parent.
 *
 * @param node the node to destroy (must not be the root node)
 * @param relink_func optional callback to update the content of each re-linked
 * node
 * @return zero on success, non-zero if \p node is the root node of the tree
 */
-__attribute__((__nonnull__(1,2)))
+cx_attr_nonnull_arg(1, 2)
 int cxTreeDestroyNode(
 CxTree *tree,
 void *node,
 cx_tree_relink_func relink_func
 );
-/**
-* Destroys a node and it's subtree.
-*
-* It is guaranteed that the simple destructor is invoked before
-* the advanced destructor, starting with the leaf nodes of the subtree.
-*
-* When this function is invoked on the root node of the tree, it destroys the
-* tree contents, but - in contrast to #cxTreeDestroy() - not the tree
-* structure, leaving an empty tree behind.
-*
-* \note The destructor function, if any, will \em not be invoked. That means
-* you will need to free the removed subtree by yourself, eventually.
-*
-* \attention This function will not free the memory of the nodes with the
-* tree's allocator, because that is usually done by the advanced destructor
-* and would therefore result in a double-free.
-*
-* @param tree the tree
-* @param node the node to remove
-* @see cxTreeDestroy()
-*/
-__attribute__((__nonnull__))
-void cxTreeDestroySubtree(CxTree *tree, void *node);
-/**
-* Destroys the tree contents.
-*
-* It is guaranteed that the simple destructor is invoked before
-* the advanced destructor, starting with the leaf nodes of the subtree.
-*
-* This is a convenience macro for invoking #cxTreeDestroySubtree() on the
-* root node of the tree.
-*
-* \attention Be careful when calling this function when no destructor function
-* is registered that actually frees the memory of nodes. In that case you will
-* need a reference to the (former) root node of the tree somewhere or
-* otherwise you will be leaking memory.
-*
-* @param tree the tree
-* @see cxTreeDestroySubtree()
-*/
-#define cxTreeClear(tree) cxTreeDestroySubtree(tree, tree->root)
-/**
-* Destroys the tree structure.
-*
-* The destructor functions are invoked for each node, starting with the leaf
-* nodes.
-* It is guaranteed that for each node the simple destructor is invoked before
-* the advanced destructor.
-*
-* \attention This function will only invoke the destructor functions
-* on the nodes.
-* It will NOT additionally free the nodes with the tree's allocator, because
-* that would cause a double-free in most scenarios where the advanced
-* destructor is already freeing the memory.
-*
-* @param tree the tree to destroy
-*/
-__attribute__((__nonnull__))
-static inline void cxTreeDestroy(CxTree *tree) {
-if (tree->root != NULL) {
-cxTreeDestroySubtree(tree, tree->root);
-}
-cxFree(tree->allocator, tree);
-}
 #ifdef __cplusplus
 } // extern "C"
 #endif
 #endif //UCX_TREE_H

Mercurial > hg > ucx / file comparison

comparison: src/cx/tree.h

src/cx/tree.h