ucx/tree.c

/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright 2024 Mike Becker, Olaf Wintermann All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 *   1. Redistributions of source code must retain the above copyright
 *      notice, this list of conditions and the following disclaimer.
 *
 *   2. Redistributions in binary form must reproduce the above copyright
 *      notice, this list of conditions and the following disclaimer in the
 *      documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */

#include "cx/tree.h"

#include <assert.h>
#include <string.h>

#define CX_TREE_PTR(cur, off) (*(void**)(((char*)(cur))+(off)))
#define tree_parent(node) CX_TREE_PTR(node, loc_parent)
#define tree_children(node) CX_TREE_PTR(node, loc_children)
#define tree_last_child(node) CX_TREE_PTR(node, loc_last_child)
#define tree_prev(node) CX_TREE_PTR(node, loc_prev)
#define tree_next(node) CX_TREE_PTR(node, loc_next)

#define tree_layout(tree) \
    (tree)->loc_parent,\
    (tree)->loc_children,\
    (tree)->loc_last_child,\
    (tree)->loc_prev,  \
    (tree)->loc_next

void cx_tree_add(
        void *parent,
        void *node,
        ptrdiff_t loc_parent,
        ptrdiff_t loc_children,
        ptrdiff_t loc_last_child,
        ptrdiff_t loc_prev,
        ptrdiff_t loc_next
) {
    assert(loc_parent >= 0);
    assert(loc_children >= 0);
    assert(loc_next >= 0);

    void *current_parent = tree_parent(node);
    if (current_parent == parent) return;
    if (current_parent != NULL) {
        cx_tree_remove(node, loc_parent, loc_children,
            loc_last_child, loc_prev, loc_next);
    }

    if (tree_children(parent) == NULL) {
        tree_children(parent) = node;
        if (loc_last_child >= 0) {
            tree_last_child(parent) = node;
        }
    } else {
        void *child;
        if (loc_last_child >= 0) {
            child = tree_last_child(parent);
            tree_last_child(parent) = node;
        } else {
            child = tree_children(parent);
            void *next;
            while ((next = tree_next(child)) != NULL) {
                child = next;
            }
        }
        if (loc_prev >= 0) {
            tree_prev(node) = child;
        }
        tree_next(child) = node;
    }
    tree_parent(node) = parent;
}

static void *cx_tree_node_prev(
        ptrdiff_t loc_parent,
        ptrdiff_t loc_children,
        ptrdiff_t loc_next,
        const void *node
) {
    void *parent = tree_parent(node);
    void *begin = tree_children(parent);
    if (begin == node) return NULL;
    const void *cur = begin;
    const void *next;
    while (1) {
        next = tree_next(cur);
        if (next == node) return (void *) cur;
        cur = next;
    }
}

void cx_tree_remove(
        void *node,
        ptrdiff_t loc_parent,
        ptrdiff_t loc_children,
        ptrdiff_t loc_last_child,
        ptrdiff_t loc_prev,
        ptrdiff_t loc_next
) {
    if (tree_parent(node) == NULL) return;

    assert(loc_children >= 0);
    assert(loc_next >= 0);
    assert(loc_parent >= 0);
    void *left;
    if (loc_prev >= 0) {
        left = tree_prev(node);
    } else {
        left = cx_tree_node_prev(loc_parent, loc_children, loc_next, node);
    }
    void *right = tree_next(node);
    void *parent = tree_parent(node);
    assert(left == NULL || tree_children(parent) != node);
    assert(right == NULL || loc_last_child < 0 ||
           tree_last_child(parent) != node);

    if (left == NULL) {
        tree_children(parent) = right;
    } else {
        tree_next(left) = right;
    }
    if (right == NULL) {
        if (loc_last_child >= 0) {
            tree_last_child(parent) = left;
        }
    } else {
        if (loc_prev >= 0) {
            tree_prev(right) = left;
        }
    }

    tree_parent(node) = NULL;
    tree_next(node) = NULL;
    if (loc_prev >= 0) {
        tree_prev(node) = NULL;
    }
}

