Description:

template<typename TStringTree>
class alib::containers::StringTreeIterator< TStringTree >

This class is to be used with instances of class StringTree and allows iterating recursively through its nodes.
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 the 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 C++ range-based loops. Instead, instances should rather be created once and then re-used with later iterations.

The sorting of child nodes is optional and can be changed before each recursion. Whenever a recursion in iteration occurs, the most recent settings of sorting are respected for the children of the node that is processed with that recursion.
A built-in comparison function which works on node names (path names) allows choosing ascending and descending order and to ignore or be sensitive about the 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 method SetSorting for details on this topic.

Method Initialize starts a new 'use' of this class. Besides the start node, a boolean parameter allows deciding whether the start node should be included in the iteration or not. This is useful in cases where the start-node could optionally be a leaf-node. For example, when processing files with class FTree, an application might allow accepting a single file or a folder that contains files. In this case, the iteration should include the start node, as otherwise, in case a file was given, that leaf-node would be skipped.

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 the methods Next or NextSibling to proceed. Furthermore, the method NextParentSibling allows skipping the rest of the current iteration branch.
The end of an iteration is detected with the method IsValid.

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: Further information on how this class is used are given with paragraph 2.2 Class StringTreeIterator of the description of class StringTree.

Template Parameters

TStringTree The StringTree that this class is working with.

Definition at line 55 of file stringtreeiterator.inl.

Collaboration diagram for alib::containers::StringTreeIterator< TStringTree >:

[legend]

Inner Type Index:
struct	NameSorter

struct	RecursionData
	Protected, internal struct used to store the data of recursive iterations. More...

struct	Sorter

Public Type Index:
using	CharacterType = typename StringTreeType::CharacterType
	Exposes StringTree::CharacterType StringTreeType.

using	CursorType

using	StringTreeType = TStringTree
	Publicly Exposes template parameter TStringTree.

Public Static Field Index:
static constexpr bool	IsConst = std::is_const_v<TStringTree>
	Evaluates to `true` if the given template parameter TStringTree is a constant type.

Public Method Index:
	StringTreeIterator ()=default
	Default constructor.

	StringTreeIterator (const StringTreeIterator &)=default
	Trivial copy constructor.

	StringTreeIterator (StringTreeIterator &&)=default
	Trivial default move constructor.

	~StringTreeIterator ()=default
	Destructor.

unsigned	CurrentDepth () const

uinteger	DeleteNode ()

void	Initialize (CursorType startNode, lang::Inclusion includeStartNode)

void	Invalidate ()

bool	IsInvalid () const

bool	IsValid () const

unsigned	MaxDepth () const

bool	Next ()

bool	NextParentSibling ()

bool	NextSibling ()

CursorType	Node () const

StringTreeIterator &	operator= (const StringTreeIterator &)=default

StringTreeIterator &	operator= (StringTreeIterator &&)=default

const TStringTree::NameType	Path () const

void	SetMaxDepth (unsigned int newMaxDepth=(std::numeric_limits< unsigned >::max)())

void	SetPathGeneration (lang::Switch pathGeneration)

void	SetSorting (Sorter *sorter)

Protected Type Index:
using	cursorHandle

Protected Field Index:
int	actDepth =-1

strings::TAString< CharacterType >	actPath

unsigned	maxDepth =(std::numeric_limits<unsigned int>::max)()
	The requested maximum depth of iteration recursion.

Sorter *	nextSorter =nullptr
	A pointer to a user-defined comparison object used with the next iteration.

cursorHandle	node
	The pointer to the actual node.

std::vector< RecursionData >	stack

TStringTree *	tree =nullptr
	The StringTree that this iterator works on.

Protected Method Index:
bool	next (int skipMode)

void	recursion ()

Type Definition Details:

◆ CharacterType

template<typename TStringTree>

using alib::containers::StringTreeIterator< TStringTree >::CharacterType = typename StringTreeType::CharacterType

Exposes StringTree::CharacterType StringTreeType.

Definition at line 80 of file stringtreeiterator.inl.

◆ cursorHandle

template<typename TStringTree>

using alib::containers::StringTreeIterator< TStringTree >::cursorHandle

protected

Initial value:

 std::conditional_t<!IsConst,
                                                       typename StringTreeType::CursorHandle,
                                                       typename StringTreeType::ConstCursorHandle>

Constant or mutable version of the base tree type, depending on template parameter TStringTree

Definition at line 85 of file stringtreeiterator.inl.

◆ CursorType

template<typename TStringTree>

using alib::containers::StringTreeIterator< TStringTree >::CursorType

