ntnode.h File Reference

ECU: inc/ecu/ntnode.h File Reference

ECU

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "ecu/dlist.h"
#include "ecu/object_id.h"
#include "ecu/utils.h"

Include dependency graph for ntnode.h:

Go to the source code of this file.

Data Structures
struct	ecu_ntnode
	Single node within a tree. Intrusive, so user-defined types contain this node as a member. This type represents both a root and regular tree node. At any point in time, every node will either be a root of a subtree (normal tree node) or the main root. More...

struct	ecu_ntnode_child_iterator
	Non-const child iterator. More...

struct	ecu_ntnode_child_citerator
	Const child iterator. More...

struct	ecu_ntnode_parent_iterator
	Non-const parent iterator. More...

struct	ecu_ntnode_parent_citerator
	Const parent iterator. More...

struct	ecu_ntnode_next_sibling_iterator
	Non-const next sibling iterator. More...

struct	ecu_ntnode_next_sibling_citerator
	Const next sibling iterator. More...

struct	ecu_ntnode_postorder_iterator
	Non-const postorder iterator. More...

struct	ecu_ntnode_postorder_citerator
	Const postorder iterator. More...

struct	ecu_ntnode_preorder_iterator
	Non-const preorder iterator. More...

struct	ecu_ntnode_preorder_citerator
	Const preorder iterator. More...

struct	ecu_ntnode_prev_sibling_iterator
	Non-const previous sibling iterator. More...

struct	ecu_ntnode_prev_sibling_citerator
	Const previous sibling iterator. More...

struct	ecu_ntnode_sibling_iterator
	Non-const sibling iterator. More...

struct	ecu_ntnode_sibling_citerator
	Const sibling iterator. More...

Macros
#define	ECU_NTNODE_OBJ_UNUSED ((void *)0)
	Convenience macro passed to API if optional callback objects are unused.

#define	ECU_NTNODE_DESTROY_UNUSED ((void ()(struct ecu_ntnode , ecu_object_id_t))0)
	Convenience macro passed to ecu_ntnode_ctor() if a user-defined node destructor is not needed.

#define	ECU_NTNODE_GET_ENTRY(ptr_, type_, member_) ECU_CONTAINER_OF(ptr_, type_, member_)
	Retrieves user data from an intrusive ecu_ntnode by converting the supplied ecu_ntnode back into the user's node type. More...

#define	ECU_NTNODE_GET_CONST_ENTRY(ptr_, type_, member_) ECU_CONST_CONTAINER_OF(ptr_, type_, member_)
	Const-qualified version of ECU_NTNODE_GET_ENTRY(). Retrieves user data from an intrusive ecu_ntnode by converting the supplied ecu_ntnode back into the user's node type. More...

#define	ECU_NTNODE_CHILD_FOR_EACH(var_, iter_, parent_)
	Iterates (for-loops) over all direct children. Grandchildren, great-grandchildren, etc are not included in the iteration. It is safe to remove or destroy the current node in the iteration. More...

#define	ECU_NTNODE_CONST_CHILD_FOR_EACH(var_, citer_, parent_)
	Const-qualified version of ECU_NTNODE_CHILD_FOR_EACH(). Iterates (for-loops) over all direct children. Grandchildren, great-grandchildren, etc are not included in the iteration. Returned nodes are read-only. More...

#define	ECU_NTNODE_NEXT_SIBLING_AT_FOR_EACH(var_, iter_, start_)
	Iterates (for-loops) over all next (right) siblings, including the supplied starting node. Terminates after the last (rightmost) sibling is reached. It is safe to remove or destroy the current node in the iteration. More...

#define	ECU_NTNODE_CONST_NEXT_SIBLING_AT_FOR_EACH(var_, citer_, start_)
	Const-qualified version of ECU_NTNODE_NEXT_SIBLING_AT_FOR_EACH(). Iterates (for-loops) over all next (right) siblings, including the supplied starting node. Terminates after the last (rightmost) sibling is reached. Returned nodes are read-only. More...

#define	ECU_NTNODE_NEXT_SIBLING_FOR_EACH(var_, iter_, start_)
	Same as ECU_NTNODE_NEXT_SIBLING_AT_FOR_EACH() but excludes the starting node from the iteration. More...

#define	ECU_NTNODE_CONST_NEXT_SIBLING_FOR_EACH(var_, citer_, start_)
	Same as ECU_NTNODE_CONST_NEXT_SIBLING_AT_FOR_EACH() but excludes the starting node from the iteration. More...

#define	ECU_NTNODE_PARENT_AT_FOR_EACH(var_, iter_, start_)
	Iterates (for-loops) over all parents, including the supplied starting node, by traversing up the tree. It is safe to remove or destroy the current node in the iteration. More...

#define	ECU_NTNODE_CONST_PARENT_AT_FOR_EACH(var_, citer_, start_)
	Const-qualified version of ECU_NTNODE_PARENT_AT_FOR_EACH(). Iterates (for-loops) over all parents, including the supplied starting node, by traversing up the tree. Returned nodes are read-only. More...

#define	ECU_NTNODE_PARENT_FOR_EACH(var_, iter_, start_)
	Same as ECU_NTNODE_PARENT_AT_FOR_EACH() but excludes the starting node from the iteration. More...

#define	ECU_NTNODE_CONST_PARENT_FOR_EACH(var_, citer_, start_)
	Same as ECU_NTNODE_CONST_PARENT_AT_FOR_EACH() but excludes the starting node from the iteration. More...

#define	ECU_NTNODE_POSTORDER_FOR_EACH(var_, iter_, root_)
	Performs a postorder iteration (for-loop) over a tree. The root node is included in the iteration. It is safe to remove or destroy the current node in the iteration. More...

#define	ECU_NTNODE_CONST_POSTORDER_FOR_EACH(var_, citer_, root_)
	Const-qualified version of ECU_NTNODE_POSTORDER_FOR_EACH(). Performs a postorder iteration (for-loop) over a tree. The root node is included in the iteration. Returned nodes are read-only. More...

#define	ECU_NTNODE_PREORDER_FOR_EACH(var_, iter_, root_)
	Performs a preorder iteration (for-loop) over a tree. The root node is included in the iteration. Removing or destroying the current node in the iteration is NOT allowed since this is an unsafe operation during preorder traversal. More...

#define	ECU_NTNODE_CONST_PREORDER_FOR_EACH(var_, citer_, root_)
	Const-qualified version of ECU_NTNODE_PREORDER_FOR_EACH(). Performs a preorder iteration (for-loop) over a tree. The root node is included in the iteration. Returned nodes are read-only. More...

#define	ECU_NTNODE_PREV_SIBLING_AT_FOR_EACH(var_, iter_, start_)
	Iterates (for-loops) over all previous (left) siblings, including the supplied starting node. Terminates after the first (leftmost) sibling is reached. It is safe to remove or destroy the current node in the iteration. More...

#define	ECU_NTNODE_CONST_PREV_SIBLING_AT_FOR_EACH(var_, citer_, start_)
	Const-qualified version of ECU_NTNODE_PREV_SIBLING_AT_FOR_EACH(). Iterates (for-loops) over all previous (left) siblings, including the supplied starting node. Terminates after the first (leftmost) sibling is reached. Returned nodes are read-only. More...

#define	ECU_NTNODE_PREV_SIBLING_FOR_EACH(var_, iter_, start_)
	Same as ECU_NTNODE_PREV_SIBLING_AT_FOR_EACH() but excludes the starting node from the iteration. More...

#define	ECU_NTNODE_CONST_PREV_SIBLING_FOR_EACH(var_, citer_, start_)
	Same as ECU_NTNODE_CONST_PREV_SIBLING_AT_FOR_EACH() but excludes the starting node from the iteration. More...

#define	ECU_NTNODE_SIBLING_FOR_EACH(var_, iter_, start_)
	Iterates (for-loops) over all siblings, excluding the starting node. Performs wraparound if starting sibling is not the first sibling. It is safe to remove or destroy the current node in the iteration. More...

#define	ECU_NTNODE_CONST_SIBLING_FOR_EACH(var_, citer_, start_)
	Const-qualified version of ECU_NTNODE_SIBLING_FOR_EACH(). Iterates (for-loops) over all siblings, excluding the starting node. Performs wraparound if starting sibling is not the first sibling. More...

Functions
Constructors
void	ecu_ntnode_ctor (struct ecu_ntnode me, void(destroy)(struct ecu_ntnode *me, ecu_object_id_t id), ecu_object_id_t id)
	Node constructor. More...

void	ecu_ntnode_destroy (struct ecu_ntnode *me)
	Node destructor. Destroys the supplied node and all of its descendants (children, grandchildren, etc). All destroyed nodes must be reconstructed in order to be used again. More...

Member Functions
void	ecu_ntnode_clear (struct ecu_ntnode *me)
	Removes the supplied node and all of its descendants from a tree. All nodes can be reused and added to another tree without reconstruction. More...

size_t	ecu_ntnode_count (const struct ecu_ntnode *me)
	Returns the number of direct children the supplied node has. Grandchildren, great-granchildren, etc are not counted. Returns 0 if the node has no children. More...

struct ecu_ntnode *	ecu_ntnode_first_child (struct ecu_ntnode *me)
	Returns the node's first (leftmost) child. NULL is returned if the node has no children. More...

const struct ecu_ntnode *	ecu_ntnode_first_cchild (const struct ecu_ntnode *me)
	Const-qualified version of ecu_ntnode_first_child(). Returns the node's first (leftmost) child. NULL is returned if the node has no children. More...

ecu_object_id_t	ecu_ntnode_id (const struct ecu_ntnode *me)
	Returns the node's ID assigned when it was constructed in ecu_ntnode_ctor(). More...

bool	ecu_ntnode_in_tree (const struct ecu_ntnode *me)
	Returns true if the node is in a tree. False otherwise. Note that this returns true for a root node that has children. More...

void	ecu_ntnode_insert_sibling_after (struct ecu_ntnode pos, struct ecu_ntnode sibling)
	Inserts a sibling node into the tree after the specified position. `sibling` becomes `pos's` next sibling. More...

void	ecu_ntnode_insert_sibling_before (struct ecu_ntnode pos, struct ecu_ntnode sibling)
	Inserts a sibling node into the tree before the specified position. `sibling` becomes `pos's` previous sibling. More...

bool	ecu_ntnode_is_descendant (const struct ecu_ntnode *me)
	Returns true if the node is in a tree and is not the root. False otherwise. More...

bool	ecu_ntnode_is_leaf (const struct ecu_ntnode *me)
	Returns true if the node is a leaf, meaning it has no children. False otherwise. Note that this returns true for an empty node since that is technically a leaf. More...

bool	ecu_ntnode_is_root (const struct ecu_ntnode *me)
	Returns true if the node is a root, meaning it has no parent. False otherwise. Note that this returns true for an empty node since that is technically a root. More...

struct ecu_ntnode *	ecu_ntnode_last_child (struct ecu_ntnode *me)
	Returns the node's last (rightmost) child. NULL is returned if the node has no children. More...

const struct ecu_ntnode *	ecu_ntnode_last_cchild (const struct ecu_ntnode *me)
	Const-qualified version of ecu_ntnode_last_child(). Returns the node's last (rightmost) child. NULL is returned if the node has no children. More...

struct ecu_ntnode *	ecu_ntnode_lca (struct ecu_ntnode n1, struct ecu_ntnode n2)
	Returns the least common ancestor of `n1` and `n2`. Returns NULL if nodes are in separate trees and do not have an LCA. More...

const struct ecu_ntnode *	ecu_ntnode_clca (const struct ecu_ntnode n1, const struct ecu_ntnode n2)
	Const-qualified version of ecu_ntnode_lca(). Returns the least common ancestor of `n1` and `n2`. Returns NULL if nodes are in separate trees and do not have an LCA. More...

size_t	ecu_ntnode_level (const struct ecu_ntnode *me)
	Returns which level of the tree the supplied node is in. Returns 0 if the supplied node is a root. More...

