A templated class for directed rooted trees. More...

#include <Tree.h>

Collaboration diagram for DRAIN_TREE_NAME< T, EXCLUSIVE, P >:

[legend]

Public Types
typedef drain::DRAIN_TREE_NAME< T, EXCLUSIVE, P >	tree_t

typedef T	node_data_t

typedef P	path_t

typedef path_t::elem_t	key_t

typedef path_t::elem_t	path_elem_t

typedef std::pair< key_t, tree_t >	pair_t

typedef container_t::iterator	iterator

typedef container_t::const_iterator	const_iterator

typedef std::pair< key_t, node_data_t >	node_pair_t
	Experimental. Given pair<elem, data> assigns child[elem] = data;.

Public Member Functions
typedef	DRAIN_TREE_CONTAINER (key_t, tree_t) container_t

	DRAIN_TREE_NAME ()
	Default constructor.

	DRAIN_TREE_NAME (const node_data_t &data)
	Copy constructor; copy only node data at the root.

	DRAIN_TREE_NAME (const DRAIN_TREE_NAME &t)
	Copy constructor; copy only node data at the root.

bool	dataEmpty () const

virtual bool	hasMultipleData () const

virtual const node_data_t &	getData () const

virtual node_data_t &	getData ()

virtual const node_data_t &	getData (const key_t &key) const

virtual node_data_t &	getData (const key_t &key)

container_t::const_iterator	begin () const
	Iterator interface enables for-each type iteration.

container_t::const_iterator	end () const
	Child iterator pointing beyond the last child.

container_t::iterator	begin ()
	Child iterator pointing to the first child.

container_t::iterator	end ()
	Child iterator end.

tree_t &	operator= (const tree_t &t)
	Copies the data of another node. Does not copy the children.

template<class T2 >
tree_t &	operator= (const T2 &v)
	Assigns value to contents.

tree_t &	operator= (const char *str)

template<typename K , typename V >
tree_t &	operator= (std::initializer_list< std::pair< K, V > > l)
	Assign tree structure (of depth one).

tree_t &	operator= (std::initializer_list< std::pair< const char *, const Variable > > l)
	Assign tree structure (of depth one).

template<typename V >
tree_t &	operator= (const std::initializer_list< V > &l)
	Assign data.

tree_t &	operator<< (const node_pair_t &entry)
	Experimental. Given pair(elem, data) assigns child[elem] = data;.

	operator const node_data_t & () const
	Return a reference to node data.

	operator node_data_t & ()
	Return a reference to node data.

template<class K >
tree_t &	operator[] (const K &key)
	NEW 2025 templated child addressing operator.

template<class K >
const tree_t &	operator[] (const K &key) const
	NEW 2025 templated child addressing operator.

tree_t &	operator() (const path_t &path)
	Returns a descendant. Creates one if not existing already.

template<class S >
tree_t &	operator() (const S &arg)
	Returns a descendant. Creates one if not existing already.

tree_t &	operator() (const char *arg)
	Redirects the call to operator()(const std::string & arg) .

const tree_t &	operator() (const path_t &path) const
	Returns a descendant if that exists, else returns an empty node. Otherwise like non-const counterpart.

template<class S >
const tree_t &	operator() (const S &arg) const
	Returns a descendant if that exists, else returns an empty node. Otherwise like non-const counterpart.

const tree_t &	operator() (const char *arg) const
	Redirects the call to operator()(const std::string & arg) .

void	clear ()
	Clear children and node data.

void	clearData ()

void	clearChildren ()
	Clears the children of this node. Does not clear data.

void	erase (const path_t &path)
	Deletes a descendant node and hence its subtrees.

virtual const tree_t &	getEmpty () const

virtual bool	empty () const
	Check if the tree node has empty data and no children.

bool	hasChildren () const

virtual int	hasChildren (const key_t &key) const
	The number of children with name key.

virtual bool	hasChild (const key_t &key) const
	Check if the tree node has a direct descendant with name `key`.

template<typename K >
bool	hasChild (const K &key) const

bool	hasPath (const path_t &path) const

