#include <stringtree.hpp>

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

Class Description

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

This public, inner class can be used to recursively iterate through the nodes of outer class StringTree.
The type does not apply to the concept of std::iterator_traits. The rationale for this is the fact that mechanics for sorting the child nodes are provided, which requires allocation of more resources than usual container iterators do. Therefore, objects of this type are not supposed to be temporary and created "on the fly", e.g. in range based loops introduced with C++ 11 . Instead, instances should rather be created once and then re-used with subsequent iterations.

The sorting of child nodes is optional and can be changed prior to each recursion. A built-in comparison function which works on node names (path names) allows to choose ascending and descending order and to ignore or be sensitive about letter case. Besides this, custom comparison functions that take a combination of arbitrary node attributes, including a node's value of template type T can be established. See overloaded methods SetSorting for details on this topic.

Objects of this type can be initialized, respectively reset to distinct start nodes by providing objects of

type StringTree,
type StringTree::NodePtr or
other objects of this type itself,

to overloaded methods Initialize.

The maximum depth of recursion may be limited with optional parameter depth found with each overloaded version of Initialize. During the iteration, the recursion can be individually selected per node visited. This is done by using either of methods Next or NextSibling to proceed. Furthermore, method NextParentSibling allows to skip the rest of the current iteration branch.
The end of an iteration is detected with method IsValid.

The children of a node can be iterated in a sorted fashion. To enable and disable sorting, various overloads of SetSorting exist. These methods may be invoked any time during the iteration. Whenever a recursion in iteration occurs, the most recent settings of sorting are respected for the list of children of the node that is processed with that recursion.

Finally, the generation of a string representing the actual path to the current iteration node, relative to the iteration's start node can be activated. See method SetPathGeneration for more information about this feature.

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

Friends

class StringTree

Definition at line 1443 of file stringtree.hpp.

Inner Classes
struct	RecursionData

Public Methods
	RecursiveIterator ()=default

	RecursiveIterator (const RecursiveIterator &)=default

	RecursiveIterator (RecursiveIterator &&)=default

	~RecursiveIterator ()=default

int	CurrentDepth () const

const NameType &	CurrentPath () const

uinteger	DeleteNode ()

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

void	Initialize (const RecursiveIterator &other, unsigned int depth=(std::numeric_limits< unsigned int >::max)())

void	Initialize (NodePtr nodePtr, unsigned int depth=(std::numeric_limits< unsigned int >::max)())

void	Initialize (StringTree &pTree, unsigned int depth=(std::numeric_limits< unsigned int >::max)())

void	Invalidate ()

bool	IsInvalid () const

bool	IsValid () const

bool	Next ()

bool	NextParentSibling ()

bool	NextSibling ()

NodePtr	Node () const

RecursiveIterator &	operator= (const RecursiveIterator &)=default

RecursiveIterator &	operator= (RecursiveIterator &&)=default

int	RequestedDepth () const

void	SetPathGeneration (Switch pathGeneration)

void	SetSorting (bool(*customSorterFunction)(const NodePtr &, const NodePtr &))

void	SetSorting (SortOrder order=SortOrder::Ascending, Case sensitivity=Case::Ignore)

void	SetSorting (Switch sorting)

Protected Fields
size_t	actDepth = static_cast<size_t >(-1)

AString	actPath

bool(*	nextCustomSorter )(const NodePtr &, const NodePtr &) = nullptr

bool	nextIsSorting = false

bool	nextSortingIsCaseSensitive = false

bool	nextSortingIsDescending = false

baseNode *	node

unsigned int	recursionDepth =(std::numeric_limits<unsigned int>::max)()

std::vector< RecursionData >	stack

StringTree *	tree = nullptr

Protected Methods
void	initialize (StringTree pTree, baseNode newnode, unsigned int depth)

bool	next (int skipMode)

void	recursion ()

Constructor & Destructor Documentation

◆ RecursiveIterator() [1/3]

RecursiveIterator ( )

default

Default constructor.

◆ RecursiveIterator() [2/3]

RecursiveIterator ( const RecursiveIterator & )

default

Trivial copy constructor.

◆ RecursiveIterator() [3/3]

RecursiveIterator ( RecursiveIterator && )

default

Trivial default move constructor.

◆ ~RecursiveIterator()

~RecursiveIterator ( )

default

Destructor.

Member Function Documentation

◆ CurrentDepth()

int CurrentDepth ( ) const

inline

Returns the depth of the current iteration. This is value is available to the algorithm which means this method executes in constant time.