struct ecu_ntnode *	ecu_ntnode_next (struct ecu_ntnode *me)
	Returns the node's next (right) sibling. NULL is returned if the node is the last (rightmost) sibling or has no siblings. More...

const struct ecu_ntnode *	ecu_ntnode_cnext (const struct ecu_ntnode *me)
	Const-qualified version of ecu_ntnode_next(). Returns the node's next (right) sibling. NULL is returned if the node is the last (rightmost) sibling or has no siblings. More...

struct ecu_ntnode *	ecu_ntnode_parent (struct ecu_ntnode *me)
	Returns the supplied node's parent. NULL is returned if the node is a root. More...

const struct ecu_ntnode *	ecu_ntnode_cparent (const struct ecu_ntnode *me)
	Const-qualified version of ecu_ntnode_parent(). Returns the supplied node's parent. NULL is returned if the node is a root. More...

struct ecu_ntnode *	ecu_ntnode_prev (struct ecu_ntnode *me)
	Returns the node's previous (left) sibling. NULL is returned if the node is the first (leftmost) sibling or has no siblings. More...

const struct ecu_ntnode *	ecu_ntnode_cprev (const struct ecu_ntnode *me)
	Const-qualified version of ecu_ntnode_prev(). Returns the node's previous (left) sibling. NULL is returned if the node is the first (leftmost) sibling or has no siblings. More...

void	ecu_ntnode_push_child_back (struct ecu_ntnode parent, struct ecu_ntnode child)
	Inserts a rightmost child node into the tree. `child` becomes `parent's` last (rightmost) child. More...

void	ecu_ntnode_push_child_front (struct ecu_ntnode parent, struct ecu_ntnode child)
	Inserts a leftmost child node into the tree. `child` becomes `parent's` first (leftmost) child. More...

void	ecu_ntnode_remove (struct ecu_ntnode *me)
	Removes node from a tree. If the removed node has descendants, the node becomes a new root with its tree intact. The tree remains unchanged if an empty or root node is supplied. More...

size_t	ecu_ntnode_size (const struct ecu_ntnode *me)
	Returns the total number of descendants (children, grandchildren, etc) the node has. Returns 0 if the node has no descendants. More...

bool	ecu_ntnode_valid (const struct ecu_ntnode *me)
	Returns true if supplied node has been constructed via ecu_ntnode_ctor() and can be used. False otherwise. More...

Child Iterator
struct ecu_ntnode *	ecu_ntnode_child_iterator_begin (struct ecu_ntnode_child_iterator me, struct ecu_ntnode parent)
	Starts an iteration over the supplied node's direct children. Grandchildren, great-grandchildren, etc are not iterated over. If the starting node has children its first (leftmost) child is returned. Otherwise NULL is returned, signifying the end of the iteration. More...

struct ecu_ntnode *	ecu_ntnode_child_iterator_end (struct ecu_ntnode_child_iterator *me)
	Returns the ending node in the iteration, which is NULL. More...

struct ecu_ntnode *	ecu_ntnode_child_iterator_next (struct ecu_ntnode_child_iterator *me)
	Returns the next child in the iteration. More...

const struct ecu_ntnode *	ecu_ntnode_child_iterator_cbegin (struct ecu_ntnode_child_citerator me, const struct ecu_ntnode parent)
	Const-qualified version of ecu_ntnode_child_iterator_begin(). Starts an iteration over the supplied node's direct children. Grandchildren, great-grandchildren, etc are not iterated over. If the starting node has children its first (leftmost) child is returned. Otherwise NULL is returned, signifying the end of the iteration. More...

const struct ecu_ntnode *	ecu_ntnode_child_iterator_cend (struct ecu_ntnode_child_citerator *me)
	Const-qualified version of ecu_ntnode_child_iterator_end(). Returns the ending node in the iteration, which is NULL. More...

const struct ecu_ntnode *	ecu_ntnode_child_iterator_cnext (struct ecu_ntnode_child_citerator *me)
	Const-qualified version of ecu_ntnode_child_iterator_next(). Returns the next child in the iteration. More...

Next Sibling Iterator
struct ecu_ntnode *	ecu_ntnode_next_sibling_iterator_at (struct ecu_ntnode_next_sibling_iterator me, struct ecu_ntnode start)
	Starts an iteration over all next (right) siblings, including the supplied starting node. The supplied starting node is returned. More...

struct ecu_ntnode *	ecu_ntnode_next_sibling_iterator_begin (struct ecu_ntnode_next_sibling_iterator me, struct ecu_ntnode start)
	Starts an iteration over all next (right) siblings, excluding the supplied starting node. If the starting node has siblings the next (right) sibling to it is returned. Otherwise NULL is returned, signifying the end of the iteration. More...

struct ecu_ntnode *	ecu_ntnode_next_sibling_iterator_end (struct ecu_ntnode_next_sibling_iterator *me)
	Returns the ending node in the iteration, which is NULL. More...

struct ecu_ntnode *	ecu_ntnode_next_sibling_iterator_next (struct ecu_ntnode_next_sibling_iterator *me)
	Returns the next node in the iteration. More...

const struct ecu_ntnode *	ecu_ntnode_next_sibling_iterator_cat (struct ecu_ntnode_next_sibling_citerator me, const struct ecu_ntnode start)
	Const-qualified version of ecu_ntnode_next_sibling_iterator_at(). Starts an iteration over all next (right) siblings, including the supplied starting node. The supplied starting node is returned. More...

const struct ecu_ntnode *	ecu_ntnode_next_sibling_iterator_cbegin (struct ecu_ntnode_next_sibling_citerator me, const struct ecu_ntnode start)
	Const-qualified version of ecu_ntnode_next_sibling_iterator_begin(). Starts an iteration over all next (right) siblings, excluding the supplied starting node. If the starting node has siblings the next (right) sibling to it is returned. Otherwise NULL is returned, signifying the end of the iteration. More...

const struct ecu_ntnode *	ecu_ntnode_next_sibling_iterator_cend (struct ecu_ntnode_next_sibling_citerator *me)
	Const-qualified version of ecu_ntnode_next_sibling_iterator_end(). Returns the ending node in the iteration, which is NULL. More...

const struct ecu_ntnode *	ecu_ntnode_next_sibling_iterator_cnext (struct ecu_ntnode_next_sibling_citerator *me)
	Const-qualified version of ecu_ntnode_next_sibling_iterator_next(). Returns the next node in the iteration. More...

Parent Iterator
struct ecu_ntnode *	ecu_ntnode_parent_iterator_at (struct ecu_ntnode_parent_iterator me, struct ecu_ntnode start)
	Starts an iteration over all parents, including the supplied starting node. The supplied starting node is returned. More...

struct ecu_ntnode *	ecu_ntnode_parent_iterator_begin (struct ecu_ntnode_parent_iterator me, struct ecu_ntnode start)
	Starts an iteration over all parents, excluding the supplied starting node. If the starting node has parents, its parent is returned. Otherwise NULL is returned, signifying the end of the iteration. More...

struct ecu_ntnode *	ecu_ntnode_parent_iterator_end (struct ecu_ntnode_parent_iterator *me)
	Returns the ending node in the iteration, which is NULL. More...

struct ecu_ntnode *	ecu_ntnode_parent_iterator_next (struct ecu_ntnode_parent_iterator *me)
	Returns the next parent in the iteration. More...

const struct ecu_ntnode *	ecu_ntnode_parent_iterator_cat (struct ecu_ntnode_parent_citerator me, const struct ecu_ntnode start)
	Const-qualified version of ecu_ntnode_parent_iterator_at(). Starts an iteration over all parents, including the supplied starting node. The supplied starting node is returned. More...

const struct ecu_ntnode *	ecu_ntnode_parent_iterator_cbegin (struct ecu_ntnode_parent_citerator me, const struct ecu_ntnode start)
	Const-qualified version of ecu_ntnode_parent_iterator_begin(). Starts an iteration over all parents, excluding the supplied starting node. If the starting node has parents, its parent is returned. Otherwise NULL is returned, signifying the end of the iteration. More...

const struct ecu_ntnode *	ecu_ntnode_parent_iterator_cend (struct ecu_ntnode_parent_citerator *me)
	Const-qualified version of ecu_ntnode_parent_iterator_end(). Returns the ending node in the iteration, which is NULL. More...

const struct ecu_ntnode *	ecu_ntnode_parent_iterator_cnext (struct ecu_ntnode_parent_citerator *me)
	Const-qualified version of ecu_ntnode_parent_iterator_next(). Returns the next parent in the iteration. More...

Postorder Iterator
struct ecu_ntnode *	ecu_ntnode_postorder_iterator_begin (struct ecu_ntnode_postorder_iterator me, struct ecu_ntnode root)
	Starts a postorder iteration over the supplied node's tree. Returns the first node in the iteration. More...

struct ecu_ntnode *	ecu_ntnode_postorder_iterator_end (struct ecu_ntnode_postorder_iterator *me)
	Returns the ending node in the iteration, which is a dummy delimiter. More...

struct ecu_ntnode *	ecu_ntnode_postorder_iterator_next (struct ecu_ntnode_postorder_iterator *me)
	Returns the next node in the iteration. More...

const struct ecu_ntnode *	ecu_ntnode_postorder_iterator_cbegin (struct ecu_ntnode_postorder_citerator me, const struct ecu_ntnode root)
	Const-qualified version of ecu_ntnode_postorder_iterator_begin(). Starts a postorder iteration over the supplied node's tree. Returns the first node in the iteration. More...

const struct ecu_ntnode *	ecu_ntnode_postorder_iterator_cend (struct ecu_ntnode_postorder_citerator *me)
	Const-qualified version of ecu_ntnode_postorder_iterator_end(). Returns the ending node in the iteration, which is a dummy delimiter. More...

const struct ecu_ntnode *	ecu_ntnode_postorder_iterator_cnext (struct ecu_ntnode_postorder_citerator *me)
	Const-qualified version of ecu_ntnode_postorder_iterator_next(). Returns the next node in the iteration. More...

Preorder Iterator
struct ecu_ntnode *	ecu_ntnode_preorder_iterator_begin (struct ecu_ntnode_preorder_iterator me, struct ecu_ntnode root)
	Starts a preorder iteration over the supplied node's tree. The supplied `root` is returned, which is the first node in the iteration. More...

struct ecu_ntnode *	ecu_ntnode_preorder_iterator_end (struct ecu_ntnode_preorder_iterator *me)
	Returns the ending node in the iteration, which is a dummy delimiter. More...

struct ecu_ntnode *	ecu_ntnode_preorder_iterator_next (struct ecu_ntnode_preorder_iterator *me)
	Returns the next node in the iteration. More...

const struct ecu_ntnode *	ecu_ntnode_preorder_iterator_cbegin (struct ecu_ntnode_preorder_citerator me, const struct ecu_ntnode root)
	Const-qualified version of ecu_ntnode_preorder_iterator_begin(). Starts a preorder iteration over the supplied node's tree. The supplied `root` is returned, which is the first node in the iteration. More...

const struct ecu_ntnode *	ecu_ntnode_preorder_iterator_cend (struct ecu_ntnode_preorder_citerator *me)
	Const-qualified version of ecu_ntnode_preorder_iterator_end(). Returns the ending node in the iteration, which is a dummy delimiter. More...

const struct ecu_ntnode *	ecu_ntnode_preorder_iterator_cnext (struct ecu_ntnode_preorder_citerator *me)
	Const-qualified version of ecu_ntnode_preorder_iterator_next(). Returns the next node in the iteration. More...

Previous Sibling Iterator
struct ecu_ntnode *	ecu_ntnode_prev_sibling_iterator_at (struct ecu_ntnode_prev_sibling_iterator me, struct ecu_ntnode start)
	Starts an iteration over all previous (left) siblings, including the supplied starting node. The supplied starting node is returned. More...

