mirror of
https://github.com/amadvance/snapraid.git
synced 2026-10-26 02:49:02 -04:00
574 lines
15 KiB
C
574 lines
15 KiB
C
// 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.
|
|
*
|
|
* As a difference from other tommy containers, duplicate elements cannot be inserted.
|
|
*
|
|
* 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 object.
|
|
* The address of the object is used to initialize the tommy_node::data field
|
|
* of the node.
|
|
*
|
|
* \code
|
|
* struct object {
|
|
* int value;
|
|
* // other fields
|
|
* tommy_tree_node node;
|
|
* };
|
|
*
|
|
* struct object* obj = malloc(sizeof(struct object)); // creates the object
|
|
*
|
|
* obj->value = ...; // initializes the object
|
|
*
|
|
* tommy_tree_insert(&tree, &obj->node, obj); // inserts the object
|
|
* \endcode
|
|
*
|
|
* To find an element in the tree you have to call tommy_tree_search() providing
|
|
* the key to search.
|
|
*
|
|
* \code
|
|
* struct object value_to_find = { 1 };
|
|
* struct object* obj = tommy_tree_search(&tree, &value_to_find);
|
|
* if (!obj) {
|
|
* // 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 object* obj = i->data; // gets the object pointer
|
|
*
|
|
* printf("%d\n", obj->value); // process the object
|
|
*
|
|
* i = tommy_tree_next(i); // go to the next element
|
|
* }
|
|
* \endcode
|
|
*
|
|
* To remove an element from the tree you have to call tommy_tree_remove()
|
|
* providing the key to search and remove.
|
|
*
|
|
* \code
|
|
* struct object value_to_remove = { 1 };
|
|
* struct object* obj = tommy_tree_remove(&tree, &value_to_remove);
|
|
* if (obj) {
|
|
* free(obj); // frees the object 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 object* obj = ...;
|
|
* tommy_tree_remove_existing(&tree, &obj->node);
|
|
* free(obj);
|
|
* \endcode
|
|
*
|
|
* To remove the smallest or greatest element you can use tommy_tree_remove_head()
|
|
* or tommy_tree_remove_tail().
|
|
*
|
|
* \code
|
|
* struct object* obj = tommy_tree_remove_head(&tree);
|
|
* if (obj) {
|
|
* free(obj);
|
|
* }
|
|
* \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 objects iterating the tree
|
|
* tommy_tree_foreach(&tree, free);
|
|
* \endcode
|
|
*/
|
|
|
|
#ifndef __TOMMYTREE_H
|
|
#define __TOMMYTREE_H
|
|
|
|
#include "tommytypes.h"
|
|
|
|
/******************************************************************************/
|
|
/* tree */
|
|
|
|
/**
|
|
* Tree node.
|
|
* This is the node that you have to include inside your objects.
|
|
* 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 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;
|
|
}
|
|
|
|
/**
|
|
* Inserts an element in the tree.
|
|
* If the element is already present, it's not inserted again.
|
|
* Check the return value to identify if the element was already present or not.
|
|
* You have to provide the pointer of the node embedded into the object and
|
|
* the pointer to the object.
|
|
* \param node Pointer to the node embedded into the object to insert.
|
|
* \param data Pointer to the object to insert.
|
|
* \return The element in the tree. Either the already existing one, or the one just inserted.
|
|
*/
|
|
TOMMY_API void* tommy_tree_insert(tommy_tree* tree, tommy_tree_node* node, void* data);
|
|
|
|
/**
|
|
* Removes an element from the tree.
|
|
* You must already have the address of the element to remove.
|
|
* \return The tommy_node::data field of the node removed.
|
|
*/
|
|
TOMMY_API void* tommy_tree_remove_existing(tommy_tree* tree, tommy_tree_node* node);
|
|
|
|
|
|
/** \internal
|
|
* Calls the specified function for each element in the tree.
|
|
* \param root Root node of the tree.
|
|
* \param func Function to call.
|
|
*/
|
|
TOMMY_API void tommy_tree_foreach_node(tommy_tree_node* root, tommy_foreach_func* func);
|
|
|
|
/** \internal
|
|
* Calls the specified function with an argument for each element in the tree.
|
|
* \param root Root node of the tree.
|
|
* \param func Function to call.
|
|
* \param arg Custom argument for the function.
|
|
*/
|
|
TOMMY_API void tommy_tree_foreach_arg_node(tommy_tree_node* root, tommy_foreach_arg_func* func, void* arg);
|
|
|
|
/**
|
|
* 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.
|
|
* \param node Node contained in the tree.
|
|
* \return The following node. For the tail node 0 is returned.
|
|
*/
|
|
tommy_inline tommy_tree_node* tommy_tree_next(tommy_tree_node* node)
|
|
{
|
|
tommy_tree_node* parent;
|
|
|
|
if (node->next) {
|
|
node = node->next;
|
|
while (node->prev)
|
|
node = node->prev;
|
|
return 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.
|
|
* \param node Node contained in the tree.
|
|
* \return The preceding node. For the head node 0 is returned.
|
|
*/
|
|
tommy_inline tommy_tree_node* tommy_tree_prev(tommy_tree_node* node)
|
|
{
|
|
tommy_tree_node* parent;
|
|
|
|
if (node->prev) {
|
|
node = node->prev;
|
|
while (node->next)
|
|
node = node->next;
|
|
return node;
|
|
}
|
|
|
|
parent = tommy_tree_parent(node);
|
|
while (parent && node == parent->prev) {
|
|
node = parent;
|
|
parent = tommy_tree_parent(parent);
|
|
}
|
|
|
|
return parent;
|
|
}
|
|
|
|
/**
|
|
* Gets the head (smallest) element in the tree.
|
|
* \return The head node. For empty trees 0 is returned.
|
|
*/
|
|
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) element in the tree.
|
|
* \return The tail node. For empty trees 0 is returned.
|
|
*/
|
|
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.
|
|
* \return The removed element, or 0 if 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.
|
|
* \return The removed element, or 0 if 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);
|
|
}
|
|
|
|
/** \internal
|
|
* Searches a node in the tree.
|
|
* If the element is not found, 0 is returned.
|
|
* \param cmp Comparison function.
|
|
* \param node Node to start the search from.
|
|
* \param data Element used for comparison.
|
|
* \return The first node found, or 0 if none.
|
|
*/
|
|
tommy_inline tommy_tree_node* tommy_tree_search_node(tommy_compare_func* cmp, tommy_tree_node* node, void* data)
|
|
{
|
|
while (node) {
|
|
int c = cmp(data, node->data);
|
|
|
|
if (c < 0)
|
|
node = node->prev;
|
|
else if (c > 0)
|
|
node = node->next;
|
|
else
|
|
return node;
|
|
}
|
|
|
|
return 0;
|
|
}
|
|
|
|
/**
|
|
* Searches an element in the tree.
|
|
* If the element is not found, 0 is returned.
|
|
* \param data Element used for comparison.
|
|
* \return The first element found, or 0 if none.
|
|
*/
|
|
tommy_inline void* tommy_tree_search(tommy_tree* tree, void* data)
|
|
{
|
|
tommy_tree_node* node = tommy_tree_search_node(tree->cmp, tree->root, data);
|
|
|
|
if (!node)
|
|
return 0;
|
|
|
|
return node->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 ::data argument will be the first argument of the comparison function,
|
|
* and it can be of a different type than the objects in the tree.
|
|
*/
|
|
tommy_inline void* tommy_tree_search_compare(tommy_tree* tree, tommy_compare_func* cmp, void* cmp_arg)
|
|
{
|
|
tommy_tree_node* node = tommy_tree_search_node(cmp, tree->root, cmp_arg);
|
|
|
|
if (!node)
|
|
return 0;
|
|
|
|
return node->data;
|
|
}
|
|
|
|
/** \internal
|
|
* Searches a node in the tree with key greater or equal than the specified one.
|
|
* If no such element exists, 0 is returned.
|
|
* \param cmp Comparison function.
|
|
* \param node Node to start the search from.
|
|
* \param data Element used for comparison.
|
|
* \return The first node found, or 0 if none.
|
|
*/
|
|
tommy_inline tommy_tree_node* tommy_tree_search_greater_equal_node(tommy_compare_func* cmp, tommy_tree_node* node, void* data)
|
|
{
|
|
tommy_tree_node* candidate = 0;
|
|
|
|
while (node) {
|
|
int c = cmp(data, node->data);
|
|
|
|
if (c < 0) {
|
|
candidate = node;
|
|
node = node->prev;
|
|
} else if (c > 0) {
|
|
node = node->next;
|
|
} else {
|
|
return node;
|
|
}
|
|
}
|
|
|
|
return candidate;
|
|
}
|
|
|
|
/**
|
|
* Searches an element in the tree with key greater or equal than the specified one.
|
|
* If no such element exists, 0 is returned.
|
|
* \param data Element used for comparison.
|
|
* \return The first element found, or 0 if none.
|
|
*/
|
|
tommy_inline void* tommy_tree_search_greater_equal(tommy_tree* tree, void* data)
|
|
{
|
|
tommy_tree_node* node = tommy_tree_search_greater_equal_node(tree->cmp, tree->root, data);
|
|
|
|
if (!node)
|
|
return 0;
|
|
|
|
return node->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 ::data argument will be the first argument of the comparison function,
|
|
* and it can be of a different type than the objects in the tree.
|
|
*/
|
|
tommy_inline void* tommy_tree_search_greater_equal_compare(tommy_tree* tree, tommy_compare_func* cmp, void* cmp_arg)
|
|
{
|
|
tommy_tree_node* node = tommy_tree_search_greater_equal_node(cmp, tree->root, cmp_arg);
|
|
|
|
if (!node)
|
|
return 0;
|
|
|
|
return node->data;
|
|
}
|
|
|
|
/** \internal
|
|
* Searches a node in the tree with key less or equal than the specified one.
|
|
* If no such element exists, 0 is returned.
|
|
* \param cmp Comparison function.
|
|
* \param node Node to start the search from.
|
|
* \param data Element used for comparison.
|
|
* \return The first node found, or 0 if none.
|
|
*/
|
|
tommy_inline tommy_tree_node* tommy_tree_search_less_equal_node(tommy_compare_func* cmp, tommy_tree_node* node, void* data)
|
|
{
|
|
tommy_tree_node* candidate = 0;
|
|
|
|
while (node) {
|
|
int c = cmp(data, node->data);
|
|
|
|
if (c < 0) {
|
|
node = node->prev;
|
|
} else if (c > 0) {
|
|
candidate = node;
|
|
node = node->next;
|
|
} else {
|
|
return node;
|
|
}
|
|
}
|
|
|
|
return candidate;
|
|
}
|
|
|
|
/**
|
|
* Searches an element in the tree with key less or equal than the specified one.
|
|
* If no such element exists, 0 is returned.
|
|
* \param data Element used for comparison.
|
|
* \return The first element found, or 0 if none.
|
|
*/
|
|
tommy_inline void* tommy_tree_search_less_equal(tommy_tree* tree, void* data)
|
|
{
|
|
tommy_tree_node* node = tommy_tree_search_less_equal_node(tree->cmp, tree->root, data);
|
|
|
|
if (!node)
|
|
return 0;
|
|
|
|
return node->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 ::data argument will be the first argument of the comparison function,
|
|
* and it can be of a different type than the objects in the tree.
|
|
*/
|
|
tommy_inline void* tommy_tree_search_less_equal_compare(tommy_tree* tree, tommy_compare_func* cmp, void* cmp_arg)
|
|
{
|
|
tommy_tree_node* node = tommy_tree_search_less_equal_node(cmp, tree->root, cmp_arg);
|
|
|
|
if (!node)
|
|
return 0;
|
|
|
|
return node->data;
|
|
}
|
|
|
|
/**
|
|
* Searches and removes an element.
|
|
* If the element is not found, 0 is returned.
|
|
* \param data Element used for comparison.
|
|
* \return The removed element, or 0 if not found.
|
|
*/
|
|
tommy_inline void* tommy_tree_remove(tommy_tree* tree, void* data)
|
|
{
|
|
tommy_tree_node* node = tommy_tree_search_node(tree->cmp, tree->root, data);
|
|
|
|
if (!node)
|
|
return 0;
|
|
|
|
return tommy_tree_remove_existing(tree, node);
|
|
}
|
|
|
|
/**
|
|
* 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 object
|
|
* struct object* obj = malloc(sizeof(struct object));
|
|
*
|
|
* ...
|
|
*
|
|
* // insert it in the tree
|
|
* tommy_tree_insert(&tree, &obj->node, obj);
|
|
*
|
|
* ...
|
|
*
|
|
* // deallocates all the objects iterating the tree
|
|
* tommy_tree_foreach(&tree, free);
|
|
* \endcode
|
|
*/
|
|
tommy_inline void tommy_tree_foreach(tommy_tree* tree, tommy_foreach_func* func)
|
|
{
|
|
tommy_tree_foreach_node(tree->root, func);
|
|
}
|
|
|
|
/**
|
|
* Calls the specified function with an argument for each element in the tree.
|
|
*/
|
|
tommy_inline void tommy_tree_foreach_arg(tommy_tree* tree, tommy_foreach_arg_func* func, void* arg)
|
|
{
|
|
tommy_tree_foreach_arg_node(tree->root, func, arg);
|
|
}
|
|
|
|
/**
|
|
* Checks if empty.
|
|
* \return If the tree is empty.
|
|
*/
|
|
tommy_inline tommy_bool_t tommy_tree_empty(tommy_tree* tree)
|
|
{
|
|
return tree->root == 0;
|
|
}
|
|
|
|
/**
|
|
* Gets the number of elements.
|
|
*/
|
|
tommy_inline tommy_size_t tommy_tree_count(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.
|
|
*/
|
|
TOMMY_API tommy_size_t tommy_tree_memory_usage(tommy_tree* tree);
|
|
|
|
#endif
|
|
|