Directory tree

Refcounted tree keyed by slash-separated path components, with per-node data and optional destroy / visit functions. More...

Files
file	rdirtree.h
	Path-component-keyed tree with per-node data slots.

Macros
#define	R_DIR_TREE_SEPARATOR   '/'
	Path component separator ('/').
#define	r_dir_tree_ref   r_ref_ref
	Increment the tree's refcount.
#define	r_dir_tree_unref   r_ref_unref
	Decrement the tree's refcount; frees when it reaches zero.
#define	r_dir_tree_get_root(tree)   r_dir_tree_get (tree, NULL, 0)
	Convenience: return the tree's root node.
#define	r_dir_tree_set(tree, path, size, data, notify)    r_dir_tree_set_full (tree, path, size, data, notify, NULL)
	Convenience: r_dir_tree_set_full with no visit function.
#define	r_dir_tree_clear_node(tree, path)   r_dir_tree_set (tree, path, -1, NULL, NULL)
	Convenience: drop the data at path (destroy notifier runs).
#define	r_dir_tree_remove_sub_tree(tree, path, size)    r_dir_tree_remove_node_full (tree, r_dir_tree_get (tree, path, size))
	Convenience: remove the sub-tree rooted at path.
#define	r_dir_tree_remove_all(tree)    r_dir_tree_remove_node_full (tree, r_dir_tree_get_root (tree))
	Convenience: remove every node (the tree itself remains valid).
#define	r_dir_tree_node_set(node, data, notify)   r_dir_tree_node_set_full (node, data, notify, NULL)
	Convenience: r_dir_tree_node_set_full with no visit function.
#define	r_dir_tree_node_clear(node)   r_dir_tree_node_set (node, NULL, NULL)
	Convenience: clear node's data (destroy notifier runs).

Typedefs
typedef struct RDirTree	RDirTree
	Opaque, refcounted directory tree.
typedef struct RDirTreeNode	RDirTreeNode
	Opaque node inside an RDirTree.

Functions
RDirTree *	r_dir_tree_new (void)
	Allocate an empty tree.
rsize	r_dir_tree_node_count (const RDirTree *tree)
	Total number of nodes in tree, including the root.
RDirTreeNode *	r_dir_tree_get (RDirTree *tree, const rchar *path, rssize size)
	Look up the node at path; NULL if the path doesn't exist yet.
RDirTreeNode *	r_dir_tree_get_or_any_parent (RDirTree *tree, const rchar *path, rssize size)
	Look up path; if it doesn't exist, return the deepest existing ancestor.
RDirTreeNode *	r_dir_tree_create (RDirTree *tree, const rchar *path, rssize size)
	Materialise the node at path, creating ancestors as needed; returns the leaf.
RDirTreeNode *	r_dir_tree_set_full (RDirTree *tree, const rchar *path, rssize size, rpointer data, RDestroyNotify notify, RFunc func) R_ATTR_WARN_UNUSED_RESULT
	Create the node at path (if needed) and attach data with the supplied destroy notifier and optional visit function.
void	r_dir_tree_remove_node_full (RDirTree *tree, RDirTreeNode *node)
	Remove node and every descendant; destroy notifiers run.
rpointer	r_dir_tree_node_get (RDirTreeNode *node)
	Read the data pointer attached to node.
rpointer	r_dir_tree_node_set_full (RDirTreeNode *node, rpointer data, RDestroyNotify notify, RFunc func)
	Attach data to node with optional destroy notifier and visit function; returns the previous data pointer.
RFunc	r_dir_tree_node_func (const RDirTreeNode *node)
	Return node's visit function, or NULL.
RDirTreeNode *	r_dir_tree_node_parent (const RDirTreeNode *node)
	Parent of node, or NULL at the root.
const rchar *	r_dir_tree_node_name (const RDirTreeNode *node)
	Last path component of node (no slashes).
rchar *	r_dir_tree_node_path (const RDirTreeNode *node)
	Reconstruct node's full slash-separated path; caller frees with r_free.

Detailed Description

Refcounted tree keyed by slash-separated path components, with per-node data and optional destroy / visit functions.

Useful for any URL-routing / mount-point / configuration overlay scenario where lookups happen by hierarchical path and the caller cares about resolving partial matches (e.g. r_dir_tree_get_or_any_parent for parent-fallback).

Function Documentation

r_dir_tree_get()

RDirTreeNode * r_dir_tree_get	(	RDirTree *	tree,
		const rchar *	path,
		rssize	size
	)

Look up the node at path; NULL if the path doesn't exist yet.

Parameters

tree	The tree.
path	Slash-separated path (or NULL / empty for root).
size	Length of path, or -1 for NUL-terminated.

r_dir_tree_get_or_any_parent()

RDirTreeNode * r_dir_tree_get_or_any_parent	(	RDirTree *	tree,
		const rchar *	path,
		rssize	size
	)

Look up path; if it doesn't exist, return the deepest existing ancestor.

Used for parent-fallback routing patterns.

r_dir_tree_remove_node_full()

void r_dir_tree_remove_node_full	(	RDirTree *	tree,
		RDirTreeNode *	node
	)

Remove node and every descendant; destroy notifiers run.

The node pointer is invalid after this call.

r_dir_tree_set_full()

RDirTreeNode * r_dir_tree_set_full	(	RDirTree *	tree,
		const rchar *	path,
		rssize	size,
		rpointer	data,
		RDestroyNotify	notify,
		RFunc	func
	)

Create the node at path (if needed) and attach data with the supplied destroy notifier and optional visit function.

Parameters

tree	The tree.
path	Slash-separated target path.
size	Length of path, or -1 for NUL-terminated.
data	Data pointer to attach.
notify	Destroy notifier for data, or NULL.
func	Visit function attached to the node; consulted by callers walking the tree, may be NULL.

Returns

The (possibly newly created) leaf node.