To get the absolute depth of the current node, method StringTree::NodePtr::Depth may be used.

Returns: The distance of the current node and the node of the start of the iteration.

Definition at line 1886 of file stringtree.hpp.

Here is the call graph for this function:

◆ CurrentPath()

const NameType& CurrentPath ( ) const

inline

Retrieves the current path of walking as a string representation. The path returned is relative to the start node and does not contain a leading separator character. Also, it does not contain the name of the current node, which can be received by invoking method Name on the node pointer returned by method Node.

Note that this method can be used only if path generation was activated prior to the current iteration. Activation is performed with method SetPathGeneration.

Returns: The path of the current node.

Definition at line 1825 of file stringtree.hpp.

Here is the call graph for this function:

◆ DeleteNode()

uinteger DeleteNode ( )

inline

Deletes the node that this iterator currently refers to from the tree. After the operation, the iterator is moved forward to the next sibling of the current node, respectively of the first sibling found in the recursion stack.

Note: This method constitutes a legal alternative to method NodePtr::Delete, which is forbidden to be invoked on the node returned by method Node as this would invalidate this iterator.

Methods NodePtr::DeleteChild and NodePtr::DeleteChildren are allowed with this iterator type. Consequently, no replacement method for those is given with this class.

Returns: The total number of nodes deleted.

Definition at line 1937 of file stringtree.hpp.

Here is the call graph for this function:

◆ FullPath()

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

inline

Writes the results of CurrentPath and Name, separated by the separator character TSeparator.

Note that this method can be used only if path generation was activated prior to the current iteration. Activation is performed with method SetPathGeneration.

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 string to allow concatenated operations

Definition at line 1846 of file stringtree.hpp.

Here is the call graph for this function:

◆ Initialize() [1/3]

void Initialize	(	const RecursiveIterator &	other,
		unsigned int	depth = `(std::numeric_limits<unsigned int>::max)()`
	)

inline

Resets this iterator to the first child of the node that the given other iterator currently refers to. The given iterator has to be in a valid state. Optionally, a recursion depth can be set.

Parameters

other	The iterator whose current node becomes the start node for this iterator.
depth	Sets the recursion depth. A depth of `0` iterates only the direct children of the node represented by other. Defaults to `std::numeric_limits<unsigned int>::max()` for "unlimited" recursion.

Definition at line 1670 of file stringtree.hpp.

Here is the call graph for this function:

◆ Initialize() [2/3]

void Initialize	(	NodePtr	nodePtr,
		unsigned int	depth = `(std::numeric_limits<unsigned int>::max)()`
	)

inline

Resets this iterator to the first child of the node that the given node pointer object represents. If the node pointer is invalid, the root node of the tree it represents is used.

If the given node has no children, this iterator is marked invalid when this method returns.

Optional parameter depth allows to limit the recursion depth.

Parameters

nodePtr	The node pointer to define the branch of the tree to iterate.
depth	Sets the recursion depth. A depth of `0` iterates only the direct children of the node represented by nodePtr. Defaults to `std::numeric_limits<unsigned int>::max()` for "unlimited" recursion.

Definition at line 1648 of file stringtree.hpp.

Here is the call graph for this function:

◆ Initialize() [3/3]

void Initialize	(	StringTree &	pTree,
		unsigned int	depth = `(std::numeric_limits<unsigned int>::max)()`
	)

inline

Resets this iterator to work with the given StringTree. Initializes recursive iteration to the tree's root node. Optionally, a recursion depth can be set.

Parameters

pTree	The StringTree to use.
depth	Sets the recursion depth. A depth of `0` iterates only the direct children of the root node. Defaults to `std::numeric_limits<unsigned int>::max()` for "unlimited" recursion.

Definition at line 1625 of file stringtree.hpp.

Here is the call graph for this function:

◆ initialize()

void initialize	(	StringTree *	pTree,
		baseNode *	newnode,
		unsigned int	depth
	)

inlineprotected

Resets this iterator to represent to the given node of the given tree.

Parameters

pTree	The tree to iterate on.
newnode	The new node to start the iteration from.
depth	The requested recursion depth.

Definition at line 1957 of file stringtree.hpp.

Here is the call graph for this function:

◆ Invalidate()

void Invalidate ( )

inline

Invalidates this object. After invoking this method, this iterator can not be used further, until one of the overloaded methods Initialize is invoked. After the invocation, method IsValid will return false.

Definition at line 1681 of file stringtree.hpp.

◆ IsInvalid()