int cx_tree_search(const void *root, size_t max_depth,
        const void *data, cx_tree_search_func sfunc, void **result,
        ptrdiff_t loc_children, ptrdiff_t loc_next) {
    // help avoiding bugs due to uninitialized memory
    assert(result != NULL);
    *result = NULL;

    // NULL root? exit!
    if (root == NULL) {
        return -1;
    }

    // remember return value for best match
    int ret = sfunc(root, data);
    if (ret < 0) {
        // not contained, exit
        return -1;
    }
    *result = (void*) root;
    // if root is already exact match, exit
    if (ret == 0) {
        return 0;
    }

    // when depth is one, we are already done
    if (max_depth == 1) {
        return ret;
    }

    // special case: indefinite depth
    if (max_depth == 0) {
        max_depth = SIZE_MAX;
    }

    // create an iterator
    CxTreeIterator iter = cx_tree_iterator(
            (void*) root, false, loc_children, loc_next
    );

    // skip root, we already handled it
    cxIteratorNext(iter);

    // loop through the remaining tree
    cx_foreach(void *, elem, iter) {
        // investigate the current node
        int ret_elem = sfunc(elem, data);
        if (ret_elem == 0) {
            // if found, exit the search
            *result = elem;
            ret = 0;
            break;
        } else if (ret_elem > 0 && ret_elem < ret) {
            // new distance is better
            *result = elem;
            ret = ret_elem;
        } else if (ret_elem < 0 || ret_elem > ret) {
            // not contained or distance is worse, skip entire subtree
            cxTreeIteratorContinue(iter);
        }

        // when we reached the max depth, skip the subtree
        if (iter.depth == max_depth) {
            cxTreeIteratorContinue(iter);
        }
    }

    // dispose of the iterator as we might have exited the loop early
    cxTreeIteratorDispose(&iter);

    assert(ret < 0 || *result != NULL);
    return ret;
}

static bool cx_tree_iter_valid(const void *it) {
    const CxTreeIterator *iter = it;
    return iter->node != NULL;
}

static void *cx_tree_iter_current(const void *it) {
    const CxTreeIterator *iter = it;
    return iter->node;
}

static void cx_tree_iter_next(void *it) {
    CxTreeIterator *iter = it;
    ptrdiff_t const loc_next = iter->loc_next;
    ptrdiff_t const loc_children = iter->loc_children;
    // protect us from misuse
    if (!iter->base.valid(iter)) return;

    void *children;

    // check if we are currently exiting or entering nodes
    if (iter->exiting) {
        children = NULL;
        // skipping on exit is pointless, just clear the flag
        iter->skip = false;
    } else {
        if (iter->skip) {
            // skip flag is set, pretend that there are no children
            iter->skip = false;
            children = NULL;
        } else {
            // try to enter the children (if any)
            children = tree_children(iter->node);
        }
    }

    if (children == NULL) {
        // search for the next node
        void *next = NULL;
        cx_tree_iter_search_next:
        // check if there is a sibling, but only if we are not a (subtree-)root
        if (iter->exiting) {
            next = iter->node_next;
        } else if (iter->depth > 1) {
            next = tree_next(iter->node);
            iter->node_next = next;
        }
        if (next == NULL) {
            // no sibling, we are done with this node and exit
            if (iter->visit_on_exit && !iter->exiting) {
                // iter is supposed to visit the node again
                iter->exiting = true;
            } else {
                iter->exiting = false;
                if (iter->depth == 1) {
                    // there is no parent - we have iterated the entire tree
                    // invalidate the iterator and free the node stack
                    iter->node = iter->node_next = NULL;
                    iter->stack_capacity = iter->depth = 0;
                    cxFreeDefault(iter->stack);
                    iter->stack = NULL;
                } else {
                    // the parent node can be obtained from the top of stack
                    // this way we can avoid the loc_parent in the iterator
                    iter->depth--;
                    iter->node = iter->stack[iter->depth - 1];
                    // retry with the parent node to find a sibling
                    goto cx_tree_iter_search_next;
                }
            }
        } else {
            if (iter->visit_on_exit && !iter->exiting) {
                // iter is supposed to visit the node again
                iter->exiting = true;
            } else {
                iter->exiting = false;
                // move to the sibling
                iter->counter++;
                iter->node = next;
                // new top of stack is the sibling
                iter->stack[iter->depth - 1] = next;
            }
        }
    } else {
        // node has children, push the first child onto the stack and enter it
        if (iter->depth >= iter->stack_capacity) {
            const size_t newcap = iter->stack_capacity + 8;
            if (cxReallocateArrayDefault(&iter->stack, newcap, sizeof(void*))) {
                // we cannot return an error in this function
                abort(); // LCOV_EXCL_LINE
            }
            iter->stack_capacity = newcap;
        }
        iter->stack[iter->depth] = children;
        iter->depth++;
        iter->node = children;
        iter->counter++;
    }
}