struct ecu_ntnode *	ecu_ntnode_prev_sibling_iterator_begin (struct ecu_ntnode_prev_sibling_iterator me, struct ecu_ntnode start)
	Starts an iteration over all previous (left) siblings, excluding the supplied starting node. If the starting node has siblings the previous (left) sibling to it is returned. Otherwise NULL is returned, signifying the end of the iteration. More...

struct ecu_ntnode *	ecu_ntnode_prev_sibling_iterator_end (struct ecu_ntnode_prev_sibling_iterator *me)
	Returns the ending node in the iteration, which is NULL. More...

struct ecu_ntnode *	ecu_ntnode_prev_sibling_iterator_next (struct ecu_ntnode_prev_sibling_iterator *me)
	Returns the next node in the iteration. More...

const struct ecu_ntnode *	ecu_ntnode_prev_sibling_iterator_cat (struct ecu_ntnode_prev_sibling_citerator me, const struct ecu_ntnode start)
	Const-qualified version of ecu_ntnode_prev_sibling_iterator_at(). Starts an iteration over all previous (left) siblings, including the supplied starting node. The supplied starting node is returned. More...

const struct ecu_ntnode *	ecu_ntnode_prev_sibling_iterator_cbegin (struct ecu_ntnode_prev_sibling_citerator me, const struct ecu_ntnode start)
	Const-qualified version of ecu_ntnode_prev_sibling_iterator_begin(). Starts an iteration over all previous (left) siblings, excluding the supplied starting node. If the starting node has siblings the previous (left) sibling to it is returned. Otherwise NULL is returned, signifying the end of the iteration. More...

const struct ecu_ntnode *	ecu_ntnode_prev_sibling_iterator_cend (struct ecu_ntnode_prev_sibling_citerator *me)
	Const-qualified version of ecu_ntnode_prev_sibling_iterator_end(). Returns the ending node in the iteration, which is NULL. More...

const struct ecu_ntnode *	ecu_ntnode_prev_sibling_iterator_cnext (struct ecu_ntnode_prev_sibling_citerator *me)
	Const-qualified version of ecu_ntnode_prev_sibling_iterator_next(). Returns the next node in the iteration. More...

Sibling Iterator
struct ecu_ntnode *	ecu_ntnode_sibling_iterator_begin (struct ecu_ntnode_sibling_iterator me, struct ecu_ntnode start)
	Starts an iteration over all siblings, excluding the supplied starting node. More...

struct ecu_ntnode *	ecu_ntnode_sibling_iterator_end (struct ecu_ntnode_sibling_iterator *me)
	Returns the ending node in the iteration. More...

struct ecu_ntnode *	ecu_ntnode_sibling_iterator_next (struct ecu_ntnode_sibling_iterator *me)
	Returns the next sibling in the iteration. More...

const struct ecu_ntnode *	ecu_ntnode_sibling_iterator_cbegin (struct ecu_ntnode_sibling_citerator me, const struct ecu_ntnode start)
	Const-qualified version of ecu_ntnode_sibling_iterator_begin(). Starts an iteration over all siblings, excluding the supplied starting node. More...

const struct ecu_ntnode *	ecu_ntnode_sibling_iterator_cend (struct ecu_ntnode_sibling_citerator *me)
	Const-qualified version of ecu_ntnode_sibling_iterator_end(). Returns the ending node in the iteration. More...

const struct ecu_ntnode *	ecu_ntnode_sibling_iterator_cnext (struct ecu_ntnode_sibling_citerator *me)
	Const-qualified version of ecu_ntnode_sibling_iterator_next(). Returns the next sibling in the iteration. More...

Detailed Description

See ntnode.h section in Sphinx documentation.

Author: Ian Ress

Version: 0.1

Date: 2025-05-15

Copyright: Copyright (c) 2025

Macro Definition Documentation

◆ ECU_NTNODE_CHILD_FOR_EACH

#define ECU_NTNODE_CHILD_FOR_EACH	(	var_,
		iter_,
		parent_
	)

Value:

    for (struct ecu_ntnode *var_ = ecu_ntnode_child_iterator_begin(iter_, parent_); \
         var_ != ecu_ntnode_child_iterator_end(iter_);                              \
         var_ = ecu_ntnode_child_iterator_next(iter_))

Iterates (for-loops) over all direct children. Grandchildren, great-grandchildren, etc are not included in the iteration. It is safe to remove or destroy the current node in the iteration.

Parameters

var_	Loop variable name. This variable will store the current node in the iteration and will be a pointer to ecu_ntnode.
iter_	Iterator to initialize. This will be a pointer to ecu_ntnode_child_iterator.
parent_	The children of this node will be iterated over. This will be a pointer to ecu_ntnode.

◆ ECU_NTNODE_CONST_CHILD_FOR_EACH

#define ECU_NTNODE_CONST_CHILD_FOR_EACH	(	var_,
		citer_,
		parent_
	)

Value:

    for (const struct ecu_ntnode *var_ = ecu_ntnode_child_iterator_cbegin(citer_, parent_); \
         var_ != ecu_ntnode_child_iterator_cend(citer_);                                    \
         var_ = ecu_ntnode_child_iterator_cnext(citer_))

Const-qualified version of ECU_NTNODE_CHILD_FOR_EACH(). Iterates (for-loops) over all direct children. Grandchildren, great-grandchildren, etc are not included in the iteration. Returned nodes are read-only.

Parameters

var_	Loop variable name. This variable will store the current node in the iteration and will be a pointer to const ecu_ntnode.
citer_	Iterator to initialize. This will be a pointer to ecu_ntnode_child_citerator.
parent_	The children of this node will be iterated over. This will be a pointer to ecu_ntnode.

◆ ECU_NTNODE_CONST_NEXT_SIBLING_AT_FOR_EACH

#define ECU_NTNODE_CONST_NEXT_SIBLING_AT_FOR_EACH	(	var_,
		citer_,
		start_
	)

Value:

    for (const struct ecu_ntnode *var_ = ecu_ntnode_next_sibling_iterator_cat(citer_, start_); \
         var_ != ecu_ntnode_next_sibling_iterator_cend(citer_);                                \
         var_ = ecu_ntnode_next_sibling_iterator_cnext(citer_))

Const-qualified version of ECU_NTNODE_NEXT_SIBLING_AT_FOR_EACH(). Iterates (for-loops) over all next (right) siblings, including the supplied starting node. Terminates after the last (rightmost) sibling is reached. Returned nodes are read-only.

Parameters

var_	Loop variable name. This variable will store the current node in the iteration and will be a pointer to const ecu_ntnode.
citer_	Iterator to initialize. This will be a pointer to ecu_ntnode_next_sibling_citerator.
start_	Starting node of the iteration. This node IS included in the iteration and is returned first. This will be a pointer to const ecu_ntnode.

◆ ECU_NTNODE_CONST_NEXT_SIBLING_FOR_EACH

#define ECU_NTNODE_CONST_NEXT_SIBLING_FOR_EACH	(	var_,
		citer_,
		start_
	)

Value:

    for (const struct ecu_ntnode *var_ = ecu_ntnode_next_sibling_iterator_cbegin(citer_, start_); \
         var_ != ecu_ntnode_next_sibling_iterator_cend(citer_);                                   \
         var_ = ecu_ntnode_next_sibling_iterator_cnext(citer_))

Same as ECU_NTNODE_CONST_NEXT_SIBLING_AT_FOR_EACH() but excludes the starting node from the iteration.

Parameters

var_	Loop variable name. This variable will store the current node in the iteration and will be a pointer to const ecu_ntnode.
citer_	Iterator to initialize. This will be a pointer to ecu_ntnode_next_sibling_citerator.
start_	Starting node of the iteration. This will be a pointer to const ecu_ntnode. This node is NOT included in the iteration. The node next to this one is returned first.

◆ ECU_NTNODE_CONST_PARENT_AT_FOR_EACH

#define ECU_NTNODE_CONST_PARENT_AT_FOR_EACH	(	var_,
		citer_,
		start_
	)

Value:

    for (const struct ecu_ntnode *var_ = ecu_ntnode_parent_iterator_cat(citer_, start_); \
         var_ != ecu_ntnode_parent_iterator_cend(citer_);                                \
         var_ = ecu_ntnode_parent_iterator_cnext(citer_))

Const-qualified version of ECU_NTNODE_PARENT_AT_FOR_EACH(). Iterates (for-loops) over all parents, including the supplied starting node, by traversing up the tree. Returned nodes are read-only.

Parameters

var_	Loop variable name. This variable will store the current node in the iteration and will be a pointer to const ecu_ntnode.
citer_	Iterator to initialize. This will be a pointer to ecu_ntnode_parent_citerator.
start_	Starting node of the iteration. This node IS included in the iteration and is returned first. This will be a pointer to const ecu_ntnode.

◆ ECU_NTNODE_CONST_PARENT_FOR_EACH

#define ECU_NTNODE_CONST_PARENT_FOR_EACH	(	var_,
		citer_,
		start_
	)

Value:

    for (const struct ecu_ntnode *var_ = ecu_ntnode_parent_iterator_cbegin(citer_, start_); \
         var_ != ecu_ntnode_parent_iterator_cend(citer_);                                   \
         var_ = ecu_ntnode_parent_iterator_cnext(citer_))

Same as ECU_NTNODE_CONST_PARENT_AT_FOR_EACH() but excludes the starting node from the iteration.

Parameters

var_	Loop variable name. This variable will store the current node in the iteration and will be a pointer to const ecu_ntnode.
citer_	Iterator to initialize. This will be a pointer to ecu_ntnode_parent_citerator.
start_	Starting node of the iteration. This node is NOT included in the iteration. This will be a pointer to const ecu_ntnode.

◆ ECU_NTNODE_CONST_POSTORDER_FOR_EACH

#define ECU_NTNODE_CONST_POSTORDER_FOR_EACH	(	var_,
		citer_,
		root_
	)

Value:

    for (const struct ecu_ntnode *var_ = ecu_ntnode_postorder_iterator_cbegin(citer_, root_); \
         var_ != ecu_ntnode_postorder_iterator_cend(citer_);                                  \
         var_ = ecu_ntnode_postorder_iterator_cnext(citer_))

Const-qualified version of ECU_NTNODE_POSTORDER_FOR_EACH(). Performs a postorder iteration (for-loop) over a tree. The root node is included in the iteration. Returned nodes are read-only.

Parameters

var_	Loop variable name. This variable will store the current node in the iteration and will be a pointer to const ecu_ntnode.
citer_	Iterator to initialize. This will be a pointer to ecu_ntnode_postorder_citerator.
root_	Tree to iterate over. By design, this will always be the root of a subtree or the main root. This node will be included in the iteration, and will be a pointer to const ecu_ntnode.

◆ ECU_NTNODE_CONST_PREORDER_FOR_EACH

#define ECU_NTNODE_CONST_PREORDER_FOR_EACH	(	var_,
		citer_,
		root_
	)

Value:

    for (const struct ecu_ntnode *var_ = ecu_ntnode_preorder_iterator_cbegin(citer_, root_); \
         var_ != ecu_ntnode_preorder_iterator_cend(citer_);                                  \
         var_ = ecu_ntnode_preorder_iterator_cnext(citer_))

Const-qualified version of ECU_NTNODE_PREORDER_FOR_EACH(). Performs a preorder iteration (for-loop) over a tree. The root node is included in the iteration. Returned nodes are read-only.

Parameters

var_	Loop variable name. This variable will store the current node in the iteration and will be a pointer to const ecu_ntnode.
citer_	Iterator to initialize. This will be a pointer to ecu_ntnode_preorder_citerator.
root_	Tree to iterate over. By design, this will always be the root of a subtree or the main root. This node will be included in the iteration, and will be a pointer to const ecu_ntnode.

◆ ECU_NTNODE_CONST_PREV_SIBLING_AT_FOR_EACH

#define ECU_NTNODE_CONST_PREV_SIBLING_AT_FOR_EACH	(	var_,
		citer_,
		start_
	)

