// SPDX-License-Identifier: BSD-2-Clause // Copyright (C) 2015 Andrea Mazzoleni /** \file * AVL tree. * * This tree is a standard AVL tree implementation that stores elements in the * order defined by the comparison function. * * Duplicate elements are allowed. They are visited in insertion order. * Use tommy_tree_insert_unique() to reject duplicate keys. * * To initialize a tree you have to call tommy_tree_init() specifying a comparison * function that will define the order in the tree. * * \code * tommy_tree tree; * * tommy_tree_init(&tree, cmp); * \endcode * * To insert elements in the tree you have to call tommy_tree_insert() for * each element. * In the insertion call you have to specify the address of the node and the * address of the element. * The address of the element is used to initialize the tommy_node::data field * of the node. * * \code * struct element { * int value; * // other fields * tommy_tree_node node; * }; * * struct element* elem = malloc(sizeof(struct element)); // creates the element * * elem->value = ...; // initializes the element * * tommy_tree_insert(&tree, &elem->node, elem); // inserts the element * \endcode * * To find the first element with a given key in tree order, call * tommy_tree_search() providing the key to search. * * \code * struct element value_to_find = { 1 }; * struct element* elem = tommy_tree_search(&tree, &value_to_find); * if (!elem) { * // not found * } else { * // found * } * \endcode * * To iterate over all the elements in the tree you can call * tommy_tree_head() to get the head of the tree and follow the * next elements with tommy_tree_next(). * * \code * tommy_tree_node* i = tommy_tree_head(&tree); * while (i) { * struct element* elem = i->data; // gets the element pointer * * printf("%d\n", elem->value); // process the element * * i = tommy_tree_next(i); // go to the next element * } * \endcode * * \anchor tommy_tree_iterator_validity * Iterators are pointers to nodes contained in the tree. * Inserting elements or removing other nodes between iterator calls does not * invalidate pointers to nodes that remain in the tree. * Subsequent next/prev calls use the current contents and ordering; * inserted elements may become visible and removed elements are skipped. * * Removing the pointed node invalidates its use as an iterator, even if * its storage has not been freed. To continue traversal after removing * the current node, obtain the next or previous node before removal. * * Keys and fields used for ordering must not be modified while contained. * Concurrent traversal and modification require external synchronization. * * To remove the first element with a given key in tree order, call * tommy_tree_remove() providing the key to search and remove. * * \code * struct element value_to_remove = { 1 }; * struct element* elem = tommy_tree_remove(&tree, &value_to_remove); * if (elem) { * free(elem); // frees the element allocated memory * } * \endcode * * You can also remove an element from the tree if you already have the node * address using tommy_tree_remove_existing(). * * \code * struct element* elem = ...; * tommy_tree_remove_existing(&tree, &elem->node); * free(elem); * \endcode * * To remove the smallest or greatest element you can use tommy_tree_remove_head() * or tommy_tree_remove_tail(). * * \code * struct element* elem = tommy_tree_remove_head(&tree); * if (elem) { * free(elem); * } * \endcode * * To destroy the tree you have to remove or destroy all the contained elements. * The tree itself doesn't have or need a deallocation function. * This can be done with the tommy_tree_foreach() function. * * \code * // deallocates all the elements iterating the tree * tommy_tree_foreach(&tree, free); * \endcode */ #ifndef TOMMY_TREE_H #define TOMMY_TREE_H #include "tommytypes.h" #include "tommylist.h" /******************************************************************************/ /* tree */ /** * Tree node. * This is the node that you have to include inside your elements. * The node must preserve its natural alignment because the tree stores the * balance factor in the two least significant bits of the parent pointer. */ typedef tommy_node tommy_tree_node; /** * Tree container type. * \note Don't use internal fields directly, but access the container only using functions. */ typedef struct tommy_tree_struct { tommy_tree_node* root; /**< Root node. */ tommy_compare_func* cmp; /**< Comparison function. */ tommy_size_t count; /**< Number of elements. */ } tommy_tree; /** * Initializes the tree. * \param tree The tree. * \param cmp The comparison function that defines the order in the tree. */ tommy_inline void tommy_tree_init(tommy_tree* tree, tommy_compare_func* cmp) { tree->root = 0; tree->count = 0; tree->cmp = cmp; } /** * Exchanges the contents of two initialized trees, including their comparison functions. * Each comparison function moves with its root to preserve the tree order. * The trees must not share nodes. Nodes are not accessed or modified. * Passing the same tree twice has no effect. * \param first The first tree. * \param second The second tree. * \note This operation is O(1). */ tommy_inline void tommy_tree_swap(tommy_tree* first, tommy_tree* second) { tommy_tree tmp = *first; *first = *second; *second = tmp; } /** * Removes all elements, preserving the comparison function. * The tree remains initialized and can be reused immediately. * Elements are not freed and nodes are not accessed or modified. * Their links must not be used to traverse the previous contents. * You can call this function after tommy_tree_foreach() has freed the elements. * \param tree The tree. * \note This operation is O(1). */ tommy_inline void tommy_tree_clear(tommy_tree* tree) { tree->root = 0; tree->count = 0; } /** * Inserts an element in the tree, allowing duplicate keys. * Equal elements are visited in insertion order. * You have to provide the pointer of the node embedded into the element and * the pointer to the element. * \param tree The tree. * \param node Pointer to the node embedded into the element to insert. * \param data Pointer to the element to insert. */ TOMMY_API void tommy_tree_insert(tommy_tree* tree, tommy_tree_node* node, void* data); /** * Inserts an element only if no equal element is already contained. * If found, the first equal element in tree order is returned and the * candidate node is left unchanged. Otherwise the candidate is inserted * and data is returned. * \param tree The tree. * \param node The candidate node. It must not belong to any container. * \param data Pointer to the element to insert. * \return The first equal element, or data if the candidate was inserted. */ TOMMY_API void* tommy_tree_insert_unique(tommy_tree* tree, tommy_tree_node* node, void* data); /** * Transfers all elements from the tree to the tail of a list in tree order. * Existing list elements remain before the transferred elements. The tree is * left empty and initialized with its original comparison function. * The list must be initialized and must not share nodes with the tree. * Elements are not freed, and the node data and index fields are left unchanged. * The index field no longer represents a valid tree parent after the transfer. * \param tree The tree to drain. * \param list The destination list. * \note This operation is O(n), using O(log n) stack space. */ TOMMY_API void tommy_tree_to_list(tommy_tree* tree, tommy_list* list); /** * Removes an element from the tree. * You must already have the address of the node to remove. * \param tree The tree. * \param node The node to remove. * \return The removed element. */ TOMMY_API void* tommy_tree_remove_existing(tommy_tree* tree, tommy_tree_node* node); /** * Gets the parent of the specified node. * \param node Node contained in the tree. * \return The parent node. For the root node 0 is returned. */ tommy_inline tommy_tree_node* tommy_tree_parent(tommy_tree_node* node) { return (tommy_tree_node*)(tommy_uintptr_t)(node->index & ~(tommy_size_t)3); } /** * Gets the node following the specified one in tree order. * See \ref tommy_tree_iterator_validity for iterator validity across insertions and removals. * \param node Node contained in the tree. * \return The following node, or 0 for the tail node. * \note This operation is O(log n), and amortized O(1) during full traversal. */ tommy_inline tommy_tree_node* tommy_tree_next(tommy_tree_node* node) { if (node->next) { node = node->next; while (node->prev) node = node->prev; return node; } tommy_tree_node* parent = tommy_tree_parent(node); while (parent && node == parent->next) { node = parent; parent = tommy_tree_parent(parent); } return parent; } /** * Gets the node preceding the specified one in tree order. * See \ref tommy_tree_iterator_validity for iterator validity across insertions and removals. * \param node Node contained in the tree. * \return The preceding node, or 0 for the head node. * \note This operation is O(log n), and amortized O(1) during full traversal. */ tommy_inline tommy_tree_node* tommy_tree_prev(tommy_tree_node* node) { if (node->prev) { node = node->prev; while (node->next) node = node->next; return node; } tommy_tree_node* parent = tommy_tree_parent(node); while (parent && node == parent->prev) { node = parent; parent = tommy_tree_parent(parent); } return parent; } /** * Gets the head (smallest) node in the tree. * \param tree The tree. * \return The head node, or 0 if the tree is empty. * \note This operation is O(log n). */ tommy_inline tommy_tree_node* tommy_tree_head(tommy_tree* tree) { tommy_tree_node* node = tree->root; if (!node) return 0; while (node->prev) node = node->prev; return node; } /** * Gets the tail (greatest) node in the tree. * \param tree The tree. * \return The tail node, or 0 if the tree is empty. * \note This operation is O(log n). */ tommy_inline tommy_tree_node* tommy_tree_tail(tommy_tree* tree) { tommy_tree_node* node = tree->root; if (!node) return 0; while (node->next) node = node->next; return node; } /** * Removes and returns the head (smallest) element. * If the tree is empty, 0 is returned. * \param tree The tree. * \return The removed element, or 0 if the tree is empty. */ tommy_inline void* tommy_tree_remove_head(tommy_tree* tree) { tommy_tree_node* node = tommy_tree_head(tree); if (!node) return 0; return tommy_tree_remove_existing(tree, node); } /** * Removes and returns the tail (greatest) element. * If the tree is empty, 0 is returned. * \param tree The tree. * \return The removed element, or 0 if the tree is empty. */ tommy_inline void* tommy_tree_remove_tail(tommy_tree* tree) { tommy_tree_node* node = tommy_tree_tail(tree); if (!node) return 0; return tommy_tree_remove_existing(tree, node); } /** * Finds the first equal node in the tree with a specific comparison function. * * Like tommy_tree_find() but you can specify a different comparison function. * Note that this function must define a suborder of the original one. * The first equal node in tree order is returned. * * The cmp_arg argument will be the first argument of the comparison function, * and it can be of a different type than the elements in the tree. * \param tree The tree. * \param cmp Comparison function called with cmp_arg and the element in the tree. * \param cmp_arg Search key, which may have a different type from tree elements. * \return The first equal node in tree order, or 0 if none. */ tommy_inline tommy_tree_node* tommy_tree_find_compare(tommy_tree* tree, tommy_compare_func* cmp, const void* cmp_arg) { tommy_tree_node* node = tree->root; tommy_tree_node* candidate = 0; while (node) { /* comparators must not change the tree, so retain the data across the call */ void* data = node->data; int c = cmp(cmp_arg, data); if (c < 0) node = node->prev; else if (c > 0) node = node->next; else { candidate = node; node = node->prev; } } return candidate; } /** * Finds the first equal node in the tree. * If the element is not found, 0 is returned. * \param tree The tree. * \param data Element used for comparison. * \return The first equal node in tree order, or 0 if none. */ tommy_inline tommy_tree_node* tommy_tree_find(tommy_tree* tree, const void* data) { return tommy_tree_find_compare(tree, tree->cmp, data); } /** * Searches an element in the tree with a specific comparison function. * * Like tommy_tree_search() but you can specify a different comparison function. * Note that this function must define a suborder of the original one. * The first equal element in tree order is returned. * * The cmp_arg argument will be the first argument of the comparison function, * and it can be of a different type than the elements in the tree. * \param tree The tree. * \param cmp Comparison function called with cmp_arg and the element in the tree. * \param cmp_arg Search key, which may have a different type from tree elements. * \return The first equal element in tree order, or 0 if none. */ tommy_inline void* tommy_tree_search_compare(tommy_tree* tree, tommy_compare_func* cmp, const void* cmp_arg) { tommy_tree_node* node = tommy_tree_find_compare(tree, cmp, cmp_arg); return node ? node->data : 0; } /** * Searches an element in the tree. * If the element is not found, 0 is returned. * \param tree The tree. * \param data Element used for comparison. * \return The first equal element in tree order, or 0 if none. */ tommy_inline void* tommy_tree_search(tommy_tree* tree, const void* data) { tommy_tree_node* node = tommy_tree_find(tree, data); return node ? node->data : 0; } /** * Finds a node in the tree with key greater or equal than the specified one with a specific comparison function. * * Like tommy_tree_find_greater_equal() but you can specify a different comparison function. * Note that this function must define a suborder of the original one. * The first qualifying node in tree order is returned. * * The cmp_arg argument will be the first argument of the comparison function, * and it can be of a different type than the elements in the tree. * \param tree The tree. * \param cmp Comparison function called with cmp_arg and the element in the tree. * \param cmp_arg Search key, which may have a different type from tree elements. * \return The first node in tree order with key greater or equal, or 0 if none. */ tommy_inline tommy_tree_node* tommy_tree_find_greater_equal_compare(tommy_tree* tree, tommy_compare_func* cmp, const void* cmp_arg) { tommy_tree_node* node = tree->root; tommy_tree_node* candidate = 0; while (node) { /* comparators must not change the tree, so retain the data across the call */ void* data = node->data; int c = cmp(cmp_arg, data); if (c <= 0) { candidate = node; node = node->prev; } else { node = node->next; } } return candidate; } /** * Finds a node in the tree with key greater or equal than the specified one. * If no such element exists, 0 is returned. * \param tree The tree. * \param data Element used for comparison. * \return The first node in tree order with key greater or equal, or 0 if none. */ tommy_inline tommy_tree_node* tommy_tree_find_greater_equal(tommy_tree* tree, const void* data) { return tommy_tree_find_greater_equal_compare(tree, tree->cmp, data); } /** * Searches an element in the tree with key greater or equal than the specified one with a specific comparison function. * * Like tommy_tree_search_greater_equal() but you can specify a different comparison function. * Note that this function must define a suborder of the original one. * The first qualifying element in tree order is returned. * * The cmp_arg argument will be the first argument of the comparison function, * and it can be of a different type than the elements in the tree. * \param tree The tree. * \param cmp Comparison function called with cmp_arg and the element in the tree. * \param cmp_arg Search key, which may have a different type from tree elements. * \return The first element in tree order with key greater or equal, or 0 if none. */ tommy_inline void* tommy_tree_search_greater_equal_compare(tommy_tree* tree, tommy_compare_func* cmp, const void* cmp_arg) { tommy_tree_node* node = tommy_tree_find_greater_equal_compare(tree, cmp, cmp_arg); return node ? node->data : 0; } /** * Searches an element in the tree with key greater or equal than the specified one. * If no such element exists, 0 is returned. * \param tree The tree. * \param data Element used for comparison. * \return The first element in tree order with key greater or equal, or 0 if none. */ tommy_inline void* tommy_tree_search_greater_equal(tommy_tree* tree, const void* data) { tommy_tree_node* node = tommy_tree_find_greater_equal(tree, data); return node ? node->data : 0; } /** * Finds the first node in tree order with key strictly greater than the specified one using a specific comparison function. * The function must define a suborder of the tree comparison function. * Equivalent elements are excluded from the result. * \param tree The tree. * \param cmp Comparison function called with cmp_arg and the element in the tree. * \param cmp_arg Search key, which may have a different type from tree elements. * \return The first strictly greater node, or 0 if none. */ tommy_inline tommy_tree_node* tommy_tree_find_greater_compare(tommy_tree* tree, tommy_compare_func* cmp, const void* cmp_arg) { tommy_tree_node* node = tree->root; tommy_tree_node* candidate = 0; while (node) { /* comparators must not change the tree, so retain the data across the call */ void* data = node->data; int c = cmp(cmp_arg, data); if (c < 0) { candidate = node; node = node->prev; } else { node = node->next; } } return candidate; } /** * Finds the first node in tree order with key strictly greater than the specified one. * If no such element exists, 0 is returned. * \param tree The tree. * \param data Element used for comparison. * \return The first strictly greater node, or 0 if none. */ tommy_inline tommy_tree_node* tommy_tree_find_greater(tommy_tree* tree, const void* data) { return tommy_tree_find_greater_compare(tree, tree->cmp, data); } /** * Searches the first element in tree order with key strictly greater than the specified one using a specific comparison function. * The function must define a suborder of the tree comparison function. * Equivalent elements are excluded from the result. * \param tree The tree. * \param cmp Comparison function called with cmp_arg and the element in the tree. * \param cmp_arg Search key, which may have a different type from tree elements. * \return The first strictly greater element, or 0 if none. */ tommy_inline void* tommy_tree_search_greater_compare(tommy_tree* tree, tommy_compare_func* cmp, const void* cmp_arg) { tommy_tree_node* node = tommy_tree_find_greater_compare(tree, cmp, cmp_arg); return node ? node->data : 0; } /** * Searches the first element in tree order with key strictly greater than the specified one. * If no such element exists, 0 is returned. * \param tree The tree. * \param data Element used for comparison. * \return The first strictly greater element, or 0 if none. */ tommy_inline void* tommy_tree_search_greater(tommy_tree* tree, const void* data) { tommy_tree_node* node = tommy_tree_find_greater(tree, data); return node ? node->data : 0; } /** * Finds a node in the tree with key less or equal than the specified one with a specific comparison function. * * Like tommy_tree_find_less_equal() but you can specify a different comparison function. * Note that this function must define a suborder of the original one. * The last qualifying node in tree order is returned. * * The cmp_arg argument will be the first argument of the comparison function, * and it can be of a different type than the elements in the tree. * \param tree The tree. * \param cmp Comparison function called with cmp_arg and the element in the tree. * \param cmp_arg Search key, which may have a different type from tree elements. * \return The last node in tree order with key less or equal, or 0 if none. */ tommy_inline tommy_tree_node* tommy_tree_find_less_equal_compare(tommy_tree* tree, tommy_compare_func* cmp, const void* cmp_arg) { tommy_tree_node* node = tree->root; tommy_tree_node* candidate = 0; while (node) { /* comparators must not change the tree, so retain the data across the call */ void* data = node->data; int c = cmp(cmp_arg, data); if (c < 0) { node = node->prev; } else { candidate = node; node = node->next; } } return candidate; } /** * Finds a node in the tree with key less or equal than the specified one. * If no such element exists, 0 is returned. * \param tree The tree. * \param data Element used for comparison. * \return The last node in tree order with key less or equal, or 0 if none. */ tommy_inline tommy_tree_node* tommy_tree_find_less_equal(tommy_tree* tree, const void* data) { return tommy_tree_find_less_equal_compare(tree, tree->cmp, data); } /** * Searches an element in the tree with key less or equal than the specified one with a specific comparison function. * * Like tommy_tree_search_less_equal() but you can specify a different comparison function. * Note that this function must define a suborder of the original one. * The last qualifying element in tree order is returned. * * The cmp_arg argument will be the first argument of the comparison function, * and it can be of a different type than the elements in the tree. * \param tree The tree. * \param cmp Comparison function called with cmp_arg and the element in the tree. * \param cmp_arg Search key, which may have a different type from tree elements. * \return The last element in tree order with key less or equal, or 0 if none. */ tommy_inline void* tommy_tree_search_less_equal_compare(tommy_tree* tree, tommy_compare_func* cmp, const void* cmp_arg) { tommy_tree_node* node = tommy_tree_find_less_equal_compare(tree, cmp, cmp_arg); return node ? node->data : 0; } /** * Searches an element in the tree with key less or equal than the specified one. * If no such element exists, 0 is returned. * \param tree The tree. * \param data Element used for comparison. * \return The last element in tree order with key less or equal, or 0 if none. */ tommy_inline void* tommy_tree_search_less_equal(tommy_tree* tree, const void* data) { tommy_tree_node* node = tommy_tree_find_less_equal(tree, data); return node ? node->data : 0; } /** * Finds the last node in tree order with key strictly less than the specified one using a specific comparison function. * The function must define a suborder of the tree comparison function. * Equivalent elements are excluded from the result. * \param tree The tree. * \param cmp Comparison function called with cmp_arg and the element in the tree. * \param cmp_arg Search key, which may have a different type from tree elements. * \return The last strictly less node, or 0 if none. */ tommy_inline tommy_tree_node* tommy_tree_find_less_compare(tommy_tree* tree, tommy_compare_func* cmp, const void* cmp_arg) { tommy_tree_node* node = tree->root; tommy_tree_node* candidate = 0; while (node) { /* comparators must not change the tree, so retain the data across the call */ void* data = node->data; int c = cmp(cmp_arg, data); if (c > 0) { candidate = node; node = node->next; } else { node = node->prev; } } return candidate; } /** * Finds the last node in tree order with key strictly less than the specified one. * If no such element exists, 0 is returned. * \param tree The tree. * \param data Element used for comparison. * \return The last strictly less node, or 0 if none. */ tommy_inline tommy_tree_node* tommy_tree_find_less(tommy_tree* tree, const void* data) { return tommy_tree_find_less_compare(tree, tree->cmp, data); } /** * Searches the last element in tree order with key strictly less than the specified one using a specific comparison function. * The function must define a suborder of the tree comparison function. * Equivalent elements are excluded from the result. * \param tree The tree. * \param cmp Comparison function called with cmp_arg and the element in the tree. * \param cmp_arg Search key, which may have a different type from tree elements. * \return The last strictly less element, or 0 if none. */ tommy_inline void* tommy_tree_search_less_compare(tommy_tree* tree, tommy_compare_func* cmp, const void* cmp_arg) { tommy_tree_node* node = tommy_tree_find_less_compare(tree, cmp, cmp_arg); return node ? node->data : 0; } /** * Searches the last element in tree order with key strictly less than the specified one. * If no such element exists, 0 is returned. * \param tree The tree. * \param data Element used for comparison. * \return The last strictly less element, or 0 if none. */ tommy_inline void* tommy_tree_search_less(tommy_tree* tree, const void* data) { tommy_tree_node* node = tommy_tree_find_less(tree, data); return node ? node->data : 0; } /** * Searches and removes an element from the tree with a specific comparison function. * The comparison function must define a suborder of the original one. * The cmp_arg argument is passed as the first argument of the comparison * function and may have a different type than the elements in the tree. * \param tree The tree. * \param cmp Comparison function called with cmp_arg and the element in the tree. * \param cmp_arg Search key, which may have a different type from tree elements. * \return The first equal element in tree order, or 0 if not found. */ tommy_inline void* tommy_tree_remove_compare(tommy_tree* tree, tommy_compare_func* cmp, const void* cmp_arg) { tommy_tree_node* candidate = tommy_tree_find_compare(tree, cmp, cmp_arg); if (!candidate) return 0; return tommy_tree_remove_existing(tree, candidate); } /** * Searches and removes an element from the tree. * If the element is not found, 0 is returned. * \param tree The tree. * \param data Element used for comparison. * \return The first equal element in tree order, or 0 if not found. */ tommy_inline void* tommy_tree_remove(tommy_tree* tree, const void* data) { return tommy_tree_remove_compare(tree, tree->cmp, data); } /** * Calls the specified function for each element in the tree. * * The elements are processed in order. * * You cannot add or remove elements from the inside of the callback, * but can use it to deallocate them. * * \code * tommy_tree tree; * * // initializes the tree * tommy_tree_init(&tree, cmp); * * ... * * // creates an element * struct element* elem = malloc(sizeof(struct element)); * * ... * * // insert it in the tree * tommy_tree_insert(&tree, &elem->node, elem); * * ... * * // deallocates all the elements iterating the tree * tommy_tree_foreach(&tree, free); * tommy_tree_clear(&tree); // resets the tree before reuse * \endcode * * If the callback frees the elements, the tree retains dangling node * pointers. Call tommy_tree_clear() or tommy_tree_init() before reusing it. * The tree has no storage to release. * \param tree The tree. * \param func Function to call with each element. */ TOMMY_API void tommy_tree_foreach(tommy_tree* tree, tommy_foreach_func* func); /** * Calls the specified function with an argument for each element in the tree. * The iteration order and callback rules are the same as tommy_tree_foreach(). * The callback may deallocate the current element. * Adding or removing elements from inside the callback is not allowed. * \param tree The tree. * \param func Function to call with each element. * \param arg Argument to pass to the function. */ TOMMY_API void tommy_tree_foreach_arg(tommy_tree* tree, tommy_foreach_arg_func* func, void* arg); /** * Checks whether the tree is empty. * \param tree The tree. * \return Nonzero if the tree is empty, 0 otherwise. * \note This operation is O(1). */ tommy_inline tommy_bool_t tommy_tree_empty(const tommy_tree* tree) { return tree->root == 0; } /** * Gets the number of elements. * \param tree The tree. * \return The number of elements in the tree. * \note This operation is O(1). */ tommy_inline tommy_size_t tommy_tree_count(const tommy_tree* tree) { return tree->count; } /** * Gets the size of allocated memory. * It includes the size of the ::tommy_tree_node of the stored elements. * \param tree The tree. * \return Total memory allocated by the tree, in bytes. */ TOMMY_API tommy_size_t tommy_tree_memory_usage(const tommy_tree* tree); #endif