CxTreeIterator cx_tree_iterator(
        void *root,
        bool visit_on_exit,
        ptrdiff_t loc_children,
        ptrdiff_t loc_next
) {
    CxTreeIterator ret;
    ret.use_dfs = true;
    ret.loc_children = loc_children;
    ret.loc_next = loc_next;
    ret.visit_on_exit = visit_on_exit;

    // initialize members
    ret.node_next = NULL;
    ret.exiting = false;
    ret.skip = false;

    // assign base iterator functions
    ret.base.allow_remove = false;
    ret.base.remove = false;
    ret.base.current_impl = NULL;
    ret.base.valid = cx_tree_iter_valid;
    ret.base.next = cx_tree_iter_next;
    ret.base.current = cx_tree_iter_current;

    // visit the root node
    ret.node = root;
    if (root != NULL) {
        ret.stack_capacity = 16;
        ret.stack = cxMallocDefault(sizeof(void *) * 16);
        ret.stack[0] = root;
        ret.counter = 1;
        ret.depth = 1;
    } else {
        ret.stack_capacity = 0;
        ret.stack = NULL;
        ret.counter = 0;
        ret.depth = 0;
    }

    return ret;
}

static bool cx_tree_visitor_valid(const void *it) {
    const CxTreeIterator *iter = it;
    return iter->node != NULL;
}

static void *cx_tree_visitor_current(const void *it) {
    const CxTreeIterator *iter = it;
    return iter->node;
}

CX_NONNULL
static void cx_tree_visitor_enqueue_siblings(
        CxTreeIterator *iter, void *node, ptrdiff_t loc_next) {
    node = tree_next(node);
    while (node != NULL) {
        struct cx_tree_visitor_queue_s *q;
        q = cxMallocDefault(sizeof(struct cx_tree_visitor_queue_s));
        q->depth = iter->queue_last->depth;
        q->node = node;
        iter->queue_last->next = q;
        iter->queue_last = q;
        node = tree_next(node);
    }
    iter->queue_last->next = NULL;
}

static void cx_tree_visitor_next(void *it) {
    CxTreeIterator *iter = it;
    // protect us from misuse
    if (!iter->base.valid(iter)) return;

    ptrdiff_t const loc_next = iter->loc_next;
    ptrdiff_t const loc_children = iter->loc_children;

    // add the children of the current node to the queue
    // unless the skip flag is set
    void *children;
    if (iter->skip) {
        iter->skip = false;
        children = NULL;
    } else {
        children = tree_children(iter->node);
    }
    if (children != NULL) {
        struct cx_tree_visitor_queue_s *q;
        q = cxMallocDefault(sizeof(struct cx_tree_visitor_queue_s));
        q->depth = iter->depth + 1;
        q->node = children;
        if (iter->queue_last == NULL) {
            assert(iter->queue_next == NULL);
            iter->queue_next = q;
        } else {
            iter->queue_last->next = q;
        }
        iter->queue_last = q;
        cx_tree_visitor_enqueue_siblings(iter, children, loc_next);
    }

    // check if there is a next node
    if (iter->queue_next == NULL) {
        iter->node = NULL;
        return;
    }

    // dequeue the next node
    iter->node = iter->queue_next->node;
    iter->depth = iter->queue_next->depth;
    {
        struct cx_tree_visitor_queue_s *q = iter->queue_next;
        iter->queue_next = q->next;
        if (iter->queue_next == NULL) {
            assert(iter->queue_last == q);
            iter->queue_last = NULL;
        }
        cxFreeDefault(q);
    }

    // increment the node counter
    iter->counter++;
}

