#include <stringtree.hpp>

Inheritance diagram for StringTree< T, TNodeMaintainer, TRecycling >::NodePtr:

Collaboration diagram for StringTree< T, TNodeMaintainer, TRecycling >::NodePtr:

Class Description

template<typename T, typename TNodeMaintainer = StringTreeNamesDynamic<character>, typename TRecycling = Recycling::Private>
class aworx::lib::monomem::StringTree< T, TNodeMaintainer, TRecycling >::NodePtr

This public, inner class provides the main interface into outer class StringTree. The class should be considered being similar to a simple pointer or to a lightweight iterator type, which refers to a tree and a current node.
The class's interface allows the access to a node's name and value and to to insert and remove child nodes.

Instances of this class can be received with methods StringTree::Root and StringTree::RecursiveIterator::Node.

The default constructor creates an invalid object, which has to be initialized by assigning a valid object prior to its first use.

See also: For more information on how this class is used, see paragraph 2.1 Inner Class NodePtr of the description of class StringTree.

Friends

class StringTree

Definition at line 568 of file stringtree.hpp.

Public Methods
	NodePtr () noexcept=default

	NodePtr (const NodePtr &) noexcept=default

	NodePtr (NodePtr &&) noexcept=default

	~NodePtr () noexcept=default

AString &	AssemblePath (AString &target, CurrentData targetData=CurrentData::Clear) const

NodePtr	Child (const NameType &name)

NodePtr	Clone () const

uinteger	CountChildren () const

template<bool TCheck = true, typename... TArgs>
NodePtr	CreateChild (const NameType &childName, TArgs &&... args) const

template<typename... TArgs>
std::pair< NodePtr, bool >	CreateChildIfNotExistent (const NameType &name, TArgs &&... args)

template<typename... TArgs>
std::pair< NodePtr, integer >	CreatePathIfNotExistent (const NameType &path, TArgs &&... args)

uinteger	Delete ()

bool	DeleteChild (const NameType &childName) const

void	DeleteChild (NodePtr &child) const

uinteger	DeleteChildren () const

int	Depth () const

NodePtr	FirstChild () const

bool	GoToChild (const NameType &name)

template<typename... TArgs>
bool	GoToCreateChildIfNotExistent (const NameType &name, TArgs &&... args)

template<typename... TArgs>
integer	GoToCreatedPathIfNotExistent (const NameType &path, TArgs &&... args)

bool	GoToFirstChild ()

bool	GoToLastChild ()

bool	GoToNextSibling ()

NodePtr &	GoToParent ()

bool	GoToPreviousSibling ()

NodePtr	GoToRoot ()

SubstringType	GoToTraversedPath (const NameType &path)

bool	HasChildren () const

bool	HasNextSibling () const

bool	HasPreviousSibling () const

bool	IsInvalid () const

bool	IsRoot () const

bool	IsValid () const

NodePtr	LastChild () const

const NameType &	Name () const

NodePtr	NextSibling () const

bool	operator!= (const NodePtr &other) const

NodePtr &	operator= (const NodePtr &) noexcept=default

NodePtr &	operator= (NodePtr &&) noexcept=default

bool	operator== (const NodePtr &other) const

NodePtr	Parent () const

NodePtr	PreviousSibling () const

NodePtr	Root () const

std::pair< NodePtr, SubstringType >	TraversePath (const NameType &path)

StringTree &	Tree ()

T &	Value ()

const T &	Value () const

Protected Methods
	NodePtr (basetree pTree, baseNode pNode) noexcept

Constructor & Destructor Documentation

◆ NodePtr() [1/4]

NodePtr	(	basetree *	pTree,
		baseNode *	pNode
	)

inlineprotectednoexcept

Internal constructor

Parameters

pTree	The StringTree we work on.
pNode	The node to refer to.

Definition at line 582 of file stringtree.hpp.

◆ NodePtr() [2/4]

NodePtr ( )

defaultnoexcept

Public constructor. Creates a node pointer which is not valid. The only way to make a default-constructed instance valid is by (copy-) assigning another instance.

◆ NodePtr() [3/4]

NodePtr ( const NodePtr & )