Value:

    for (const struct ecu_ntnode *var_ = ecu_ntnode_prev_sibling_iterator_cat(citer_, start_); \
         var_ != ecu_ntnode_prev_sibling_iterator_cend(citer_);                                \
         var_ = ecu_ntnode_prev_sibling_iterator_cnext(citer_))

Const-qualified version of ECU_NTNODE_PREV_SIBLING_AT_FOR_EACH(). Iterates (for-loops) over all previous (left) siblings, including the supplied starting node. Terminates after the first (leftmost) sibling is reached. Returned nodes are read-only.

Parameters

var_	Loop variable name. This variable will store the current node in the iteration and will be a pointer to const ecu_ntnode.
citer_	Iterator to initialize. This will be a pointer to ecu_ntnode_prev_sibling_citerator.
start_	Starting node of the iteration. This node IS included in the iteration and is returned first. This will be a pointer to const ecu_ntnode.

◆ ECU_NTNODE_CONST_PREV_SIBLING_FOR_EACH

#define ECU_NTNODE_CONST_PREV_SIBLING_FOR_EACH	(	var_,
		citer_,
		start_
	)

Value:

    for (const struct ecu_ntnode *var_ = ecu_ntnode_prev_sibling_iterator_cbegin(citer_, start_); \
         var_ != ecu_ntnode_prev_sibling_iterator_cend(citer_);                                   \
         var_ = ecu_ntnode_prev_sibling_iterator_cnext(citer_))

Same as ECU_NTNODE_CONST_PREV_SIBLING_AT_FOR_EACH() but excludes the starting node from the iteration.

Parameters

var_	Loop variable name. This variable will store the current node in the iteration and will be a pointer to const ecu_ntnode.
citer_	Iterator to initialize. This will be a pointer to ecu_ntnode_prev_sibling_citerator.
start_	Starting node of the iteration. This will be a pointer to const ecu_ntnode. This node is NOT included in the iteration. The node previous to this one is returned first.

◆ ECU_NTNODE_CONST_SIBLING_FOR_EACH

#define ECU_NTNODE_CONST_SIBLING_FOR_EACH	(	var_,
		citer_,
		start_
	)

Value:

    for (const struct ecu_ntnode *var_ = ecu_ntnode_sibling_iterator_cbegin(citer_, start_); \
         var_ != ecu_ntnode_sibling_iterator_cend(citer_);                                   \
         var_ = ecu_ntnode_sibling_iterator_cnext(citer_))

Const-qualified version of ECU_NTNODE_SIBLING_FOR_EACH(). Iterates (for-loops) over all siblings, excluding the starting node. Performs wraparound if starting sibling is not the first sibling.

Note: If the starting node must be included in the iteration use a child iterator instead. SIBLING_AT() will not be supported since it is impossible to determine when to terminate the iteration.

Parameters

var_	Loop variable name. This variable will store the current node in the iteration and will be a pointer to const ecu_ntnode.
citer_	Iterator to initialize. This will be a pointer to ecu_ntnode_sibling_citerator.
start_	Starting node of the iteration. This node is NOT included in the iteration. This will be a pointer to const ecu_ntnode.

◆ ECU_NTNODE_GET_CONST_ENTRY

#define ECU_NTNODE_GET_CONST_ENTRY	(	ptr_,
		type_,
		member_
	)	ECU_CONST_CONTAINER_OF(ptr_, type_, member_)

Const-qualified version of ECU_NTNODE_GET_ENTRY(). Retrieves user data from an intrusive ecu_ntnode by converting the supplied ecu_ntnode back into the user's node type.

Parameters

ptr_	Pointer to intrusive ecu_ntnode. This can be pointer to const or non-const. I.e. (struct ecu_ntnode ) or (const struct ecu_ntnode ).
type_	User's node type containing the intrusive ecu_ntnode. Do not use const specifier. I.e. (struct my_type), never (const struct my_type).
member_	Name of ecu_ntnode member within user's type.

◆ ECU_NTNODE_GET_ENTRY

#define ECU_NTNODE_GET_ENTRY	(	ptr_,
		type_,
		member_
	)	ECU_CONTAINER_OF(ptr_, type_, member_)

Retrieves user data from an intrusive ecu_ntnode by converting the supplied ecu_ntnode back into the user's node type.

Parameters

ptr_	Pointer to intrusive ecu_ntnode. This must be pointer to non-const. I.e. (struct ecu_ntnode *).
type_	User's node type containing the intrusive ecu_ntnode. Do not use const specifier. I.e. (struct my_type), never (const struct my_type).
member_	Name of ecu_ntnode member within user's type.

◆ ECU_NTNODE_NEXT_SIBLING_AT_FOR_EACH

#define ECU_NTNODE_NEXT_SIBLING_AT_FOR_EACH	(	var_,
		iter_,
		start_
	)

Value:

    for (struct ecu_ntnode *var_ = ecu_ntnode_next_sibling_iterator_at(iter_, start_); \
         var_ != ecu_ntnode_next_sibling_iterator_end(iter_);                          \
         var_ = ecu_ntnode_next_sibling_iterator_next(iter_))

Iterates (for-loops) over all next (right) siblings, including the supplied starting node. Terminates after the last (rightmost) sibling is reached. It is safe to remove or destroy the current node in the iteration.

Parameters

var_	Loop variable name. This variable will store the current node in the iteration and will be a pointer to ecu_ntnode.
iter_	Iterator to initialize. This will be a pointer to ecu_ntnode_next_sibling_iterator.
start_	Starting node of the iteration. This node IS included in the iteration and is returned first. This will be a pointer to ecu_ntnode.

◆ ECU_NTNODE_NEXT_SIBLING_FOR_EACH

#define ECU_NTNODE_NEXT_SIBLING_FOR_EACH	(	var_,
		iter_,
		start_
	)

Value:

    for (struct ecu_ntnode *var_ = ecu_ntnode_next_sibling_iterator_begin(iter_, start_); \
         var_ != ecu_ntnode_next_sibling_iterator_end(iter_);                             \
         var_ = ecu_ntnode_next_sibling_iterator_next(iter_))

Same as ECU_NTNODE_NEXT_SIBLING_AT_FOR_EACH() but excludes the starting node from the iteration.

Parameters

var_	Loop variable name. This variable will store the current node in the iteration and will be a pointer to ecu_ntnode.
iter_	Iterator to initialize. This will be a pointer to ecu_ntnode_next_sibling_iterator.
start_	Starting node of the iteration. This will be a pointer to ecu_ntnode. This node is NOT included in the iteration. The node next to this one is returned first.

◆ ECU_NTNODE_PARENT_AT_FOR_EACH

#define ECU_NTNODE_PARENT_AT_FOR_EACH	(	var_,
		iter_,
		start_
	)

Value:

    for (struct ecu_ntnode *var_ = ecu_ntnode_parent_iterator_at(iter_, start_); \
         var_ != ecu_ntnode_parent_iterator_end(iter_);                          \
         var_ = ecu_ntnode_parent_iterator_next(iter_))

Iterates (for-loops) over all parents, including the supplied starting node, by traversing up the tree. It is safe to remove or destroy the current node in the iteration.

Parameters

var_	Loop variable name. This variable will store the current node in the iteration and will be a pointer to ecu_ntnode.
iter_	Iterator to initialize. This will be a pointer to ecu_ntnode_parent_iterator.
start_	Starting node of the iteration. This node IS included in the iteration and is returned first. This will be a pointer to ecu_ntnode.

◆ ECU_NTNODE_PARENT_FOR_EACH

#define ECU_NTNODE_PARENT_FOR_EACH	(	var_,
		iter_,
		start_
	)

Value:

    for (struct ecu_ntnode *var_ = ecu_ntnode_parent_iterator_begin(iter_, start_); \
         var_ != ecu_ntnode_parent_iterator_end(iter_);                             \
         var_ = ecu_ntnode_parent_iterator_next(iter_))

Same as ECU_NTNODE_PARENT_AT_FOR_EACH() but excludes the starting node from the iteration.

Parameters

var_	Loop variable name. This variable will store the current node in the iteration and will be a pointer to ecu_ntnode.
iter_	Iterator to initialize. This will be a pointer to ecu_ntnode_parent_iterator.
start_	Starting node of the iteration. This node is NOT included in the iteration. This will be a pointer to ecu_ntnode.

◆ ECU_NTNODE_POSTORDER_FOR_EACH

#define ECU_NTNODE_POSTORDER_FOR_EACH	(	var_,
		iter_,
		root_
	)

Value:

    for (struct ecu_ntnode *var_ = ecu_ntnode_postorder_iterator_begin(iter_, root_); \
         var_ != ecu_ntnode_postorder_iterator_end(iter_);                            \
         var_ = ecu_ntnode_postorder_iterator_next(iter_))

Performs a postorder iteration (for-loop) over a tree. The root node is included in the iteration. It is safe to remove or destroy the current node in the iteration.

Parameters

var_	Loop variable name. This variable will store the current node in the iteration and will be a pointer to ecu_ntnode.
iter_	Iterator to initialize. This will be a pointer to ecu_ntnode_postorder_iterator.
root_	Tree to iterate over. By design, this will always be the root of a subtree or the main root. This node will be included in the iteration, and will be a pointer to ecu_ntnode.

◆ ECU_NTNODE_PREORDER_FOR_EACH

#define ECU_NTNODE_PREORDER_FOR_EACH	(	var_,
		iter_,
		root_
	)

Value:

    for (struct ecu_ntnode *var_ = ecu_ntnode_preorder_iterator_begin(iter_, root_); \
         var_ != ecu_ntnode_preorder_iterator_end(iter_);                            \
         var_ = ecu_ntnode_preorder_iterator_next(iter_))

Performs a preorder iteration (for-loop) over a tree. The root node is included in the iteration. Removing or destroying the current node in the iteration is NOT allowed since this is an unsafe operation during preorder traversal.

Parameters

var_	Loop variable name. This variable will store the current node in the iteration and will be a pointer to ecu_ntnode.
iter_	Iterator to initialize. This will be a pointer to ecu_ntnode_preorder_iterator.
root_	Tree to iterate over. By design, this will always be the root of a subtree or the main root. This node will be included in the iteration, and will be a pointer to ecu_ntnode.

◆ ECU_NTNODE_PREV_SIBLING_AT_FOR_EACH

#define ECU_NTNODE_PREV_SIBLING_AT_FOR_EACH	(	var_,
		iter_,
		start_
	)

Value:

    for (struct ecu_ntnode *var_ = ecu_ntnode_prev_sibling_iterator_at(iter_, start_); \
         var_ != ecu_ntnode_prev_sibling_iterator_end(iter_);                          \
         var_ = ecu_ntnode_prev_sibling_iterator_next(iter_))

Iterates (for-loops) over all previous (left) siblings, including the supplied starting node. Terminates after the first (leftmost) sibling is reached. It is safe to remove or destroy the current node in the iteration.

Parameters

var_	Loop variable name. This variable will store the current node in the iteration and will be a pointer to ecu_ntnode.
iter_	Iterator to initialize. This will be a pointer to ecu_ntnode_prev_sibling_iterator.
start_	Starting node of the iteration. This node IS included in the iteration and is returned first. This will be a pointer to ecu_ntnode.

◆ ECU_NTNODE_PREV_SIBLING_FOR_EACH

#define ECU_NTNODE_PREV_SIBLING_FOR_EACH	(	var_,
		iter_,
		start_
	)

Value:

    for (struct ecu_ntnode *var_ = ecu_ntnode_prev_sibling_iterator_begin(iter_, start_); \
         var_ != ecu_ntnode_prev_sibling_iterator_end(iter_);                             \
         var_ = ecu_ntnode_prev_sibling_iterator_next(iter_))

Same as ECU_NTNODE_PREV_SIBLING_AT_FOR_EACH() but excludes the starting node from the iteration.

Parameters