CxTreeIterator cx_tree_visitor(
        void *root,
        ptrdiff_t loc_children,
        ptrdiff_t loc_next
) {
    CxTreeIterator ret;
    ret.visit_on_exit = false;
    ret.exiting = false;
    ret.use_dfs = false;
    ret.loc_children = loc_children;
    ret.loc_next = loc_next;

    // initialize members
    ret.skip = false;
    ret.queue_next = NULL;
    ret.queue_last = NULL;

    // assign base iterator functions
    ret.base.allow_remove = false;
    ret.base.remove = false;
    ret.base.current_impl = NULL;
    ret.base.valid = cx_tree_visitor_valid;
    ret.base.next = cx_tree_visitor_next;
    ret.base.current = cx_tree_visitor_current;

    // visit the root node
    ret.node = root;
    if (root != NULL) {
        ret.counter = 1;
        ret.depth = 1;
    } else {
        ret.counter = 0;
        ret.depth = 0;
    }

    return ret;
}

size_t cx_tree_size(void *root, ptrdiff_t loc_children, ptrdiff_t loc_next) {
    CxTreeIterator iter = cx_tree_iterator(root, false, loc_children, loc_next);
    while (cxIteratorValid(iter)) {
        cxIteratorNext(iter);
    }
    return iter.counter;
}

size_t cx_tree_depth(void *root, ptrdiff_t loc_children, ptrdiff_t loc_next) {
    CxTreeIterator iter = cx_tree_iterator(root, false, loc_children, loc_next);
    size_t depth = 0;
    while (cxIteratorValid(iter)) {
        if (iter.depth > depth) {
            depth = iter.depth;
        }
        cxIteratorNext(iter);
    }
    return depth;
}

CxTree *cxTreeCreate(const CxAllocator *allocator,
        size_t node_size, size_t elem_size, void *root, ptrdiff_t loc_data,
        ptrdiff_t loc_parent, ptrdiff_t loc_children, ptrdiff_t loc_last_child,
        ptrdiff_t loc_prev, ptrdiff_t loc_next) {

    if (allocator == NULL) {
        allocator = cxDefaultAllocator;
    }

    CxTree *tree = cxZalloc(allocator, sizeof(CxTree));
    if (tree == NULL) return NULL;  // LCOV_EXCL_LINE
    tree->collection.allocator = allocator;

    if (elem_size == CX_STORE_POINTERS) {
        tree->collection.store_pointer = true;
        tree->collection.elem_size = sizeof(void*);
    } else {
        tree->collection.elem_size = elem_size;
    }

    tree->root = root;
    tree->node_size = node_size;
    tree->loc_parent = loc_parent;
    tree->loc_children = loc_children;
    tree->loc_last_child = loc_last_child;
    tree->loc_prev = loc_prev;
    tree->loc_next = loc_next;
    tree->loc_data = loc_data;

    if (root == NULL) {
        cxSetAdvancedDestructor(tree, cxFree, (void*)allocator);
    } else {
        tree->collection.size = cx_tree_size(root, loc_children, loc_next);
    }

    return tree;
}

void cxTreeFree(CxTree *tree) {
    if (tree == NULL) return;
    if (tree->root != NULL) {
        cxTreeClear(tree);
    }
    cxFree(tree->collection.allocator, tree);
}