Initial value:

 std::conditional_t< !IsConst,
                                                            typename StringTreeType::Cursor,
                                                            typename StringTreeType::ConstCursor>

Publicly exposes the cursor type that is used to walk the tree. Evaluates to the constant or mutable types StringTree::Cursor or or StringTree::ConstCursor.

Definition at line 75 of file stringtreeiterator.inl.

◆ StringTreeType

template<typename TStringTree>

using alib::containers::StringTreeIterator< TStringTree >::StringTreeType = TStringTree

Publicly Exposes template parameter TStringTree.

Definition at line 67 of file stringtreeiterator.inl.

Field Details:

◆ actDepth

template<typename TStringTree>

int alib::containers::StringTreeIterator< TStringTree >::actDepth =-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 212 of file stringtreeiterator.inl.

◆ actPath

template<typename TStringTree>

strings::TAString<CharacterType> alib::containers::StringTreeIterator< TStringTree >::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 207 of file stringtreeiterator.inl.

◆ IsConst

template<typename TStringTree>

bool alib::containers::StringTreeIterator< TStringTree >::IsConst = std::is_const_v<TStringTree>

staticconstexpr

Evaluates to true if the given template parameter TStringTree is a constant type.

Definition at line 70 of file stringtreeiterator.inl.

◆ maxDepth

template<typename TStringTree>

unsigned alib::containers::StringTreeIterator< TStringTree >::maxDepth =(std::numeric_limits<unsigned int>::max)()

protected

The requested maximum depth of iteration recursion.

Definition at line 215 of file stringtreeiterator.inl.

◆ nextSorter

template<typename TStringTree>

Sorter* alib::containers::StringTreeIterator< TStringTree >::nextSorter =nullptr

protected

A pointer to a user-defined comparison object used with the next iteration.

Definition at line 218 of file stringtreeiterator.inl.

◆ node

template<typename TStringTree>

cursorHandle alib::containers::StringTreeIterator< TStringTree >::node

protected

The pointer to the actual node.

Definition at line 197 of file stringtreeiterator.inl.

◆ stack

template<typename TStringTree>

std::vector<RecursionData> alib::containers::StringTreeIterator< TStringTree >::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 203 of file stringtreeiterator.inl.

◆ tree

template<typename TStringTree>

TStringTree* alib::containers::StringTreeIterator< TStringTree >::tree =nullptr

protected

The StringTree that this iterator works on.

Definition at line 194 of file stringtreeiterator.inl.

Method Details:

◆ CurrentDepth()

template<typename TStringTree>

unsigned alib::containers::StringTreeIterator< TStringTree >::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, the method TCursor::Depth, may be used.

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

Definition at line 385 of file stringtreeiterator.inl.

◆ DeleteNode()

template<typename TStringTree>

uinteger alib::containers::StringTreeIterator< TStringTree >::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 TCursor::Delete, which is forbidden to be invoked on the node returned by method Node as this would invalidate this iterator.
Methods TCursor::DeleteChild and TCursor::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 431 of file stringtreeiterator.inl.

◆ Initialize()

template<typename TStringTree>

void alib::containers::StringTreeIterator< TStringTree >::Initialize	(	CursorType	startNode,
		lang::Inclusion	includeStartNode )

inline

Resets this iterator to the first child of the node that the given cursor object represents.
If the given node has no children, this iterator is marked invalid when this method returns, unless param includeStartNode is set to true. In the latter case, at least the start node is part of the iteration.

Parameters

startNode	The cursor that defines the branch of the tree to be iterated. In debug-builts it is asserted that this instance is valid.
includeStartNode	Denotes whether the startNode is included in the iteration or not. If so, the start node will be the first node visited.

Definition at line 265 of file stringtreeiterator.inl.

◆ Invalidate()

template<typename TStringTree>

void alib::containers::StringTreeIterator< TStringTree >::Invalidate ( )

inline

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

Definition at line 296 of file stringtreeiterator.inl.

◆ IsInvalid()

template<typename TStringTree>

bool alib::containers::StringTreeIterator< TStringTree >::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 before being initialized.

Definition at line 311 of file stringtreeiterator.inl.

◆ IsValid()

template<typename TStringTree>

bool alib::containers::StringTreeIterator< TStringTree >::IsValid ( ) const

inline

Determines if this instance is valid. StringTreeIterator 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 before being initialized.

Definition at line 305 of file stringtreeiterator.inl.

◆ MaxDepth()

template<typename TStringTree>

unsigned alib::containers::StringTreeIterator< TStringTree >::MaxDepth ( ) 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 367 of file stringtreeiterator.inl.

◆ Next()