var_	Loop variable name. This variable will store the current node in the iteration and will be a pointer to ecu_ntnode.
iter_	Iterator to initialize. This will be a pointer to ecu_ntnode_prev_sibling_iterator.
start_	Starting node of the iteration. This will be a pointer to ecu_ntnode. This node is NOT included in the iteration. The node previous to this one is returned first.

◆ ECU_NTNODE_SIBLING_FOR_EACH

#define ECU_NTNODE_SIBLING_FOR_EACH	(	var_,
		iter_,
		start_
	)

Value:

    for (struct ecu_ntnode *var_ = ecu_ntnode_sibling_iterator_begin(iter_, start_); \
         var_ != ecu_ntnode_sibling_iterator_end(iter_);                             \
         var_ = ecu_ntnode_sibling_iterator_next(iter_))

Iterates (for-loops) over all siblings, excluding the starting node. Performs wraparound if starting sibling is not the first sibling. It is safe to remove or destroy the current node in the iteration.

Note: If the starting node must be included in the iteration use a child iterator instead. SIBLING_AT() will not be supported since it is impossible to determine when to terminate the iteration.

Parameters

var_	Loop variable name. This variable will store the current node in the iteration and will be a pointer to ecu_ntnode.
iter_	Iterator to initialize. This will be a pointer to ecu_ntnode_sibling_iterator.
start_	Starting node of the iteration. This node is NOT included in the iteration. This will be a pointer to ecu_ntnode.

Function Documentation

◆ ecu_ntnode_child_iterator_begin()

struct ecu_ntnode* ecu_ntnode_child_iterator_begin	(	struct ecu_ntnode_child_iterator *	me,
		struct ecu_ntnode *	parent
	)

Starts an iteration over the supplied node's direct children. Grandchildren, great-grandchildren, etc are not iterated over. If the starting node has children its first (leftmost) child is returned. Otherwise NULL is returned, signifying the end of the iteration.

Precondition: Memory already allocated for me.; parent previously constructed via ecu_ntnode_ctor().

Warning: Not meant to be used directly. Use ECU_NTNODE_CHILD_FOR_EACH() instead.

Parameters

me	Non-const child iterator to initialize.
parent	Parent containing children to iterate over.

◆ ecu_ntnode_child_iterator_cbegin()

const struct ecu_ntnode* ecu_ntnode_child_iterator_cbegin	(	struct ecu_ntnode_child_citerator *	me,
		const struct ecu_ntnode *	parent
	)

Const-qualified version of ecu_ntnode_child_iterator_begin(). Starts an iteration over the supplied node's direct children. Grandchildren, great-grandchildren, etc are not iterated over. If the starting node has children its first (leftmost) child is returned. Otherwise NULL is returned, signifying the end of the iteration.

Precondition: Memory already allocated for me.; parent previously constructed via ecu_ntnode_ctor().

Warning: Not meant to be used directly. Use ECU_NTNODE_CONST_CHILD_FOR_EACH() instead.

Parameters

me	Const child iterator to initialize.
parent	Parent containing children to iterate over.

◆ ecu_ntnode_child_iterator_cend()

const struct ecu_ntnode* ecu_ntnode_child_iterator_cend ( struct ecu_ntnode_child_citerator * me )

Const-qualified version of ecu_ntnode_child_iterator_end(). Returns the ending node in the iteration, which is NULL.

Precondition: me started via ecu_ntnode_child_iterator_cbegin().

Warning: Not meant to be used directly. Use ECU_NTNODE_CONST_CHILD_FOR_EACH() instead.

Parameters

me	Const child iterator.

◆ ecu_ntnode_child_iterator_cnext()

const struct ecu_ntnode* ecu_ntnode_child_iterator_cnext ( struct ecu_ntnode_child_citerator * me )

Const-qualified version of ecu_ntnode_child_iterator_next(). Returns the next child in the iteration.

Precondition: me started via ecu_ntnode_child_iterator_cbegin().

Warning: Not meant to be used directly. Use ECU_NTNODE_CONST_CHILD_FOR_EACH() instead.

Parameters

me	Const child iterator.

◆ ecu_ntnode_child_iterator_end()

struct ecu_ntnode* ecu_ntnode_child_iterator_end ( struct ecu_ntnode_child_iterator * me )

Returns the ending node in the iteration, which is NULL.

Precondition: me started via ecu_ntnode_child_iterator_begin().

Warning: Not meant to be used directly. Use ECU_NTNODE_CHILD_FOR_EACH() instead.

Parameters

me	Non-const child iterator.

◆ ecu_ntnode_child_iterator_next()

struct ecu_ntnode* ecu_ntnode_child_iterator_next ( struct ecu_ntnode_child_iterator * me )

Returns the next child in the iteration.

Precondition: me started via ecu_ntnode_child_iterator_begin().

Warning: Not meant to be used directly. Use ECU_NTNODE_CHILD_FOR_EACH() instead.

Parameters

me	Non-const child iterator.

◆ ecu_ntnode_clca()

const struct ecu_ntnode* ecu_ntnode_clca	(	const struct ecu_ntnode *	n1,
		const struct ecu_ntnode *	n2
	)

Const-qualified version of ecu_ntnode_lca(). Returns the least common ancestor of n1 and n2. Returns NULL if nodes are in separate trees and do not have an LCA.

Precondition: n1 and n2 previously constructed via ecu_ntnode_ctor().

Parameters

n1	First node to check.
n2	Second node to check.

◆ ecu_ntnode_clear()

void ecu_ntnode_clear ( struct ecu_ntnode * me )

Removes the supplied node and all of its descendants from a tree. All nodes can be reused and added to another tree without reconstruction.

Precondition: me previously constructed via ecu_ntnode_ctor().

Parameters

me	Node to remove. Its entire subtree will also be removed.

◆ ecu_ntnode_cnext()

const struct ecu_ntnode* ecu_ntnode_cnext ( const struct ecu_ntnode * me )

Const-qualified version of ecu_ntnode_next(). Returns the node's next (right) sibling. NULL is returned if the node is the last (rightmost) sibling or has no siblings.

Precondition: me previously constructed via ecu_ntnode_ctor().

Parameters

me	Node to check.

◆ ecu_ntnode_count()

size_t ecu_ntnode_count ( const struct ecu_ntnode * me )

Returns the number of direct children the supplied node has. Grandchildren, great-granchildren, etc are not counted. Returns 0 if the node has no children.

Precondition: me previously constructed via ecu_ntnode_ctor().

Parameters

me	Node to check.

◆ ecu_ntnode_cparent()

const struct ecu_ntnode* ecu_ntnode_cparent ( const struct ecu_ntnode * me )

Const-qualified version of ecu_ntnode_parent(). Returns the supplied node's parent. NULL is returned if the node is a root.

Precondition: me previously constructed via ecu_ntnode_ctor().

Parameters

me	Node to check.

◆ ecu_ntnode_cprev()

const struct ecu_ntnode* ecu_ntnode_cprev ( const struct ecu_ntnode * me )

Const-qualified version of ecu_ntnode_prev(). Returns the node's previous (left) sibling. NULL is returned if the node is the first (leftmost) sibling or has no siblings.

Precondition: me previously constructed via ecu_ntnode_ctor().

Parameters

me	Node to check.

◆ ecu_ntnode_ctor()

void ecu_ntnode_ctor	(	struct ecu_ntnode *	me,
		void()(struct ecu_ntnode me, ecu_object_id_t id)	destroy,
		ecu_object_id_t	id
	)

Node constructor.

Precondition: Memory already allocated for me.

Warning: me must not be an active node within a tree, otherwise behavior is undefined.

Parameters

me	Node to construct. This cannot be NULL.
destroy	Optional callback. Defines any additional cleanup needed to fully destroy this user-defined node. Do not use API calls that edit the ecu_ntnode (insert, remove, etc) within this callback. Doing so is undefined behavior. Executes when node is destroyed via ecu_ntnode_destroy(), or if this node was in a tree that was destroyed by ecu_ntnode_destroy(). Supply ECU_NTNODE_DESTROY_UNUSED if unused.
id	Optional ID to assign to node. Used to identify different user-defined types stored in the same tree. Supply ECU_OBJECT_ID_UNUSED if unused. Otherwise this value must be greater than or equal to ECU_VALID_OBJECT_ID_BEGIN

◆ ecu_ntnode_destroy()

void ecu_ntnode_destroy ( struct ecu_ntnode * me )

Node destructor. Destroys the supplied node and all of its descendants (children, grandchildren, etc). All destroyed nodes must be reconstructed in order to be used again.

Precondition: me previously constructed via ecu_ntnode_ctor().

Warning: Memory is not freed since ECU is meant to be used without dynamic memory allocation. If the destroyed nodes were allocated on the heap, user is responsible for freeing memory. It is recommended to free the nodes inside the destroy callbacks passed to ecu_ntnode_ctor().

Parameters

me	Node to destroy. This node's subtree will also be destroyed.

◆ ecu_ntnode_first_cchild()

const struct ecu_ntnode* ecu_ntnode_first_cchild ( const struct ecu_ntnode * me )

Const-qualified version of ecu_ntnode_first_child(). Returns the node's first (leftmost) child. NULL is returned if the node has no children.

Precondition: me previously constructed via ecu_ntnode_ctor().

Parameters

me	Node to check.

◆ ecu_ntnode_first_child()

struct ecu_ntnode* ecu_ntnode_first_child ( struct ecu_ntnode * me )

Returns the node's first (leftmost) child. NULL is returned if the node has no children.

Precondition: me previously constructed via ecu_ntnode_ctor().

Parameters

me	Node to check.

◆ ecu_ntnode_id()

ecu_object_id_t ecu_ntnode_id ( const struct ecu_ntnode * me )

Returns the node's ID assigned when it was constructed in ecu_ntnode_ctor().

Precondition: me previously constructed via ecu_ntnode_ctor().

Parameters

me	Node to check.

◆ ecu_ntnode_in_tree()

bool ecu_ntnode_in_tree ( const struct ecu_ntnode * me )

Returns true if the node is in a tree. False otherwise. Note that this returns true for a root node that has children.

Precondition: me previously constructed via ecu_ntnode_ctor().

Parameters

me	Node to check.

◆ ecu_ntnode_insert_sibling_after()

void ecu_ntnode_insert_sibling_after	(	struct ecu_ntnode *	pos,
		struct ecu_ntnode *	sibling
	)

Inserts a sibling node into the tree after the specified position. sibling becomes pos's next sibling.

Precondition: pos and sibling previously constructed via ecu_ntnode_ctor().

Parameters

pos	Position node. Node is inserted after this position. This cannot be a root.
sibling	Node to insert. This cannot already be within a tree unless this is a root node. If this is a root of an existing tree, its tree remains intact.

◆ ecu_ntnode_insert_sibling_before()

void ecu_ntnode_insert_sibling_before	(	struct ecu_ntnode *	pos,
		struct ecu_ntnode *	sibling
	)

Inserts a sibling node into the tree before the specified position. sibling becomes pos's previous sibling.

Precondition: pos and sibling previously constructed via ecu_ntnode_ctor().

Parameters

pos	Position node. Node is inserted before this position. This cannot be a root.
sibling	Node to insert. This cannot already be within a tree unless this is a root node. If this is a root of an existing tree, its tree remains intact.

◆ ecu_ntnode_is_descendant()

bool ecu_ntnode_is_descendant ( const struct ecu_ntnode * me )

Returns true if the node is in a tree and is not the root. False otherwise.

Precondition: me previously constructed via ecu_ntnode_ctor().

Parameters

me	Node to check.

◆ ecu_ntnode_is_leaf()

bool ecu_ntnode_is_leaf ( const struct ecu_ntnode * me )

Returns true if the node is a leaf, meaning it has no children. False otherwise. Note that this returns true for an empty node since that is technically a leaf.

Precondition: me previously constructed via ecu_ntnode_ctor().

Parameters

me	Node to check.

◆ ecu_ntnode_is_root()