void cxTreeSetParent(CxTree *tree, void *parent, void *child) {
    size_t loc_parent = tree->loc_parent;
    if (tree_parent(child) == NULL) {
        tree->collection.size++;
    }
    cx_tree_add(parent, child, tree_layout(tree));
}

void cxTreeAddNode(CxTree *tree, void *parent, void *child) {
    cx_tree_add(parent, child, tree_layout(tree));
    tree->collection.size++;
}

void *cxTreeCreateNode(CxTree *tree, void *parent) {
    void *node = cxZalloc(tree->collection.allocator, tree->node_size);
    if (node == NULL) return NULL; // LCOV_EXCL_LINE
    cx_tree_add(parent, node, tree_layout(tree));
    tree->collection.size++;
    return node;
}

void *cxTreeAddData(CxTree *tree, void *parent, const void *data) {
    if (tree->loc_data < 0) return NULL;

    void *node = cxTreeCreateNode(tree, parent);
    if (node == NULL) return NULL; // LCOV_EXCL_LINE

    char *dst = node;
    dst += tree->loc_data;
    const void *src = cxCollectionStoresPointers(tree) ? (const void*)&data : data;
    memcpy(dst, src, tree->collection.elem_size);

    return node;
}

void *cxTreeCreateRoot(CxTree *tree) {
    if (tree->root != NULL) {
        return tree->root;
    }

    void *node = cxZalloc(tree->collection.allocator, tree->node_size);
    if (node == NULL) return NULL; // LCOV_EXCL_LINE
    tree->root = node;
    tree->collection.size = 1;
    return node;
}

void *cxTreeCreateRootData(CxTree *tree, const void *data) {
    if (tree->loc_data < 0) return NULL;

    void *node = cxTreeCreateRoot(tree);
    if (node == NULL) return NULL; // LCOV_EXCL_LINE

    char *dst = node;
    dst += tree->loc_data;
    const void *src = cxCollectionStoresPointers(tree) ? (const void*)&data : data;
    memcpy(dst, src, tree->collection.elem_size);

    return node;
}

void *cxTreeSetRoot(CxTree *tree, void *new_root) {
    void *old_root = tree->root;
    tree->root = new_root;
    return old_root;
}

void *cxTreeFindInSubtree(CxTree *tree, const void *data,
        void *subtree_root, size_t max_depth, bool use_dfs) {
    if (tree->loc_data < 0 || subtree_root == NULL) {
        return NULL;
    }

    CxTreeIterator iter = use_dfs
        ? cx_tree_iterator(subtree_root, false, tree->loc_children, tree->loc_next)
        : cx_tree_visitor(subtree_root, tree->loc_children, tree->loc_next);

    cx_foreach(char*, node, iter) {
        char *node_data = node + tree->loc_data;
        if (cxCollectionStoresPointers(tree)) {
            node_data = *(void**)node_data;
        }
        if (cx_invoke_compare_func(tree, node_data, data) == 0) {
            cxTreeIteratorDispose(&iter);
            return node;
        }
        if (iter.depth == max_depth) {
            cxTreeIteratorContinue(iter);
        }
    }
    return NULL;
}

void *cxTreeFindFastInSubtree(CxTree *tree, const void *data,
        cx_tree_search_func sfunc, void *root, size_t max_depth) {
    void *result;
    int ret = cx_tree_search(root, max_depth, data, sfunc, &result,
        tree->loc_children, tree->loc_next);
    if (ret == 0) {
        return result;
    } else {
        return NULL;
    }
}

size_t cxTreeSubtreeSize(CxTree *tree, void *subtree_root) {
    if (subtree_root == tree->root) {
        return tree->collection.size;
    }
    return cx_tree_size(subtree_root, tree->loc_children, tree->loc_next);
}

size_t cxTreeSubtreeDepth(CxTree *tree, void *subtree_root) {
    return cx_tree_depth(subtree_root, tree->loc_children, tree->loc_next);
}