void	initChild (tree_t &) const
	Means for automatically setting something, for example the type of a node.

tree_t &	addChild ()
	Add a child with an automatically generated key (path element).

tree_t &	addChild (const key_t &key)
	Ensure that a child node with given key exists. For MULTIPLE, always add one.

template<typename E >
tree_t &	addChild (const E &key)
	Converts argument to std:string and calls addChild()

tree_t &	prependChild ()
	Push in the front. This is only available for unordered trees.

template<typename E >
tree_t &	prependChild (const E &key)
	Converts argument to std:string and calls addChild()

tree_t &	prependChild (const key_t &key)

tree_t &	operator++ ()
	Shorthand for prependChild().

tree_t &	operator++ (int)
	Shorthand for appendChild().

container_t &	getChildren ()
	Returns the map containing the children.

const container_t &	getChildren () const
	Returns the map containing the children.

const node_data_t *	operator-> () const
	Fast access to data, applied widely in TreeXML (HTML/SVG)

node_data_t *	operator-> ()
	Fast access to data, applied widely in TreeXML (HTML/SVG)

void	swap (tree_t &t)
	Replace children (but no data?)

void	swapData (node_data_t &node)
	User should redefine (implement) this function for applied node types.

Static Public Member Functions
static bool	dataEmpty (const node_data_t &data)
	Default implementation. To be redefined (template-implemented).

static bool	isExclusive ()
	True, if this tree type can either children or node data, but not both.

static bool	isMultiple ()
	True, if this tree type can contain children with a same key (path element).

static bool	isOrdered ()
	True, if the keys of the children of a node are stored in an ordered structure (that is, std::map).s.

static void	generateKey (const tree_t &tree, typename P::elem_t &key)

static const key_t &	getKey (const key_t &key)
	"Default implementation" of key conversion – the identity mapping.

static key_t	getKey (const char *key)
	Conversion of char array to key type (which is never a char array).

template<typename K >
static const key_t &	getKey (const K &key)
	Mapping of keys of external type - for example an enumerated type - to native `key_t` type.

Public Attributes
node_data_t	data
	Contents (data) of the node.

Protected Member Functions
virtual tree_t &	retrieveChild (const key_t &key)

virtual const tree_t &	retrieveChild (const key_t &key) const

bool	hasPath (typename path_t::const_iterator it, typename path_t::const_iterator eit) const
	Checks if there is a node with a given path name.

tree_t &	get (typename path_t::const_iterator it, typename path_t::const_iterator eit)
	Returns a descendant. Creates one, if not present.

const tree_t &	get (typename path_t::const_iterator it, typename path_t::const_iterator eit) const
	Given the descendant pointed to by a given path segment.

Protected Attributes
container_t	children

Static Protected Attributes
static const tree_t	emptyNode

Detailed Description

template<class T, bool EXCLUSIVE = false, class P = drain::Path<std::string,'/'>>
class drain::DRAIN_TREE_NAME< T, EXCLUSIVE, P >

A templated class for directed rooted trees.

This file provides templates of for basic types of trees (directed rooted trees):

OrderedTree – std::map<>
OrderedMultiTree – std::multimap
UnorderedTree – std::list
UnorderedMultiTree – std::list

Template Parameters

T	- node type, containing user-designed data implementing clear(), size() and empty() for future compatibility.
EXCLUSIVE	- node can contains either data or children but not both (JSON-like convention)
P	- applied path structure, like std::list – must implement empty() both for path and keys (path elements)

Data:

The nodes in a tree contain user defined data, the type of which is given as template T.

Currenty, data Concept is requires the following methods:

clear() – resetting the data to default initial (empty) value.
empty() – returning true if the data is empty, or can be identified with empty.