template<typename TStringTree>

bool alib::containers::StringTreeIterator< TStringTree >::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 331 of file stringtreeiterator.inl.

◆ next()

template<typename TStringTree>

bool alib::containers::StringTreeIterator< TStringTree >::next ( int skipMode )

inlineprotected

Goes to the next node. This method is used with 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 505 of file stringtreeiterator.inl.

◆ NextParentSibling()

template<typename TStringTree>

bool alib::containers::StringTreeIterator< TStringTree >::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 348 of file stringtreeiterator.inl.

◆ NextSibling()

template<typename TStringTree>

bool alib::containers::StringTreeIterator< TStringTree >::NextSibling ( )

inline

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

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 341 of file stringtreeiterator.inl.

◆ Node()

template<typename TStringTree>

CursorType alib::containers::StringTreeIterator< TStringTree >::Node ( ) const

inline

Returns the current node, encapsulated in a cursor object.

Note: It is not allowed to use the method TCursor::Delete on the node returned by this method. As a replacement, use the method DeleteNode provided with this class.
However, the methods TCursor::DeleteChild and TCursor::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 406 of file stringtreeiterator.inl.

◆ operator=() [1/2]

template<typename TStringTree>

StringTreeIterator & alib::containers::StringTreeIterator< TStringTree >::operator= ( const StringTreeIterator< TStringTree > & )

default

Trivial default copy assign operator.

Returns: A reference to this.

◆ operator=() [2/2]

template<typename TStringTree>

StringTreeIterator & alib::containers::StringTreeIterator< TStringTree >::operator= ( StringTreeIterator< TStringTree > && )

default

Trivial default move assign operator.

Returns: A reference to this.

◆ Path()

template<typename TStringTree>

const TStringTree::NameType alib::containers::StringTreeIterator< TStringTree >::Path ( ) const

inline

Retrieves the current path of walking as a string representation. The path returned is absolute with a leading separator character.

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

Returns: The path of the current node.

Definition at line 358 of file stringtreeiterator.inl.

◆ recursion()

template<typename TStringTree>

void alib::containers::StringTreeIterator< TStringTree >::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 445 of file stringtreeiterator.inl.

◆ SetMaxDepth()

template<typename TStringTree>

void alib::containers::StringTreeIterator< TStringTree >::SetMaxDepth ( unsigned int newMaxDepth = (std::numeric_limits<unsigned>::max)() )

inline

Changes the maximum depth of iteration. This method may be invoked any time, also after iteration has started.

Parameters

newMaxDepth The maximum depth to use from now on. Defaults to the maximum unsigned int value.

Definition at line 373 of file stringtreeiterator.inl.

◆ SetPathGeneration()

template<typename TStringTree>

void alib::containers::StringTreeIterator< TStringTree >::SetPathGeneration ( lang::Switch pathGeneration )

inline

With this method, the assembly of a string representing the absolute path of the actual node is activated or deactivated.
If activated, the path to the current node can be received with the method Path.

Note that, for technical reasons, the invocation of the method invalidates this iterator.

Parameters

pathGeneration Denotes whether the path should be generated and retrievable or not.

Definition at line 250 of file stringtreeiterator.inl.

◆ SetSorting()

template<typename TStringTree>

void alib::containers::StringTreeIterator< TStringTree >::SetSorting ( Sorter * sorter )

inline

Sets a sorter instance which is used for any next recursion step.

This method may be invoked at any time, even on invalid iterators and those that are not initialized, yet. The given sorter is stored for future use. Such a use happens whenever a recursive iteration over a list of child nodes is started. At that moment the current configuration of sorting is applied to the list of direct children.

Parameters

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

Definition at line 323 of file stringtreeiterator.inl.

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

stringtreeiterator.inl

Description:

Inner Type Index:

Public Type Index:

Public Static Field Index:

Public Method Index:

Protected Type Index:

Protected Field Index:

Protected Method Index:

Type Definition Details:

◆ CharacterType

◆ cursorHandle

◆ CursorType

◆ StringTreeType

Field Details:

◆ actDepth

◆ actPath

◆ IsConst

◆ maxDepth

◆ nextSorter

◆ node

◆ stack

◆ tree

Method Details:

◆ CurrentDepth()

◆ DeleteNode()

◆ Initialize()

◆ Invalidate()

◆ IsInvalid()

◆ IsValid()

◆ MaxDepth()

◆ Next()

◆ next()

◆ NextParentSibling()

◆ NextSibling()

◆ Node()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ Path()

◆ recursion()

◆ SetMaxDepth()

◆ SetPathGeneration()

◆ SetSorting()