bool IsInvalid ( ) const

inline

The negation of IsValid.

Returns: false if this is a valid iterator. If invalid, true is returned and the iterator must not be evaluated prior to being initialized.

Definition at line 1706 of file stringtree.hpp.

Here is the call graph for this function:

◆ IsValid()

bool IsValid ( ) const

inline

Determines if this is a valid. RecursiveIterator instances may become invalid after invocations of one of the methods Next, NextSibling or NextParentSibling (at the end of the iteration) and become valid with the invocation of one of the overloaded methods Initialize.

Returns: true if this is a valid iterator. If invalid, false is returned and the iterator must not be evaluated prior to being initialized.

Definition at line 1695 of file stringtree.hpp.

◆ Next()

bool Next ( )

inline

Iterates to the first child of the current node. If no such child exists, to the next sibling node. If also no sibling exists, iteration continues with the next available node of a previous recursion level.

Returns: true if a next node was found, false otherwise. If false is returned, this iterator is invalid after the call.

Definition at line 1778 of file stringtree.hpp.

Here is the call graph for this function:

◆ next()

bool next ( int skipMode )

inlineprotected

Goes to the next node. This method is used with the derived class's interface methods Next, NextSibling and NextParentSibling, as well as with DeleteNode.

Parameters

skipMode 0 iterates to the first child (if available), 1 iterates to the next sibling (if available) and 2 to the next available sibling of the parent, respectively the current recursion stack.

Returns: true if this iterator is valid (a next node was found), false otherwise.

Definition at line 2055 of file stringtree.hpp.

Here is the call graph for this function:

◆ NextParentSibling()

bool NextParentSibling ( )

inline

Skips the remaining siblings of the current recursion level and continues with the next available sibling of a previous level.

Returns: true if a next node was found, false otherwise. If false is returned, this iterator is invalid after the call.

Definition at line 1805 of file stringtree.hpp.

Here is the call graph for this function:

◆ NextSibling()

bool NextSibling ( )

inline

Omits recursion on the current node's children, even if the current depth is lower than RequestedDepth.

If no sibling exists, iteration continues with the next available node of a previous recursion level.

Returns: true if a next node was found, false otherwise. If false is returned, this iterator is invalid after the call.

Definition at line 1793 of file stringtree.hpp.

Here is the call graph for this function:

◆ Node()

NodePtr Node ( ) const

inline

Returns the current node, encapsulated in a node pointer object.

Note: It is not allowed to use method NodePtr::Delete on the node returned by this method. As a replacement, use method DeleteNode implemented in this class.
However, methods NodePtr::DeleteChild and NodePtr::DeleteChildren are allowed to be invoked and therefore have no replacement in this class.

Returns: An instance of the public node interface pointing to the currently referenced tree node.

Definition at line 1909 of file stringtree.hpp.

Here is the call graph for this function:

◆ operator=() [1/2]

RecursiveIterator& operator= ( const RecursiveIterator & )

default

Trivial default copy assign operator.

Returns: A reference to this.

◆ operator=() [2/2]

RecursiveIterator& operator= ( RecursiveIterator && )

default

Trivial default move assign operator.

Returns: A reference to this.

◆ recursion()

void recursion ( )

inlineprotected

Sets this iterator to point to the first child of the actual node. If sorting is enabled, copies all children from the map to a vector and sorts them there.

Definition at line 1979 of file stringtree.hpp.

◆ RequestedDepth()

int RequestedDepth ( ) const

inline

Returns the requested maximum depth of iteration, set with Initialize.

See also: For the current iteration depth, use CurrentDepth.

Returns: The distance of the current node and the node of the start of the iteration.

Definition at line 1871 of file stringtree.hpp.

◆ SetPathGeneration()

void SetPathGeneration ( Switch pathGeneration )

inline

With this method, the assembly of a string representing the path from the node used to initialize this iterator to the actual node, is activated or deactivated.
If activated, the path to the current node can be received using overloaded methods CurrentPath and FullPath.

The invocation of the method invalidates this iterator. Note that the path generation can be enabled and disabled with the optional parameter of the overloaded Initialize methods.

Parameters

pathGeneration Denotes whether the path should be generated or not.

Definition at line 1607 of file stringtree.hpp.

Here is the call graph for this function:

◆ SetSorting() [1/3]

void SetSorting ( bool(*)(const NodePtr &, const NodePtr &) customSorterFunction )

inline

Sets the sorting of children by their template value, using the given callback function.

See also: For more details on sorting see method SetSorting(Switch sorting).