bool ecu_ntnode_is_root ( const struct ecu_ntnode * me )

Returns true if the node is a root, meaning it has no parent. False otherwise. Note that this returns true for an empty node since that is technically a root.

Precondition: me previously constructed via ecu_ntnode_ctor().

Parameters

me	Node to check.

◆ ecu_ntnode_last_cchild()

const struct ecu_ntnode* ecu_ntnode_last_cchild ( const struct ecu_ntnode * me )

Const-qualified version of ecu_ntnode_last_child(). Returns the node's last (rightmost) child. NULL is returned if the node has no children.

Precondition: me previously constructed via ecu_ntnode_ctor().

Parameters

me	Node to check.

◆ ecu_ntnode_last_child()

struct ecu_ntnode* ecu_ntnode_last_child ( struct ecu_ntnode * me )

Returns the node's last (rightmost) child. NULL is returned if the node has no children.

Precondition: me previously constructed via ecu_ntnode_ctor().

Parameters

me	Node to check.

◆ ecu_ntnode_lca()

struct ecu_ntnode* ecu_ntnode_lca	(	struct ecu_ntnode *	n1,
		struct ecu_ntnode *	n2
	)

Returns the least common ancestor of n1 and n2. Returns NULL if nodes are in separate trees and do not have an LCA.

Precondition: n1 and n2 previously constructed via ecu_ntnode_ctor().

Parameters

n1	First node to check.
n2	Second node to check.

◆ ecu_ntnode_level()

size_t ecu_ntnode_level ( const struct ecu_ntnode * me )

Returns which level of the tree the supplied node is in. Returns 0 if the supplied node is a root.

Precondition: me previously constructed via ecu_ntnode_ctor().

Parameters

me	Node to check.

◆ ecu_ntnode_next()

struct ecu_ntnode* ecu_ntnode_next ( struct ecu_ntnode * me )

Returns the node's next (right) sibling. NULL is returned if the node is the last (rightmost) sibling or has no siblings.

Precondition: me previously constructed via ecu_ntnode_ctor().

Parameters

me	Node to check.

◆ ecu_ntnode_next_sibling_iterator_at()

struct ecu_ntnode* ecu_ntnode_next_sibling_iterator_at	(	struct ecu_ntnode_next_sibling_iterator *	me,
		struct ecu_ntnode *	start
	)

Starts an iteration over all next (right) siblings, including the supplied starting node. The supplied starting node is returned.

Precondition: Memory already allocated for me.; start previously constructed via ecu_ntnode_ctor().

Warning: Not meant to be used directly. Use ECU_NTNODE_NEXT_SIBLING_AT_FOR_EACH() instead.

Parameters

me	Non-const next sibling iterator to initialize.
start	Starting node of the iteration.

◆ ecu_ntnode_next_sibling_iterator_begin()

struct ecu_ntnode* ecu_ntnode_next_sibling_iterator_begin	(	struct ecu_ntnode_next_sibling_iterator *	me,
		struct ecu_ntnode *	start
	)

Starts an iteration over all next (right) siblings, excluding the supplied starting node. If the starting node has siblings the next (right) sibling to it is returned. Otherwise NULL is returned, signifying the end of the iteration.

Precondition: Memory already allocated for me.; start previously constructed via ecu_ntnode_ctor().

Warning: Not meant to be used directly. Use ECU_NTNODE_NEXT_SIBLING_FOR_EACH() instead.

Parameters

me	Non-const next sibling iterator to initialize.
start	Starting node of the iteration.

◆ ecu_ntnode_next_sibling_iterator_cat()

const struct ecu_ntnode* ecu_ntnode_next_sibling_iterator_cat	(	struct ecu_ntnode_next_sibling_citerator *	me,
		const struct ecu_ntnode *	start
	)

Const-qualified version of ecu_ntnode_next_sibling_iterator_at(). Starts an iteration over all next (right) siblings, including the supplied starting node. The supplied starting node is returned.

Precondition: Memory already allocated for me.; start previously constructed via ecu_ntnode_ctor().

Warning: Not meant to be used directly. Use ECU_NTNODE_CONST_NEXT_SIBLING_AT_FOR_EACH() instead.

Parameters

me	Const next sibling iterator to initialize.
start	Starting node of the iteration.

◆ ecu_ntnode_next_sibling_iterator_cbegin()

const struct ecu_ntnode* ecu_ntnode_next_sibling_iterator_cbegin	(	struct ecu_ntnode_next_sibling_citerator *	me,
		const struct ecu_ntnode *	start
	)

Const-qualified version of ecu_ntnode_next_sibling_iterator_begin(). Starts an iteration over all next (right) siblings, excluding the supplied starting node. If the starting node has siblings the next (right) sibling to it is returned. Otherwise NULL is returned, signifying the end of the iteration.

Precondition: Memory already allocated for me.; start previously constructed via ecu_ntnode_ctor().

Warning: Not meant to be used directly. Use ECU_NTNODE_CONST_NEXT_SIBLING_FOR_EACH() instead.

Parameters

me	Const next sibling iterator to initialize.
start	Starting node of the iteration.

◆ ecu_ntnode_next_sibling_iterator_cend()

const struct ecu_ntnode* ecu_ntnode_next_sibling_iterator_cend ( struct ecu_ntnode_next_sibling_citerator * me )

Const-qualified version of ecu_ntnode_next_sibling_iterator_end(). Returns the ending node in the iteration, which is NULL.

Precondition: me started via ecu_ntnode_next_sibling_iterator_cat() or ecu_ntnode_next_sibling_iterator_cbegin().

Warning: Not meant to be used directly. Use ECU_NTNODE_CONST_NEXT_SIBLING_AT_FOR_EACH() or ECU_NTNODE_CONST_NEXT_SIBLING_FOR_EACH() instead.

Parameters

me	Const next sibling iterator.

◆ ecu_ntnode_next_sibling_iterator_cnext()

const struct ecu_ntnode* ecu_ntnode_next_sibling_iterator_cnext ( struct ecu_ntnode_next_sibling_citerator * me )

Const-qualified version of ecu_ntnode_next_sibling_iterator_next(). Returns the next node in the iteration.

Precondition: me started via ecu_ntnode_next_sibling_iterator_cat() or ecu_ntnode_next_sibling_iterator_cbegin().

Warning: Not meant to be used directly. Use ECU_NTNODE_CONST_NEXT_SIBLING_AT_FOR_EACH() or ECU_NTNODE_CONST_NEXT_SIBLING_FOR_EACH() instead.

Parameters

me	Const next sibling iterator.

◆ ecu_ntnode_next_sibling_iterator_end()

struct ecu_ntnode* ecu_ntnode_next_sibling_iterator_end ( struct ecu_ntnode_next_sibling_iterator * me )

Returns the ending node in the iteration, which is NULL.

Precondition: me started via ecu_ntnode_next_sibling_iterator_at() or ecu_ntnode_next_sibling_iterator_begin().

Warning: Not meant to be used directly. Use ECU_NTNODE_NEXT_SIBLING_AT_FOR_EACH() or ECU_NTNODE_NEXT_SIBLING_FOR_EACH() instead.

Parameters

me	Non-const next sibling iterator.

◆ ecu_ntnode_next_sibling_iterator_next()

struct ecu_ntnode* ecu_ntnode_next_sibling_iterator_next ( struct ecu_ntnode_next_sibling_iterator * me )

Returns the next node in the iteration.

Precondition: me started via ecu_ntnode_next_sibling_iterator_at() or ecu_ntnode_next_sibling_iterator_begin().

Warning: Not meant to be used directly. Use ECU_NTNODE_NEXT_SIBLING_AT_FOR_EACH() or ECU_NTNODE_NEXT_SIBLING_FOR_EACH() instead.

Parameters

me	Non-const next sibling iterator.

◆ ecu_ntnode_parent()

struct ecu_ntnode* ecu_ntnode_parent ( struct ecu_ntnode * me )

Returns the supplied node's parent. NULL is returned if the node is a root.

Precondition: me previously constructed via ecu_ntnode_ctor().

Parameters

me	Node to check.

◆ ecu_ntnode_parent_iterator_at()

struct ecu_ntnode* ecu_ntnode_parent_iterator_at	(	struct ecu_ntnode_parent_iterator *	me,
		struct ecu_ntnode *	start
	)

Starts an iteration over all parents, including the supplied starting node. The supplied starting node is returned.

Precondition: Memory already allocated for me.; start previously constructed via ecu_ntnode_ctor().

Warning: Not meant to be used directly. Use ECU_NTNODE_PARENT_AT_FOR_EACH() instead.

Parameters

me	Non-const parent iterator to initialize.
start	Starting node of the iteration.

◆ ecu_ntnode_parent_iterator_begin()

struct ecu_ntnode* ecu_ntnode_parent_iterator_begin	(	struct ecu_ntnode_parent_iterator *	me,
		struct ecu_ntnode *	start
	)

Starts an iteration over all parents, excluding the supplied starting node. If the starting node has parents, its parent is returned. Otherwise NULL is returned, signifying the end of the iteration.

Precondition: Memory already allocated for me.; start previously constructed via ecu_ntnode_ctor().

Warning: Not meant to be used directly. Use ECU_NTNODE_PARENT_FOR_EACH() instead.

Parameters

me	Non-const parent iterator to initialize.
start	Starting node of the iteration.

◆ ecu_ntnode_parent_iterator_cat()

const struct ecu_ntnode* ecu_ntnode_parent_iterator_cat	(	struct ecu_ntnode_parent_citerator *	me,
		const struct ecu_ntnode *	start
	)

Const-qualified version of ecu_ntnode_parent_iterator_at(). Starts an iteration over all parents, including the supplied starting node. The supplied starting node is returned.

Precondition: Memory already allocated for me.; start previously constructed via ecu_ntnode_ctor().

Warning: Not meant to be used directly. Use ECU_NTNODE_CONST_PARENT_AT_FOR_EACH() instead.

Parameters

me	Const parent iterator to initialize.
start	Starting node of the iteration.

◆ ecu_ntnode_parent_iterator_cbegin()

const struct ecu_ntnode* ecu_ntnode_parent_iterator_cbegin	(	struct ecu_ntnode_parent_citerator *	me,
		const struct ecu_ntnode *	start
	)

Const-qualified version of ecu_ntnode_parent_iterator_begin(). Starts an iteration over all parents, excluding the supplied starting node. If the starting node has parents, its parent is returned. Otherwise NULL is returned, signifying the end of the iteration.

Precondition: Memory already allocated for me.; start previously constructed via ecu_ntnode_ctor().

Warning: Not meant to be used directly. Use ECU_NTNODE_CONST_PARENT_FOR_EACH() instead.

Parameters

me	Const parent iterator to initialize.
start	Starting node of the iteration.

◆ ecu_ntnode_parent_iterator_cend()

const struct ecu_ntnode* ecu_ntnode_parent_iterator_cend ( struct ecu_ntnode_parent_citerator * me )

Const-qualified version of ecu_ntnode_parent_iterator_end(). Returns the ending node in the iteration, which is NULL.

Precondition: me started via ecu_ntnode_parent_iterator_cat() or ecu_ntnode_parent_iterator_cbegin().

Warning: Not meant to be used directly. Use ECU_NTNODE_CONST_PARENT_AT_FOR_EACH() or ECU_NTNODE_CONST_PARENT_FOR_EACH() instead.

Parameters

me	Const parent iterator.

◆ ecu_ntnode_parent_iterator_cnext()

const struct ecu_ntnode* ecu_ntnode_parent_iterator_cnext ( struct ecu_ntnode_parent_citerator * me )

Const-qualified version of ecu_ntnode_parent_iterator_next(). Returns the next parent in the iteration.

Precondition: me started via ecu_ntnode_parent_iterator_cat() or ecu_ntnode_parent_iterator_cbegin().

Warning: Not meant to be used directly. Use ECU_NTNODE_CONST_PARENT_AT_FOR_EACH() or ECU_NTNODE_CONST_PARENT_FOR_EACH() instead.