defaultnoexcept

Trivial default copy constructor.

◆ NodePtr() [4/4]

NodePtr ( NodePtr && )

defaultnoexcept

Trivial default move constructor.

◆ ~NodePtr()

~NodePtr ( )

defaultnoexcept

Trivial default destructor.

Member Function Documentation

◆ AssemblePath()

AString& AssemblePath	(	AString &	target,
		CurrentData	targetData = `CurrentData::Clear`
	)		const

inline

Writes the path to the represented node (excluding the represented node's name) to the given AString.
If this node represents the root node, then nothing is written.
No separation character is prepended to the start and appended to the end of the resulting path.

Note that this method is rather inefficient, as the list of parent nodes have to be inserted to the beginning of the string in an iteration loop, which implies a string copy per parent node. In many situations, it is recommended to search for other ways to keep track of the current path of a node. Class StringTree::RecursiveIterator for example, optionally allows to maintain a string representing the current path with every iteration.

Parameters

target	The target to append the path to.
targetData	Denotes whether target should be cleared prior to appending the path. Defaults to CurrentData::Clear.

Returns: The given AString to allow concatenated operations on it.

Definition at line 1219 of file stringtree.hpp.

Here is the call graph for this function:

◆ Child()

NodePtr Child ( const NameType & name )

inline

Searches a child with the given name and returns a node pointer to it. If no child with this name exists, the returned node pointer is invalid

The given name is not considered a path and is not checked for being "." or ".." or if it contains a separator character. Children with such name can not exist and hence can't be found. However, in debug builds, an ALIB_WARNING is reported.

Parameters

name	The name of the child to search.

Returns: A node pointer representing the last child of the node represented by this node pointer.

Definition at line 864 of file stringtree.hpp.

Here is the call graph for this function:

◆ Clone()

NodePtr Clone ( ) const

inline

Creates a node pointer value representing the same node like this pointer.

Returns: A clone of this node pointer.

Definition at line 666 of file stringtree.hpp.

Here is the call graph for this function:

◆ CountChildren()

uinteger CountChildren ( ) const

inline

Returns the number of direct children of the represented node.
Note that this method runs in constant time.

Returns: The number of direct children of the represented node.

Definition at line 1167 of file stringtree.hpp.

Here is the call graph for this function:

◆ CreateChild()

NodePtr CreateChild	(	const NameType &	childName,
		TArgs &&...	args
	)		const

inline

Creates and returns a child node. If a node already exists, nothing is done and nullptr is returned as this is considered an error.

If the child name is illegal (equal to "." or ".." or contains a separation character), an ALib warning is raised and an invalid node pointer is returned.

Template parameter TCheck may be used to suppress the search for an existing child with the same name, as well as the check for correctness of the given child name. This tremendously improves the execution performance of this method.

Attention: Setting template parameter TCheck to false and inserting child nodes with the same name, sets a StringTree to an undefined state.

Template Parameters

TCheck	If `false`, no check for an existing child with the same name is performed.
TArgs	Types of variadic parameters given with parameter args.

Parameters

childName	The name of the child
args	Variadic parameters to be forwarded to constructor of custom type T of the child created.

Returns: A new node pointer object representing the created child node. If the given childName was invalid or the child existed already, the returned object is invalid.

Definition at line 1258 of file stringtree.hpp.

Here is the call graph for this function:

◆ CreateChildIfNotExistent()

std::pair<NodePtr, bool> CreateChildIfNotExistent	(	const NameType &	name,
		TArgs &&...	args
	)

inline

Moves this node pointer to the child with given name. If no child with this name exists, one will be created.

If the given childName is invalid (equals to "." or ".." or contains the separation character), then still true is returned, but this node pointer becomes invalid. In addition, with debug builds, an ALIB_WARNING is reported.

Template Parameters

TArgs Types of variadic parameters given with parameter args.

Parameters

name	The name of the desired child.
args	Variadic parameters to be forwarded to constructor of custom type T in the case a child is created.

Returns: A pair of a node pointer pointing to the child and a boolean that equals false if the child was found, and true if a child was created. If the given name was invalid, the returned node pointer will be invalid while the boolean still indicates "not found" (aka true).

Definition at line 919 of file stringtree.hpp.

Here is the call graph for this function:

◆ CreatePathIfNotExistent()

std::pair<NodePtr, integer> CreatePathIfNotExistent	(	const NameType &	path,
		TArgs &&...	args
	)

inline

Follows the given path and creates non-existing children along the way.

Child names "." and ".." are allowed and respected same as documented with method TraversePath.

New child nodes are constructed by forwarding the given args. Existing children remain untouched.

Template Parameters

TArgs Types of variadic parameters given with parameter args.

Parameters

path	The path to move along.
args	Variadic parameters to be forwarded to constructor of each node that is created.

Returns: A std::pair containing a resulting NodePtr and the number of nodes created.

Definition at line 1046 of file stringtree.hpp.

Here is the call graph for this function:

◆ Delete()

uinteger Delete ( )

inline

Deletes the branch that this node pointer refers to from the tree. If this node pointer does not represent the root node, then after the operation, it refers to the parent of the current node.
If the represented node is the root node, only the children are deleted and this object remains representing the root node.

Note: If this method is invoked on an object returned by method RecursiveIterator::Node, the invoking iterator becomes invalid.
To avoid this, method RecursiveIterator::DeleteNode is to be used.

Returns: The total number of nodes deleted. Can be zero, in case this object represents the root node and this node has no children.

Definition at line 1378 of file stringtree.hpp.

Here is the call graph for this function:

◆ DeleteChild() [1/2]

bool DeleteChild ( const NameType & childName ) const

inline

Searches and deletes the child named childName from the node that this object refers to. This object itself is not changed.

See also: Overloaded version of this method that accepts a node pointer referring to the child in question.

Parameters

childName The name of the desired child.

Returns: true if the child existed and was deleted, false otherwise.

Definition at line 1300 of file stringtree.hpp.

Here is the call graph for this function:

◆ DeleteChild() [2/2]

void DeleteChild ( NodePtr & child ) const

inline

Deletes the child represented by the given node pointer child from the node that this node pointer refers to. After the invocation the given child refers to its next sibling. If no such sibling exists, child becomes invalid. This node pointer itself is not changed.

Note: This method is handy to implement forward iterations through children of a parent node with the aim to delete certain child nodes. No corresponding version of this method exists that moves the given child pointer to its previous sibling. For reverse iterations, a clone of the child argument has to be passed. However, any overhead caused by such temporary object creation will be optimized out by modern C++ compilers.

Parameters

child Deletes the child represented by the given node.

Definition at line 1337 of file stringtree.hpp.

Here is the call graph for this function:

◆ DeleteChildren()

uinteger DeleteChildren ( ) const

inline

Deletes the children of the node that this node pointer refers to. This object itself is not changed.

Returns: The number of children that were deleted.

Definition at line 1354 of file stringtree.hpp.

Here is the call graph for this function:

◆ Depth()

int Depth ( ) const

inline

Determines the depth of the node represented by this object. This is done by counting the iterations needed to reach the root node of the tree.

Returns: The distance from this node to the root node.

Definition at line 1146 of file stringtree.hpp.

Here is the call graph for this function:

◆ FirstChild()

NodePtr FirstChild ( ) const

inline

Returns a node pointer value that represents the first child of the node represented. If the represented node has no children, an invalid node pointer is returned.

Returns: A node pointer representing the first child of the node represented by this node pointer.

Definition at line 796 of file stringtree.hpp.

Here is the call graph for this function:

◆ GoToChild()

bool GoToChild ( const NameType & name )

inline

Searches a child with the given name and moves this node pointer to it. If no child with this name exists, the node pointer does not change and false is returned.

The given name is not considered a path and is not checked for being "." or ".." or if it contains a separator character. Children with such name can not exist and hence can't be found. However, in debug builds, an ALIB_WARNING is reported.

Parameters

name	The name of the child to search.

Returns: true if the child existed and this object changed, false otherwise.

Definition at line 886 of file stringtree.hpp.

Here is the call graph for this function:

◆ GoToCreateChildIfNotExistent()

bool GoToCreateChildIfNotExistent	(	const NameType &	name,
		TArgs &&...	args
	)

inline

Moves this node pointer to the child with given name. If no child with this name exists, one will be created.

If the given childName is invalid (equals to "." or ".." or contains the separation character), then still true is returned, but this node pointer becomes invalid. In addition, with debug builds, an ALIB_WARNING is reported.

Template Parameters

TArgs Types of variadic parameters given with parameter args.

Parameters

name	The name of the desired child.
args	Variadic parameters to be forwarded to constructor of custom type T in the case a child is created.

Returns: false if the child was found, and true if one was created or the given child name was invalid.

Definition at line 950 of file stringtree.hpp.

Here is the call graph for this function:

◆ GoToCreatedPathIfNotExistent()

integer GoToCreatedPathIfNotExistent	(	const NameType &	path,
		TArgs &&...	args
	)

inline

Follows the given path and creates non-existing children along the way.

Child names "." and ".." are allowed and respected same as in TraversePath.

New child nodes are constructed by forwarding the given args. Existing children remain untouched.

Template Parameters

TArgs Types of variadic parameters given with parameter args.

Parameters

path	The path to move along.
args	Variadic parameters to be forwarded to constructor of each node that is created.

Returns: The number of nodes created.

Definition at line 1074 of file stringtree.hpp.

Here is the call graph for this function:

◆ GoToFirstChild()

bool GoToFirstChild ( )

inline

Moves this node pointer to the first child of its represented node. If the represented node has no children, this node pointer becomes invalid.

Returns: true if the node pointer was moved, false if the represented node has no children.

Definition at line 809 of file stringtree.hpp.

Here is the call graph for this function:

◆ GoToLastChild()

bool GoToLastChild ( )

inline

Moves this node pointer to the last child of its represented node. If the represented node has no children, this node pointer becomes invalid.

Returns: true if the node pointer was moved, false if the represented node has no children.

Definition at line 840 of file stringtree.hpp.

Here is the call graph for this function:

◆ GoToNextSibling()

bool GoToNextSibling ( )

inline

Moves this node pointer to the next sibling of the represented node. If the node has no next sibling, this node pointer becomes invalid. The latter is always true if this is the root node of the tree.

Returns: true if this node pointer was moved, false if the represented node has no next sibling.

Definition at line 743 of file stringtree.hpp.

Here is the call graph for this function:

◆ GoToParent()

NodePtr& GoToParent ( )

inline

Moves this node pointer to its parent node. If this is the root node, this object becomes invalid.

Returns: *this to allow concatenated calls

Definition at line 715 of file stringtree.hpp.

Here is the call graph for this function:

◆ GoToPreviousSibling()

bool GoToPreviousSibling ( )

inline

Moves this node pointer to the previous sibling of the represented node. If the node has no previous sibling, this node pointer becomes invalid. The latter is always true if this is the root node of the tree.

Returns: true if this node pointer was moved, false if the represented node has no previous sibling.

Definition at line 777 of file stringtree.hpp.

Here is the call graph for this function:

◆ GoToRoot()

NodePtr GoToRoot ( )

inline

Returns a node pointer to the root node of the tree.

Returns: A node pointer representing the root node of the tree this pointer represents.

Definition at line 688 of file stringtree.hpp.

◆ GoToTraversedPath()

SubstringType GoToTraversedPath ( const NameType & path )

inline

Same as TraversePath, but moves this node pointer instead of returning one.

Parameters

path	The path to move this node pointer along.

Returns: The unconsumed portion of the path. An empty Substring if the path existed.

Definition at line 1021 of file stringtree.hpp.

Here is the call graph for this function:

◆ HasChildren()

bool HasChildren ( ) const

inline

Returns true if the represented node has at least one direct child.

Returns: true if the current node has children, false otherwise.

Definition at line 1156 of file stringtree.hpp.

Here is the call graph for this function:

◆ HasNextSibling()

bool HasNextSibling ( ) const

inline

Evaluates if the node represented by this object has a next sibling in its parent's list of children.

Returns: true if a next sibling to this object's represented node exists, false otherwise.

Definition at line 1179 of file stringtree.hpp.

Here is the call graph for this function:

◆ HasPreviousSibling()

bool HasPreviousSibling ( ) const

inline

Evaluates if the node represented by this object has a previous sibling in its parent's list of children.

Returns: true if a previous sibling to this object's represented node exists, false otherwise.

Definition at line 1192 of file stringtree.hpp.

Here is the call graph for this function:

◆ IsInvalid()

bool IsInvalid ( ) const

inline

Returns the opposite of IsValid.

Returns: true if this is an invalid node pointer that must not be used, false otherwise.

Definition at line 656 of file stringtree.hpp.

Here is the call graph for this function:

◆ IsRoot()

bool IsRoot ( ) const

inline

Returns true if this node pointer represents the root node of the StringTree, false otherwise.

Returns: true if this object represents the root node, false otherwise.

Definition at line 1135 of file stringtree.hpp.

Here is the call graph for this function:

◆ IsValid()

bool IsValid ( ) const

inline

Determines if this is a valid object. Node pointers may become invalid with transition methods like GoToParent, GoToFirstChild or GoToNextSibling. An invalid object may be turned into a valid one by either

assigning a valid object (copy assignment), or
invoking method GoToRoot, or
invoking method GoToTraversedPath using absolute path addressing.

Note that the latter is not applicable to a default-constructed objects (which are also invalid) as with such no StringTree is assigned.

Returns: true if this is a valid node pointer. If invalid, false is returned and this object must not be used.

Definition at line 645 of file stringtree.hpp.

◆ LastChild()

NodePtr LastChild ( ) const

inline

Returns a node pointer value that represents the last child of the node represented. If the represented node has no children, an invalid node pointer is returned.

Returns: A node pointer representing the last child of the node represented by this node pointer.

Definition at line 828 of file stringtree.hpp.

Here is the call graph for this function:

◆ Name()

const NameType& Name ( ) const

inline

Returns the name of the represented node. Note that the concatenated names of recursive child nodes, separated by TSeparator constitute a path.

Returns: A constant reference to the name of the represented node.

Definition at line 1094 of file stringtree.hpp.

Here is the call graph for this function:

◆ NextSibling()

NodePtr NextSibling ( ) const

inline

Returns a node pointer value that represents the next sibling of the node represented this node pointer. If the node has no next sibling, an invalid node pointer is returned.

Returns: A node pointer object representing the next sibling of the node represented by this object.

Definition at line 730 of file stringtree.hpp.

Here is the call graph for this function:

◆ operator!=()

bool operator!= ( const NodePtr & other ) const

inline

Comparison operator.

Parameters

other The object to compare ourselves to.

Returns: false if this and given node pointer are equal, true otherwise.

Definition at line 626 of file stringtree.hpp.

◆ operator=() [1/2]

NodePtr& operator= ( const NodePtr & )

defaultnoexcept

Trivial default copy assign operator.

Returns: A reference to this.

◆ operator=() [2/2]

NodePtr& operator= ( NodePtr && )

defaultnoexcept

Trivial default move assign operator.

Returns: A reference to this.

◆ operator==()

bool operator== ( const NodePtr & other ) const

inline

Comparison operator.

Parameters

other The object to compare ourselves to.

Returns: true if this and given node pointer are equal, false otherwise.

Definition at line 617 of file stringtree.hpp.

◆ Parent()

NodePtr Parent ( ) const

inline

Creates a node pointer value representing the parent node of the node represented by this object.

If this object represents the root node of the tree, the returned node pointer is invalid.

Returns: A node pointer representing the parent node of the node represented by this node pointer.

Definition at line 703 of file stringtree.hpp.

Here is the call graph for this function:

◆ PreviousSibling()

NodePtr PreviousSibling ( ) const

inline

Returns a node pointer value that represents the previous sibling of the node represented this node pointer. If the node has no previous sibling, an invalid node pointer is returned.

Returns: A node pointer object representing the previous sibling of the node represented by this object.

Definition at line 762 of file stringtree.hpp.

Here is the call graph for this function:

◆ Root()

NodePtr Root ( ) const

inline

Returns a node pointer to the root node of the tree.

Returns: A node pointer representing the root node of the tree this pointer represents.

Definition at line 677 of file stringtree.hpp.

Here is the call graph for this function:

◆ TraversePath()

std::pair<NodePtr, SubstringType> TraversePath ( const NameType & path )

inline

Follows the given path from the currently represented node to the target node.

The method supports absolute and relative path addressing: If path begins with a separation character, then the transition starts with the root node of the StringTree. Furthermore, child name "." is ignored and just skipped while a name of ".." addresses the parent node during the transition. Repeated separation characters are ignored.
If, while processing the path string, the root node is found an the next path element is "..", this element is ignored and processing continues. As a sample, assuming that nodes /a and /b exist, the paths:

 /a/../b

and

 /a/../../b

both evaluate to

/b

Relative paths must not be used on invalid node pointers. Doing so is undefined behavior and raises an ALib assertion in debug-compilations.

If a child along the path does not exist, the traversal is ended and the remaining portion of the path is returned.

Note: If parameter path is a temporary object, the resulting Substring must not be used, as it refers to the given string's buffer. In any case, its length can still be compared to 0 to evaluate success of the traversal.

Parameters

path	The path to follow, starting with the node this pointer represents.

Returns: A pair of a node pointer pointing to last child not of the existing portion of the given path, and a substring that contains the non-existing portion of a path, or is empty if the complete path existed.

Definition at line 1006 of file stringtree.hpp.

Here is the call graph for this function:

◆ Tree()

StringTree& Tree ( )

inline

Returns the three that this pointer is created of.

Returns: The tree that this object refers to.

Definition at line 1105 of file stringtree.hpp.

◆ Value() [1/2]

T& Value ( )

inline

Retrieves a reference to the templated value of type T stored in the represented node.

Returns: The current node's value.

Definition at line 1115 of file stringtree.hpp.

Here is the call graph for this function:

◆ Value() [2/2]

const T& Value ( ) const

inline

Retrieves a constant reference to the templated value of type T stored in the represented node.

Returns: The current node's value.

Definition at line 1124 of file stringtree.hpp.

Here is the call graph for this function:

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

stringtree.hpp

Class Description

template<typename T, typename TNodeMaintainer = StringTreeNamesDynamic<character>, typename TRecycling = Recycling::Private> class aworx::lib::monomem::StringTree< T, TNodeMaintainer, TRecycling >::NodePtr

Friends

Public Methods

Protected Methods

Constructor & Destructor Documentation

◆ NodePtr() [1/4]

◆ NodePtr() [2/4]

◆ NodePtr() [3/4]

◆ NodePtr() [4/4]

◆ ~NodePtr()

Member Function Documentation

◆ AssemblePath()

◆ Child()

◆ Clone()

◆ CountChildren()

◆ CreateChild()

◆ CreateChildIfNotExistent()

◆ CreatePathIfNotExistent()

◆ Delete()

◆ DeleteChild() [1/2]

◆ DeleteChild() [2/2]

◆ DeleteChildren()

◆ Depth()

◆ FirstChild()

◆ GoToChild()

◆ GoToCreateChildIfNotExistent()

◆ GoToCreatedPathIfNotExistent()

◆ GoToFirstChild()

◆ GoToLastChild()

◆ GoToNextSibling()

◆ GoToParent()

◆ GoToPreviousSibling()

◆ GoToRoot()

◆ GoToTraversedPath()

◆ HasChildren()

◆ HasNextSibling()

◆ HasPreviousSibling()

◆ IsInvalid()

◆ IsRoot()

◆ IsValid()

◆ LastChild()

◆ Name()

◆ NextSibling()

◆ operator!=()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ Parent()

◆ PreviousSibling()

◆ Root()

◆ TraversePath()

◆ Tree()

◆ Value() [1/2]

◆ Value() [2/2]

template<typename T, typename TNodeMaintainer = StringTreeNamesDynamic<character>, typename TRecycling = Recycling::Private>
class aworx::lib::monomem::StringTree< T, TNodeMaintainer, TRecycling >::NodePtr