A tree is EXCLUSIVE, if a node contains either data or children. For example, a JSON tree is EXCLUSIVE and an XML tree is not (a tag can containg attributes (data) and inner tages (children).

Further, each type listed above has two variants:

inclusive (implicit, default) – each node may contain data and child nodes.
exclusive – each node may contain data or child nodes, but not both. In the code, both data and children exist as members but in exclusive trees data is automatically cleared if children are added, and inversely, chilren are cleared (removed) if data is assigned.

Limitation: in OrderedTree the children are in a std::map, and threrefore each child of a node has a unique key. In UnorderedTree there may be children having the same key.

Addressing:

tree(path) return a descendant tree[path_element] returns childs only (complains separators, for some time)

Child nodes can be addressed with operator[] with std::string valued keys:

OrderedTree<std::string> tree;
t["first"] = "Hello!";
t["second"] = "Another greeting...";

As the operator[] returns a reference, it may be used recursively:

OrderedTree<std::string> & subTree1 = t["first"]["child"]["grandChild"];

Tree also recognizes a path separator, which is '/' by default. Hence, the node created in the above example could be likewise created or addressed as:

OrderedTree<std::string> & subTree = t("first/child/grandChild"); // equivalent

One may iterate the children directly:

for (auto & entry: tree){
  std::cout << entry.first << ':' << entry.second << '\n';
}

Each node contains data of type T. It may be unused (empty), that is, a node can be used only as a branching point.

OrderedTree<std::string> t;
t.data = "Hello world";
std::string s = t;  // Now contains "Hello world".

(Direct assignments to and from the node data has been supported, but is now disabled for c++ compatibility reasons.)

Also direct referencing of the node data is now disabled:

Tree<std::string> t;
t = "Hello world";
Tree<std::string> &r = t; // Refers to tree.
std::string &s = t;       // Refers to data, "Hello world".

Template Parameters

T	– node data type
EXCLUSIVE	- a node may contain either data or children but not both.

Member Function Documentation

◆ addChild() [1/3]

template<class T , bool EXCLUSIVE = false, class P = drain::Path<std::string,'/'>>

tree_t & addChild ( )

inline

Add a child with an automatically generated key (path element).

For example, specialized methods may generate a key (path element) automatically.

See also: TreeHTML::addChild()

◆ addChild() [2/3]

template<class T , bool EXCLUSIVE = false, class P = drain::Path<std::string,'/'>>

template<typename E >

tree_t & addChild ( const E & key )

inline

Converts argument to std:string and calls addChild()

Template Parameters

E	- class other than std:string

◆ addChild() [3/3]

template<class T , bool EXCLUSIVE = false, class P = drain::Path<std::string,'/'>>

tree_t & addChild ( const key_t & key )

inline

Ensure that a child node with given key exists. For MULTIPLE, always add one.

Behaviour of this function varies as follows:

OrderedTree: return child named key, if exists
UnorderedTree, MULTIPLE: return the first child named key, if exists, else create one.
UnorderedTree, UNIQUE==false: always create a new child named key and return it.

If UNORDERED and not MULTIPLE, reuse existing nodes. If UNORDERED and not MULTIPLE, reuse existing nodes. Behaviour of this function varies as follows:

OrderedTree: create a child, if nonexistent.
UnorderedTree, MULTIPLE: always add a child.
UnorderedTree, not MULTIPLE: create a child, if nonexistent

This implementation, OrderedTree has always unique keys for children.

◆ begin()

template<class T , bool EXCLUSIVE = false, class P = drain::Path<std::string,'/'>>

container_t::const_iterator begin ( ) const

inline

Iterator interface enables for-each type iteration.

for (const auto & entry: tree){ // ... } Child iterator pointing to the first child.

◆ clear()

template<class T , bool EXCLUSIVE = false, class P = drain::Path<std::string,'/'>>

void clear ( )

inline

Clear children and node data.

See also: erase(); clearChildren(); clearData()

◆ clearChildren()

template<class T , bool EXCLUSIVE = false, class P = drain::Path<std::string,'/'>>

void clearChildren ( )

inline

Clears the children of this node. Does not clear data.

See also: clearData(); clear(); erase()

◆ clearData()

template<class T , bool EXCLUSIVE = false, class P = drain::Path<std::string,'/'>>

void clearData ( )

inline

See also: clear(); clearChildren(); erase()

◆ dataEmpty()

template<class T , bool EXCLUSIVE = false, class P = drain::Path<std::string,'/'>>

static bool dataEmpty ( const node_data_t & data )

inlinestatic

Default implementation. To be redefined (template-implemented).

This default applies to many STL types, like string, vector, set and list.

◆ erase()

template<class T , bool EXCLUSIVE = false, class P = drain::Path<std::string,'/'>>

void erase ( const path_t & path )

inline

Deletes a descendant node and hence its subtrees.

As opposite of clear() which focuses on a (current) node, this function refers to a descendant.

See also: clear()

◆ get()

template<class T , bool EXCLUSIVE = false, class P = drain::Path<std::string,'/'>>

const tree_t & get	(	typename path_t::const_iterator	it,
		typename path_t::const_iterator	eit
	)		const

inlineprotected

Given the descendant pointed to by a given path segment.

Returns: – descendant node, or the node itself if the path is empty.

◆ getChildren()

template<class T , bool EXCLUSIVE = false, class P = drain::Path<std::string,'/'>>

container_t & getChildren ( )

inline

Returns the map containing the children.

This is useful for example for map::swap ?

◆ getEmpty()

template<class T , bool EXCLUSIVE = false, class P = drain::Path<std::string,'/'>>

virtual const tree_t & getEmpty ( ) const

inlinevirtual

GENERAL (independent from container type) Empty "default" node; typically initialized with empty data as well.

◆ hasChild()

template<class T , bool EXCLUSIVE = false, class P = drain::Path<std::string,'/'>>

virtual bool hasChild ( const key_t & key ) const

inlinevirtual

Check if the tree node has a direct descendant with name key.

A multiple tree may have more than one children with the same name. With them, consider hasChildren(const key_t &key) .

See also: OrderedMultiTree; UnorderedMultiTree

Returns: – the number of children with name 'key'.

◆ hasChildren()

template<class T , bool EXCLUSIVE = false, class P = drain::Path<std::string,'/'>>

virtual int hasChildren ( const key_t & key ) const

inlinevirtual

The number of children with name key.

Checks how many immediate descendants with name key exist.

A multiple tree may have more than one children with the same name.

See also: OrderedMultiTree, UnorderedMultiTree

With simple trees, use the faster hasChild(const key_t &key).

See also: OrderedTree; UnorderedTree.

Returns: – the number of children with name 'key'.

◆ hasPath()

template<class T , bool EXCLUSIVE = false, class P = drain::Path<std::string,'/'>>

bool hasPath	(	typename path_t::const_iterator	it,
		typename path_t::const_iterator	eit
	)		const

inlineprotected

Checks if there is a node with a given path name.

Could be called hasDescendant; hence is like hasChild() but calls children recursively.

Parameters

eit - end()

◆ initChild()

template<class T , bool EXCLUSIVE = false, class P = drain::Path<std::string,'/'>>

void initChild ( tree_t & ) const

inline

Means for automatically setting something, for example the type of a node.

For example the default type of a node can be set based on the type of the host node.

See also: TreeHTML::initChild()

Future option: also key (of type const key_t &) is considered

◆ isExclusive()

template<class T , bool EXCLUSIVE = false, class P = drain::Path<std::string,'/'>>

static bool isExclusive ( )

inlinestatic

True, if this tree type can either children or node data, but not both.

A JSON structure is implemented as an EXCLUSIVE tree: a node contains either a subtree or a value (FlexibleMap).

See also: TreeExamples

◆ operator node_data_t &()

template<class T , bool EXCLUSIVE = false, class P = drain::Path<std::string,'/'>>

operator node_data_t & ( )

inline

Return a reference to node data.

Handy in functions of type fct(N & node) .

◆ operator()() [1/4]

template<class T , bool EXCLUSIVE = false, class P = drain::Path<std::string,'/'>>

tree_t & operator() ( const char * arg )

inline

Redirects the call to operator()(const std::string & arg) .

Parameters

arg	- by default, the path from the current node to the child node.

◆ operator()() [2/4]

template<class T , bool EXCLUSIVE = false, class P = drain::Path<std::string,'/'>>

tree_t & operator() ( const path_t & path )

inline

Returns a descendant. Creates one if not existing already.

Parameters

path	- the path from the current node to the child node.

This function, using native path_t type, should be reserved for this semantic by not redefining (specialising) this function in template classes.

◆ operator()() [3/4]

template<class T , bool EXCLUSIVE = false, class P = drain::Path<std::string,'/'>>

const tree_t & operator() ( const path_t & path ) const

inline

Returns a descendant if that exists, else returns an empty node. Otherwise like non-const counterpart.

Parameters

path	- the path from the current node to the child node.

This function, using native path_t type, should be reserved for this semantic by not redefining (specialising) this function in template classes.

◆ operator()() [4/4]

template<class T , bool EXCLUSIVE = false, class P = drain::Path<std::string,'/'>>

template<class S >

tree_t & operator() ( const S & arg )

inline

Returns a descendant. Creates one if not existing already.

Parameters

arg	- the path from the current node to the child node.

This function, not using native path_t type, can be redefined in template classes. For example, an important attribute can be set using this method.

However, operator()(const char *arg) should be redefined to produce equivalent result with const string &arg.

◆ operator=() [1/5]

template<class T , bool EXCLUSIVE = false, class P = drain::Path<std::string,'/'>>

template<typename V >

tree_t & operator= ( const std::initializer_list< V > & l )

inline

Assign data.

If initializer list elements are not pairs, assign it to node data.

2025/01 experimental.

◆ operator=() [2/5]

template<class T , bool EXCLUSIVE = false, class P = drain::Path<std::string,'/'>>

template<class T2 >

tree_t & operator= ( const T2 & v )

inline

Assigns value to contents.

Assigns a value to contents. This may be redefined in derived classes. For example, assigning a value of certain class may cause adding a specific child element instead of assigning to data (the default, here).

◆ operator=() [3/5]

template<class T , bool EXCLUSIVE = false, class P = drain::Path<std::string,'/'>>

tree_t & operator= ( const tree_t & t )

inline

Copies the data of another node. Does not copy the children.

Default use to reset a node (re-initialize its data).

◆ operator=() [4/5]

template<class T , bool EXCLUSIVE = false, class P = drain::Path<std::string,'/'>>

tree_t & operator= ( std::initializer_list< std::pair< const char *, const Variable > > l )

inline

Assign tree structure (of depth one).

Default implementation: assign new nodes (children).

Examples of overriding:

TreeXML::operator=()
TreeSVG::operator=()

◆ operator=() [5/5]

template<class T , bool EXCLUSIVE = false, class P = drain::Path<std::string,'/'>>

template<typename K , typename V >

tree_t & operator= ( std::initializer_list< std::pair< K, V > > l )

inline

Assign tree structure (of depth one).

Default implementation: assign new nodes (children).

◆ operator[]()

template<class T , bool EXCLUSIVE = false, class P = drain::Path<std::string,'/'>>

template<class K >

tree_t & operator[] ( const K & key )

inline

NEW 2025 templated child addressing operator.

Allows using EnumDict enums as keys, for example.

◆ prependChild()

template<class T , bool EXCLUSIVE = false, class P = drain::Path<std::string,'/'>>

template<typename E >

tree_t & prependChild ( const E & key )

inline

Converts argument to std:string and calls addChild()

Template Parameters

E	- class other than std:string

The documentation for this class was generated from the following file:

src/drain/util/Tree.h

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Member Function Documentation

◆ addChild() [1/3]

◆ addChild() [2/3]

◆ addChild() [3/3]

◆ begin()

◆ clear()

◆ clearChildren()

◆ clearData()

◆ dataEmpty()

◆ erase()

◆ get()

◆ getChildren()

◆ getEmpty()

◆ hasChild()

◆ hasChildren()

◆ hasPath()

◆ initChild()

◆ isExclusive()

◆ operator node_data_t &()

◆ operator()() [1/4]

◆ operator()() [2/4]

◆ operator()() [3/4]

◆ operator()() [4/4]

◆ operator=() [1/5]

◆ operator=() [2/5]

◆ operator=() [3/5]

◆ operator=() [4/5]

◆ operator=() [5/5]

◆ operator[]()

◆ prependChild()