Parameters

me	Const parent iterator.

◆ ecu_ntnode_parent_iterator_end()

struct ecu_ntnode* ecu_ntnode_parent_iterator_end ( struct ecu_ntnode_parent_iterator * me )

Returns the ending node in the iteration, which is NULL.

Precondition: me started via ecu_ntnode_parent_iterator_at() or ecu_ntnode_parent_iterator_begin().

Warning: Not meant to be used directly. Use ECU_NTNODE_PARENT_AT_FOR_EACH() or ECU_NTNODE_PARENT_FOR_EACH() instead.

Parameters

me	Non-const parent iterator.

◆ ecu_ntnode_parent_iterator_next()

struct ecu_ntnode* ecu_ntnode_parent_iterator_next ( struct ecu_ntnode_parent_iterator * me )

Returns the next parent in the iteration.

Precondition: me started via ecu_ntnode_parent_iterator_at() or ecu_ntnode_parent_iterator_begin().

Warning: Not meant to be used directly. Use ECU_NTNODE_PARENT_AT_FOR_EACH() or ECU_NTNODE_PARENT_FOR_EACH() instead.

Parameters

me	Non-const parent iterator.

◆ ecu_ntnode_postorder_iterator_begin()

struct ecu_ntnode* ecu_ntnode_postorder_iterator_begin	(	struct ecu_ntnode_postorder_iterator *	me,
		struct ecu_ntnode *	root
	)

Starts a postorder iteration over the supplied node's tree. Returns the first node in the iteration.

Precondition: Memory already allocated for me.; root previously constructed via ecu_ntnode_ctor().

Warning: Not meant to be used directly. Use ECU_NTNODE_POSTORDER_FOR_EACH() instead.

Parameters

me	Non-const postorder iterator to initialize.
root	Root of tree to iterate over. This root is included in the iteration.

◆ ecu_ntnode_postorder_iterator_cbegin()

const struct ecu_ntnode* ecu_ntnode_postorder_iterator_cbegin	(	struct ecu_ntnode_postorder_citerator *	me,
		const struct ecu_ntnode *	root
	)

Const-qualified version of ecu_ntnode_postorder_iterator_begin(). Starts a postorder iteration over the supplied node's tree. Returns the first node in the iteration.

Precondition: Memory already allocated for me.; root previously constructed via ecu_ntnode_ctor().

Warning: Not meant to be used directly. Use ECU_NTNODE_CONST_POSTORDER_FOR_EACH() instead.

Parameters

me	Const postorder iterator to initialize.
root	Root of tree to iterate over. This root is included in the iteration.

◆ ecu_ntnode_postorder_iterator_cend()

const struct ecu_ntnode* ecu_ntnode_postorder_iterator_cend ( struct ecu_ntnode_postorder_citerator * me )

Const-qualified version of ecu_ntnode_postorder_iterator_end(). Returns the ending node in the iteration, which is a dummy delimiter.

Precondition: me started via ecu_ntnode_postorder_iterator_cbegin().

Warning: The node returned by this function should never be used since it is a dummy delimiter.; Not meant to be used directly. Use ECU_NTNODE_CONST_POSTORDER_FOR_EACH() instead.

Parameters

me	Const postorder iterator.

◆ ecu_ntnode_postorder_iterator_cnext()

const struct ecu_ntnode* ecu_ntnode_postorder_iterator_cnext ( struct ecu_ntnode_postorder_citerator * me )

Const-qualified version of ecu_ntnode_postorder_iterator_next(). Returns the next node in the iteration.

Precondition: me started via ecu_ntnode_postorder_iterator_cbegin().

Warning: Not meant to be used directly. Use ECU_NTNODE_CONST_POSTORDER_FOR_EACH() instead.

Parameters

me	Const postorder iterator.

◆ ecu_ntnode_postorder_iterator_end()

struct ecu_ntnode* ecu_ntnode_postorder_iterator_end ( struct ecu_ntnode_postorder_iterator * me )

Returns the ending node in the iteration, which is a dummy delimiter.

Precondition: me started via ecu_ntnode_postorder_iterator_begin().

Warning: The node returned by this function should never be used since it is a dummy delimiter.; Not meant to be used directly. Use ECU_NTNODE_POSTORDER_FOR_EACH() instead.

Parameters

me	Non-const postorder iterator.

◆ ecu_ntnode_postorder_iterator_next()

struct ecu_ntnode* ecu_ntnode_postorder_iterator_next ( struct ecu_ntnode_postorder_iterator * me )

Returns the next node in the iteration.

Precondition: me started via ecu_ntnode_postorder_iterator_begin().

Warning: Not meant to be used directly. Use ECU_NTNODE_POSTORDER_FOR_EACH() instead.

Parameters

me	Non-const postorder iterator.

◆ ecu_ntnode_preorder_iterator_begin()

struct ecu_ntnode* ecu_ntnode_preorder_iterator_begin	(	struct ecu_ntnode_preorder_iterator *	me,
		struct ecu_ntnode *	root
	)

Starts a preorder iteration over the supplied node's tree. The supplied root is returned, which is the first node in the iteration.

Precondition: Memory already allocated for me.; root previously constructed via ecu_ntnode_ctor().

Warning: Not meant to be used directly. Use ECU_NTNODE_PREORDER_FOR_EACH() instead.

Parameters

me	Non-const preorder iterator to initialize.
root	Root of tree to iterate over. This root is included in the iteration and is returned in this function.

◆ ecu_ntnode_preorder_iterator_cbegin()

const struct ecu_ntnode* ecu_ntnode_preorder_iterator_cbegin	(	struct ecu_ntnode_preorder_citerator *	me,
		const struct ecu_ntnode *	root
	)

Const-qualified version of ecu_ntnode_preorder_iterator_begin(). Starts a preorder iteration over the supplied node's tree. The supplied root is returned, which is the first node in the iteration.

Precondition: Memory already allocated for me.; root previously constructed via ecu_ntnode_ctor().

Warning: Not meant to be used directly. Use ECU_NTNODE_CONST_PREORDER_FOR_EACH() instead.

Parameters

me	Const preorder iterator to initialize.
root	Root of tree to iterate over. This root is included in the iteration and is returned in this function.

◆ ecu_ntnode_preorder_iterator_cend()

const struct ecu_ntnode* ecu_ntnode_preorder_iterator_cend ( struct ecu_ntnode_preorder_citerator * me )

Const-qualified version of ecu_ntnode_preorder_iterator_end(). Returns the ending node in the iteration, which is a dummy delimiter.

Precondition: me started via ecu_ntnode_preorder_iterator_cbegin().

Warning: The node returned by this function should never be used since it is a dummy delimiter.; Not meant to be used directly. Use ECU_NTNODE_CONST_PREORDER_FOR_EACH() instead.

Parameters

me	Const preorder iterator.

◆ ecu_ntnode_preorder_iterator_cnext()

const struct ecu_ntnode* ecu_ntnode_preorder_iterator_cnext ( struct ecu_ntnode_preorder_citerator * me )

Const-qualified version of ecu_ntnode_preorder_iterator_next(). Returns the next node in the iteration.

Precondition: me started via ecu_ntnode_preorder_iterator_cbegin().

Warning: Not meant to be used directly. Use ECU_NTNODE_CONST_PREORDER_FOR_EACH() instead.

Parameters

me	Const preorder iterator.

◆ ecu_ntnode_preorder_iterator_end()

struct ecu_ntnode* ecu_ntnode_preorder_iterator_end ( struct ecu_ntnode_preorder_iterator * me )

Returns the ending node in the iteration, which is a dummy delimiter.

Precondition: me started via ecu_ntnode_preorder_iterator_begin().

Warning: The node returned by this function should never be used since it is a dummy delimiter.; Not meant to be used directly. Use ECU_NTNODE_PREORDER_FOR_EACH() instead.

Parameters

me	Non-const preorder iterator.

◆ ecu_ntnode_preorder_iterator_next()

struct ecu_ntnode* ecu_ntnode_preorder_iterator_next ( struct ecu_ntnode_preorder_iterator * me )

Returns the next node in the iteration.

Precondition: me started via ecu_ntnode_preorder_iterator_begin().

Warning: Not meant to be used directly. Use ECU_NTNODE_PREORDER_FOR_EACH() instead.

Parameters

me	Non-const preorder iterator.

◆ ecu_ntnode_prev()

struct ecu_ntnode* ecu_ntnode_prev ( struct ecu_ntnode * me )

Returns the node's previous (left) sibling. NULL is returned if the node is the first (leftmost) sibling or has no siblings.

Precondition: me previously constructed via ecu_ntnode_ctor().

Parameters

me	Node to check.

◆ ecu_ntnode_prev_sibling_iterator_at()

struct ecu_ntnode* ecu_ntnode_prev_sibling_iterator_at	(	struct ecu_ntnode_prev_sibling_iterator *	me,
		struct ecu_ntnode *	start
	)

Starts an iteration over all previous (left) siblings, including the supplied starting node. The supplied starting node is returned.

Precondition: Memory already allocated for me.; start previously constructed via ecu_ntnode_ctor().

Warning: Not meant to be used directly. Use ECU_NTNODE_PREV_SIBLING_AT_FOR_EACH() instead.

Parameters

me	Non-const prev sibling iterator to initialize.
start	Starting node of the iteration.

◆ ecu_ntnode_prev_sibling_iterator_begin()

struct ecu_ntnode* ecu_ntnode_prev_sibling_iterator_begin	(	struct ecu_ntnode_prev_sibling_iterator *	me,
		struct ecu_ntnode *	start
	)

Starts an iteration over all previous (left) siblings, excluding the supplied starting node. If the starting node has siblings the previous (left) sibling to it is returned. Otherwise NULL is returned, signifying the end of the iteration.

Precondition: Memory already allocated for me.; start previously constructed via ecu_ntnode_ctor().

Warning: Not meant to be used directly. Use ECU_NTNODE_PREV_SIBLING_FOR_EACH() instead.

Parameters

me	Non-const prev sibling iterator to initialize.
start	Starting node of the iteration.

◆ ecu_ntnode_prev_sibling_iterator_cat()

const struct ecu_ntnode* ecu_ntnode_prev_sibling_iterator_cat	(	struct ecu_ntnode_prev_sibling_citerator *	me,
		const struct ecu_ntnode *	start
	)

Const-qualified version of ecu_ntnode_prev_sibling_iterator_at(). Starts an iteration over all previous (left) siblings, including the supplied starting node. The supplied starting node is returned.

Precondition: Memory already allocated for me.; start previously constructed via ecu_ntnode_ctor().

Warning: Not meant to be used directly. Use ECU_NTNODE_CONST_PREV_SIBLING_AT_FOR_EACH() instead.

Parameters

me	Const prev sibling iterator to initialize.
start	Starting node of the iteration.

◆ ecu_ntnode_prev_sibling_iterator_cbegin()

const struct ecu_ntnode* ecu_ntnode_prev_sibling_iterator_cbegin	(	struct ecu_ntnode_prev_sibling_citerator *	me,
		const struct ecu_ntnode *	start
	)

Const-qualified version of ecu_ntnode_prev_sibling_iterator_begin(). Starts an iteration over all previous (left) siblings, excluding the supplied starting node. If the starting node has siblings the previous (left) sibling to it is returned. Otherwise NULL is returned, signifying the end of the iteration.

Precondition: Memory already allocated for me.; start previously constructed via ecu_ntnode_ctor().

Warning: Not meant to be used directly. Use ECU_NTNODE_CONST_PREV_SIBLING_FOR_EACH() instead.

Parameters

me	Const prev sibling iterator to initialize.
start	Starting node of the iteration.

◆ ecu_ntnode_prev_sibling_iterator_cend()

const struct ecu_ntnode* ecu_ntnode_prev_sibling_iterator_cend ( struct ecu_ntnode_prev_sibling_citerator * me )