size_t cxTreeSize(CxTree *tree) {
    return tree->collection.size;
}

size_t cxTreeDepth(CxTree *tree) {
    return cx_tree_depth(tree->root, tree->loc_children, tree->loc_next);
}

int cxTreeRemoveNode(
        CxTree *tree,
        void *node,
        cx_tree_relink_func relink_func
) {
    if (node == tree->root) return 1;

    // determine the new parent
    ptrdiff_t loc_parent = tree->loc_parent;
    void *new_parent = tree_parent(node);

    // first, unlink from the parent
    cx_tree_remove(node, tree_layout(tree));

    // then relink each child
    ptrdiff_t loc_children = tree->loc_children;
    ptrdiff_t loc_next = tree->loc_next;
    void *child = tree_children(node);
    while (child != NULL) {
        // forcibly set the parent to NULL - we do not use the unlink function
        // because that would unnecessarily modify the children linked list
        tree_parent(child) = NULL;

        // update contents, if required
        if (relink_func != NULL) {
            relink_func(child, node, new_parent);
        }

        // link to new parent
        cx_tree_add(new_parent, child, tree_layout(tree));

        // proceed to next child
        child = tree_next(child);
    }

    // clear the linked list of the removed node
    tree_children(node) = NULL;
    ptrdiff_t loc_last_child = tree->loc_last_child;
    if (loc_last_child >= 0) tree_last_child(node) = NULL;

    // the tree now has one member less
    tree->collection.size--;

    return 0;
}

void cxTreeRemoveSubtree(CxTree *tree, void *node) {
    if (node == tree->root) {
        tree->root = NULL;
        tree->collection.size = 0;
        return;
    }
    size_t subtree_size = cxTreeSubtreeSize(tree, node);
    cx_tree_remove(node, tree_layout(tree));
    tree->collection.size -= subtree_size;
}

int cxTreeDestroyNode(
        CxTree *tree,
        void *node,
        cx_tree_relink_func relink_func
) {
    int result = cxTreeRemoveNode(tree, node, relink_func);
    if (result == 0) {
        cx_invoke_destructor_raw(tree, node);
        return 0;
    } else {
        return result;
    }
}

void cxTreeDestroySubtree(CxTree *tree, void *node) {
    cx_tree_remove(node, tree_layout(tree));
    CxTreeIterator iter = cx_tree_iterator(
            node, true,
            tree->loc_children, tree->loc_next
    );
    cx_foreach(void *, child, iter) {
        if (iter.exiting) {
            // always call the destructors with the node!
            cx_invoke_destructor_raw(tree, child);
        }
    }
    tree->collection.size -= iter.counter;
    if (node == tree->root) {
        tree->root = NULL;
    }
}

void cxTreeIteratorDispose(CxTreeIterator *iter) {
    if (iter->use_dfs) {
        cxFreeDefault(iter->stack);
        iter->stack = NULL;
    } else {
        struct cx_tree_visitor_queue_s *q = iter->queue_next;
        while (q != NULL) {
            struct cx_tree_visitor_queue_s *next = q->next;
            cxFreeDefault(q);
            q = next;
        }
        iter->queue_next = iter->queue_last = NULL;
    }
}

CxTreeIterator cxTreeIterateSubtree(CxTree *tree, void *node, bool visit_on_exit) {
    return cx_tree_iterator(
            node, visit_on_exit,
            tree->loc_children, tree->loc_next
    );
}

CxTreeIterator cxTreeVisitSubtree(CxTree *tree, void *node) {
    return cx_tree_visitor(
            node, tree->loc_children, tree->loc_next
    );
}

CxTreeIterator cxTreeIterate(CxTree *tree, bool visit_on_exit) {
    return cxTreeIterateSubtree(tree, tree->root, visit_on_exit);
}

CxTreeIterator cxTreeVisit(CxTree *tree) {
    return cxTreeVisitSubtree(tree, tree->root);
}