Parameters

customSorterFunction A custom comparison method used for sorting the children of nodes.

Definition at line 1765 of file stringtree.hpp.

◆ SetSorting() [2/3]

void SetSorting	(	SortOrder	order = `SortOrder::Ascending`,
		Case	sensitivity = `Case::Ignore`
	)

inline

Sets the sorting of children by their path name, using the built-in comparison methods, which in turn use method String::Equals.

See also: For more details on sorting see method SetSorting(Switch sorting).

Parameters

order	The sort order. Defaults to SortOrder::Ascending.
sensitivity	The case sensitivity when comparing path names. Defaults to Case::Ignore.

Definition at line 1746 of file stringtree.hpp.

◆ SetSorting() [3/3]

void SetSorting ( Switch sorting )

inline

Allows to switch sorting on or off. If switched on, sorting is performed by the node names in ascending order.

This and the overloaded versions of this method may be invoked at any time, even on invalid iterators and those that are not initialized. All that the methods do is storing the given parameters for future use. Such use happens whenever a recursive iteration over a list of child nodes is started. In that moment the current configuration of sorting is applied to the list of direct children.

Parameters

sorting The switch value.

Definition at line 1725 of file stringtree.hpp.

Member Data Documentation

◆ actDepth

size_t actDepth = static_cast<size_t >(-1)

protected

The current depth of the iteration (and usage but not size of field stack). set to -1 to if iteration is finished, respectively this iterator was not initialized.

Definition at line 1545 of file stringtree.hpp.

◆ actPath

AString actPath

protected

The path to the actual node (excluding the name of the actual node). If this object is nulled, no paths are generated.

Definition at line 1549 of file stringtree.hpp.

◆ nextCustomSorter

bool(* nextCustomSorter) (const NodePtr &, const NodePtr &) = nullptr

protected

A pointer to a user-defined comparison function for path names.

Definition at line 1555 of file stringtree.hpp.

◆ nextIsSorting

bool nextIsSorting = false

protected

Denotes if the children are iterated in a sorting fashion or not.

Definition at line 1558 of file stringtree.hpp.

◆ nextSortingIsCaseSensitive

bool nextSortingIsCaseSensitive = false

protected

The case sensitivity of the sort (used with built-in sorting by node name).

Definition at line 1564 of file stringtree.hpp.

◆ nextSortingIsDescending

bool nextSortingIsDescending = false

protected

The sort order (used with built-in sorting by node name).

Definition at line 1561 of file stringtree.hpp.

◆ node

baseNode* node

protected

The pointer to the actual node.

Definition at line 1530 of file stringtree.hpp.

◆ recursionDepth

unsigned int recursionDepth =(std::numeric_limits<unsigned int>::max)()

protected

The requested depth of iteration recursion.

Definition at line 1552 of file stringtree.hpp.

◆ stack

std::vector<RecursionData> stack

protected

A stack holding the recursive list of unsorted or sorted children and the hook to the current child. Implemented as a vector in combination with member actDepth, to reuse allocated storage space during iteration and when this iterator is re-used (freshly initialized).

Definition at line 1538 of file stringtree.hpp.

◆ tree

StringTree* tree = nullptr

protected

The StringTree this iterator belongs to.

Definition at line 1527 of file stringtree.hpp.

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 >::RecursiveIterator

Friends

Inner Classes

Public Methods

Protected Fields

Protected Methods

Constructor & Destructor Documentation

◆ RecursiveIterator() [1/3]

◆ RecursiveIterator() [2/3]

◆ RecursiveIterator() [3/3]

◆ ~RecursiveIterator()

Member Function Documentation

◆ CurrentDepth()

◆ CurrentPath()

◆ DeleteNode()

◆ FullPath()

◆ Initialize() [1/3]

◆ Initialize() [2/3]

◆ Initialize() [3/3]

◆ initialize()

◆ Invalidate()

◆ IsInvalid()

◆ IsValid()

◆ Next()

◆ next()

◆ NextParentSibling()

◆ NextSibling()

◆ Node()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ recursion()

◆ RequestedDepth()

◆ SetPathGeneration()

◆ SetSorting() [1/3]

◆ SetSorting() [2/3]

◆ SetSorting() [3/3]

Member Data Documentation

◆ actDepth

◆ actPath

◆ nextCustomSorter

◆ nextIsSorting

◆ nextSortingIsCaseSensitive

◆ nextSortingIsDescending

◆ node

◆ recursionDepth

◆ stack

◆ tree

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