Const-qualified version of ecu_ntnode_prev_sibling_iterator_end(). Returns the ending node in the iteration, which is NULL.

Precondition: me started via ecu_ntnode_prev_sibling_iterator_cat() or ecu_ntnode_prev_sibling_iterator_cbegin().

Warning: Not meant to be used directly. Use ECU_NTNODE_CONST_PREV_SIBLING_AT_FOR_EACH() or ECU_NTNODE_CONST_PREV_SIBLING_FOR_EACH() instead.

Parameters

me	Const prev sibling iterator.

◆ ecu_ntnode_prev_sibling_iterator_cnext()

const struct ecu_ntnode* ecu_ntnode_prev_sibling_iterator_cnext ( struct ecu_ntnode_prev_sibling_citerator * me )

Const-qualified version of ecu_ntnode_prev_sibling_iterator_next(). Returns the next node in the iteration.

Precondition: me started via ecu_ntnode_prev_sibling_iterator_cat() or ecu_ntnode_prev_sibling_iterator_cbegin().

Warning: Not meant to be used directly. Use ECU_NTNODE_CONST_PREV_SIBLING_AT_FOR_EACH() or ECU_NTNODE_CONST_PREV_SIBLING_FOR_EACH() instead.

Parameters

me	Const prev sibling iterator.

◆ ecu_ntnode_prev_sibling_iterator_end()

struct ecu_ntnode* ecu_ntnode_prev_sibling_iterator_end ( struct ecu_ntnode_prev_sibling_iterator * me )

Returns the ending node in the iteration, which is NULL.

Precondition: me started via ecu_ntnode_prev_sibling_iterator_at() or ecu_ntnode_prev_sibling_iterator_begin().

Warning: Not meant to be used directly. Use ECU_NTNODE_PREV_SIBLING_AT_FOR_EACH() or ECU_NTNODE_PREV_SIBLING_FOR_EACH() instead.

Parameters

me	Non-const prev sibling iterator.

◆ ecu_ntnode_prev_sibling_iterator_next()

struct ecu_ntnode* ecu_ntnode_prev_sibling_iterator_next ( struct ecu_ntnode_prev_sibling_iterator * me )

Returns the next node in the iteration.

Precondition: me started via ecu_ntnode_prev_sibling_iterator_at() or ecu_ntnode_prev_sibling_iterator_begin().

Warning: Not meant to be used directly. Use ECU_NTNODE_PREV_SIBLING_AT_FOR_EACH() or ECU_NTNODE_PREV_SIBLING_FOR_EACH() instead.

Parameters

me	Non-const prev sibling iterator.

◆ ecu_ntnode_push_child_back()

void ecu_ntnode_push_child_back	(	struct ecu_ntnode *	parent,
		struct ecu_ntnode *	child
	)

Inserts a rightmost child node into the tree. child becomes parent's last (rightmost) child.

Precondition: parent and child previously constructed via ecu_ntnode_ctor().

Parameters

parent	Parent node to add child to.
child	Node to insert. This will become `parent's` last child. This cannot already be within a tree unless this is a root node.

◆ ecu_ntnode_push_child_front()

void ecu_ntnode_push_child_front	(	struct ecu_ntnode *	parent,
		struct ecu_ntnode *	child
	)

Inserts a leftmost child node into the tree. child becomes parent's first (leftmost) child.

Precondition: parent and child previously constructed via ecu_ntnode_ctor().

Parameters

parent	Parent node to add child to.
child	Node to insert. This will become `parent's` first child. This cannot already be within a tree unless this is a root node.

◆ ecu_ntnode_remove()

void ecu_ntnode_remove ( struct ecu_ntnode * me )

Removes node from a tree. If the removed node has descendants, the node becomes a new root with its tree intact. The tree remains unchanged if an empty or root node is supplied.

Precondition: me previously constructed via ecu_ntnode_ctor().

Parameters

me	Node to remove.

◆ ecu_ntnode_sibling_iterator_begin()

struct ecu_ntnode* ecu_ntnode_sibling_iterator_begin	(	struct ecu_ntnode_sibling_iterator *	me,
		struct ecu_ntnode *	start
	)

Starts an iteration over all siblings, excluding the supplied starting node.

Precondition: Memory already allocated for me.; start previously constructed via ecu_ntnode_ctor().

Warning: Not meant to be used directly. Use ECU_NTNODE_SIBLING_FOR_EACH() instead.

Parameters

me	Non-const sibling iterator to initialize.
start	Starting node of the iteration.

◆ ecu_ntnode_sibling_iterator_cbegin()

const struct ecu_ntnode* ecu_ntnode_sibling_iterator_cbegin	(	struct ecu_ntnode_sibling_citerator *	me,
		const struct ecu_ntnode *	start
	)

Const-qualified version of ecu_ntnode_sibling_iterator_begin(). Starts an iteration over all siblings, excluding the supplied starting node.

Precondition: Memory already allocated for me.; start previously constructed via ecu_ntnode_ctor().

Warning: Not meant to be used directly. Use ECU_NTNODE_CONST_SIBLING_FOR_EACH() instead.

Parameters

me	Const sibling iterator to initialize.
start	Starting node of the iteration.

◆ ecu_ntnode_sibling_iterator_cend()

const struct ecu_ntnode* ecu_ntnode_sibling_iterator_cend ( struct ecu_ntnode_sibling_citerator * me )

Const-qualified version of ecu_ntnode_sibling_iterator_end(). Returns the ending node in the iteration.

Precondition: me started via ecu_ntnode_sibling_iterator_cbegin().

Warning: Not meant to be used directly. Use ECU_NTNODE_CONST_SIBLING_FOR_EACH() instead.

Parameters

me	Const sibling iterator.

◆ ecu_ntnode_sibling_iterator_cnext()

const struct ecu_ntnode* ecu_ntnode_sibling_iterator_cnext ( struct ecu_ntnode_sibling_citerator * me )

Const-qualified version of ecu_ntnode_sibling_iterator_next(). Returns the next sibling in the iteration.

Precondition: me started via ecu_ntnode_sibling_iterator_cbegin().

Warning: Not meant to be used directly. Use ECU_NTNODE_CONST_SIBLING_FOR_EACH() instead.

Parameters

me	Const sibling iterator.

◆ ecu_ntnode_sibling_iterator_end()

struct ecu_ntnode* ecu_ntnode_sibling_iterator_end ( struct ecu_ntnode_sibling_iterator * me )

Returns the ending node in the iteration.

Precondition: me started via ecu_ntnode_sibling_iterator_begin().

Warning: Not meant to be used directly. Use ECU_NTNODE_SIBLING_FOR_EACH() instead.

Parameters

me	Non-const sibling iterator.

◆ ecu_ntnode_sibling_iterator_next()

struct ecu_ntnode* ecu_ntnode_sibling_iterator_next ( struct ecu_ntnode_sibling_iterator * me )

Returns the next sibling in the iteration.

Precondition: me started via ecu_ntnode_sibling_iterator_begin().

Warning: Not meant to be used directly. Use ECU_NTNODE_SIBLING_FOR_EACH() instead.

Parameters

me	Non-const sibling iterator.

◆ ecu_ntnode_size()

size_t ecu_ntnode_size ( const struct ecu_ntnode * me )

Returns the total number of descendants (children, grandchildren, etc) the node has. Returns 0 if the node has no descendants.

Precondition: me previously constructed via ecu_ntnode_ctor().

Parameters

me	Node to check.

◆ ecu_ntnode_valid()

bool ecu_ntnode_valid ( const struct ecu_ntnode * me )

Returns true if supplied node has been constructed via ecu_ntnode_ctor() and can be used. False otherwise.

Parameters

me	Node to check.

inc/ecu/ntnode.h File Reference

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ ECU_NTNODE_CHILD_FOR_EACH

◆ ECU_NTNODE_CONST_CHILD_FOR_EACH

◆ ECU_NTNODE_CONST_NEXT_SIBLING_AT_FOR_EACH

◆ ECU_NTNODE_CONST_NEXT_SIBLING_FOR_EACH

◆ ECU_NTNODE_CONST_PARENT_AT_FOR_EACH

◆ ECU_NTNODE_CONST_PARENT_FOR_EACH

◆ ECU_NTNODE_CONST_POSTORDER_FOR_EACH

◆ ECU_NTNODE_CONST_PREORDER_FOR_EACH

◆ ECU_NTNODE_CONST_PREV_SIBLING_AT_FOR_EACH

◆ ECU_NTNODE_CONST_PREV_SIBLING_FOR_EACH

◆ ECU_NTNODE_CONST_SIBLING_FOR_EACH

◆ ECU_NTNODE_GET_CONST_ENTRY

◆ ECU_NTNODE_GET_ENTRY

◆ ECU_NTNODE_NEXT_SIBLING_AT_FOR_EACH

◆ ECU_NTNODE_NEXT_SIBLING_FOR_EACH

◆ ECU_NTNODE_PARENT_AT_FOR_EACH

◆ ECU_NTNODE_PARENT_FOR_EACH

◆ ECU_NTNODE_POSTORDER_FOR_EACH

◆ ECU_NTNODE_PREORDER_FOR_EACH

◆ ECU_NTNODE_PREV_SIBLING_AT_FOR_EACH

◆ ECU_NTNODE_PREV_SIBLING_FOR_EACH

◆ ECU_NTNODE_SIBLING_FOR_EACH

Function Documentation

◆ ecu_ntnode_child_iterator_begin()

◆ ecu_ntnode_child_iterator_cbegin()

◆ ecu_ntnode_child_iterator_cend()

◆ ecu_ntnode_child_iterator_cnext()

◆ ecu_ntnode_child_iterator_end()

◆ ecu_ntnode_child_iterator_next()

◆ ecu_ntnode_clca()

◆ ecu_ntnode_clear()

◆ ecu_ntnode_cnext()

◆ ecu_ntnode_count()

◆ ecu_ntnode_cparent()

◆ ecu_ntnode_cprev()

◆ ecu_ntnode_ctor()

◆ ecu_ntnode_destroy()

◆ ecu_ntnode_first_cchild()

◆ ecu_ntnode_first_child()

◆ ecu_ntnode_id()

◆ ecu_ntnode_in_tree()

◆ ecu_ntnode_insert_sibling_after()

◆ ecu_ntnode_insert_sibling_before()

◆ ecu_ntnode_is_descendant()

◆ ecu_ntnode_is_leaf()

◆ ecu_ntnode_is_root()

◆ ecu_ntnode_last_cchild()

◆ ecu_ntnode_last_child()

◆ ecu_ntnode_lca()

◆ ecu_ntnode_level()

◆ ecu_ntnode_next()

◆ ecu_ntnode_next_sibling_iterator_at()

◆ ecu_ntnode_next_sibling_iterator_begin()

◆ ecu_ntnode_next_sibling_iterator_cat()

◆ ecu_ntnode_next_sibling_iterator_cbegin()

◆ ecu_ntnode_next_sibling_iterator_cend()

◆ ecu_ntnode_next_sibling_iterator_cnext()

◆ ecu_ntnode_next_sibling_iterator_end()

◆ ecu_ntnode_next_sibling_iterator_next()

◆ ecu_ntnode_parent()

◆ ecu_ntnode_parent_iterator_at()

◆ ecu_ntnode_parent_iterator_begin()

◆ ecu_ntnode_parent_iterator_cat()

◆ ecu_ntnode_parent_iterator_cbegin()

◆ ecu_ntnode_parent_iterator_cend()

◆ ecu_ntnode_parent_iterator_cnext()

◆ ecu_ntnode_parent_iterator_end()

◆ ecu_ntnode_parent_iterator_next()

◆ ecu_ntnode_postorder_iterator_begin()

◆ ecu_ntnode_postorder_iterator_cbegin()

◆ ecu_ntnode_postorder_iterator_cend()

◆ ecu_ntnode_postorder_iterator_cnext()

◆ ecu_ntnode_postorder_iterator_end()

◆ ecu_ntnode_postorder_iterator_next()