template<typename TAllocator, typename T, typename TNodeHandler = StringTreeNamesDynamic<character>,
Recycling TRecycling = Recycling::Private>
template<bool TConst>
class alib::containers::StringTree< TAllocator, T, TNodeHandler, TRecycling >::TCursor< TConst >
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 insert and remove child nodes.
Instances of this class can be received with methods Root and RecursiveIterator::Node.
The default constructor creates an invalid object, which has to be initialized by assigning a valid object before its first use.
- See also
- For more information on how this class is used, see paragraph 2.1 Inner Class Cursor of the description of class StringTree.
- Template Parameters
-
| TConst | If true, internal fields representing the StringTree and the current Node become const and methods which are not declared const become unavailable. |
Friends
class StringTree
Definition at line 712 of file stringtree.hpp.
|
| | TCursor () noexcept=default |
| |
| | TCursor (const TCursor &src) noexcept |
| |
| | TCursor (TCursor &&src) noexcept |
| |
|
| ~TCursor () noexcept=default |
| | Trivial default destructor.
|
| |
| strings::TAString< typename cmTree::CharacterType, lang::HeapAllocator > & | AssemblePath (strings::TAString< typename cmTree::CharacterType, lang::HeapAllocator > &targetString, const TCursor< true > &parent, lang::CurrentData targetData=lang::CurrentData::Clear) const |
| |
| strings::TAString< typename cmTree::CharacterType, lang::HeapAllocator > & | AssemblePath (strings::TAString< typename cmTree::CharacterType, lang::HeapAllocator > &targetString, lang::CurrentData targetData=lang::CurrentData::Clear) const |
| |
| TCursor | Child (const NameType &name) const |
| |
| uinteger | CountChildren () const |
| |
| template<typename TCheck = CHK, typename... TArgs> |
| TCursor | CreateChild (const NameType &childName, TArgs &&... args) const |
| |
| template<typename... TArgs> |
| std::pair< TCursor, bool > | CreateChildIfNotExistent (const NameType &name, TArgs &&... args) |
| |
| template<typename... TArgs> |
| std::pair< TCursor, integer > | CreatePathIfNotExistent (const NameType &path, TArgs &&... args) |
| |
| uinteger | Delete () |
| |
| bool | DeleteChild (const NameType &childName) const |
| |
| void | DeleteChild (TCursor &child) const |
| |
| uinteger | DeleteChildren () const |
| |
| int | Depth () const |
| |
| int | Distance (const TCursor< true > &other) const |
| |
| CursorHandle | Export () |
| |
| ConstCursorHandle | Export () const |
| |
| TCursor | FirstChild () const |
| |
| SubstringType | GoTo (const NameType &path) |
| |
| 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 () |
| |
| TCursor & | GoToParent () |
| |
| bool | GoToPreviousSibling () |
| |
| TCursor & | GoToRoot () |
| |
| bool | HasChildren () const |
| |
| bool | HasNextSibling () const |
| |
| bool | HasPreviousSibling () const |
| |
| bool | IsInvalid () const |
| |
| bool | IsRoot () const |
| |
| bool | IsValid () const |
| |
| TCursor | LastChild () const |
| |
| const NameType & | Name () const |
| |
| TCursor | NextSibling () const |
| |
| | operator TCursor<!TConst > () |
| |
| bool | operator!= (const TCursor &other) const |
| |
| std::pair< TCursor, SubstringType > | operator() (const NameType &path) const |
| |
| T & | operator* () |
| |
| const T & | operator* () const |
| |
| T * | operator-> () |
| |
| const T * | operator-> () const |
| |
| TCursor & | operator= (const TCursor &) noexcept=default |
| |
| TCursor & | operator= (TCursor &&) noexcept=default |
| |
| bool | operator== (const TCursor &other) const |
| |
| TCursor | Parent () const |
| |
| TCursor | PreviousSibling () const |
| |
| TCursor | Root () const |
| |
| template<typename TParent = StringTree> |
| const TParent & | Tree () |
| |
| T & | Value () |
| |
| const T & | Value () const |
| |
template<typename TAllocator , typename T , typename TNodeHandler = StringTreeNamesDynamic<character>,
Recycling TRecycling = Recycling::Private>
template<bool TConst>
Same as AssemblePath but accepts a parent node to stop at, instead of the root node. The path created is a relative path from the parent to the represented node, hence it does not include the parent' name and also does not start with the separation character. The latter is true even if the given targetParent represents the root node. In this case the path is a relative path from the root node '/' to the child.
If the given parent is not found within the list of parent nodes, then an absolute path from the tree's root to the represented node is returned.
- Parameters
-
| targetString | The string buffer to append the path to. |
| parent | Denotes the parent node to start a relative path from. |
| targetData | Denotes whether target should be cleared before appending the path. Defaults to CurrentData::Clear. |
- Returns
- The given AString to allow concatenated operations.
Definition at line 1511 of file stringtree.hpp.
template<typename TAllocator , typename T , typename TNodeHandler = StringTreeNamesDynamic<character>,
Recycling TRecycling = Recycling::Private>
template<bool TConst>
Writes the absolute path to the represented node (including the represented node's name) to the given AString.
If this node represents the root node, then nothing is written but a single separation character.
While the implementation of this method is as efficient as possible (to avoid insertions at the beginning of the target string while moving to the destination/root node, internally a local node-stack is created first, which then is traversed top-down), still in many situations, it is recommended to search for other ways to keep track of the current path of a node and modify and re-use such path. For this, class StringTree::RecursiveIterator, optionally allows maintaining a string representing the current path with every iteration.
- See also
- Overloaded version AssemblePath(AString&,TCursor<TConst>&,lang::CurrentData), which allows the creation a relative path from a parent node to this node.
- Parameters
-
| targetString | The string buffer to append the path to. |
| targetData | Denotes whether target should be cleared before appending the path. Defaults to CurrentData::Clear. |
- Returns
- The given AString to allow concatenated operations.
Definition at line 1482 of file stringtree.hpp.
template<typename TAllocator , typename T , typename TNodeHandler = StringTreeNamesDynamic<character>,
Recycling TRecycling = Recycling::Private>
template<bool TConst>
Searches a child with the given name and returns a cursor to it. If no child with this name exists, the returned cursor 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 cannot 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 cursor representing the last child of the node represented by this cursor.
Definition at line 1041 of file stringtree.hpp.
template<typename TAllocator , typename T , typename TNodeHandler = StringTreeNamesDynamic<character>,
Recycling TRecycling = Recycling::Private>
template<bool TConst>
template<typename TCheck = CHK, typename... TArgs>
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 cursor 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 NC and inserting child nodes with the same name, sets a StringTree to an undefined state.
- Template Parameters
-
| TCheck | If NC, 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 the constructor of custom type T of the child created. |
- Returns
- A new cursor 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 1552 of file stringtree.hpp.
template<typename TAllocator , typename T , typename TNodeHandler = StringTreeNamesDynamic<character>,
Recycling TRecycling = Recycling::Private>
template<bool TConst>
template<typename... TArgs>
| std::pair< TCursor, bool > CreateChildIfNotExistent |
( |
const NameType & | name, |
|
|
TArgs &&... | args ) |
|
inline |
Moves this cursor 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 cursor 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 the constructor of custom type T in the case a child is created. |
- Returns
- A pair of a cursor 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 cursor will be invalid while the boolean still indicates "not found" (aka true).
Definition at line 1092 of file stringtree.hpp.
template<typename TAllocator , typename T , typename TNodeHandler = StringTreeNamesDynamic<character>,
Recycling TRecycling = Recycling::Private>
template<bool TConst>
Searches a child with the given name and moves this cursor to it. If no child with this name exists, the cursor 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 a name cannot 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 1061 of file stringtree.hpp.
template<typename TAllocator , typename T , typename TNodeHandler = StringTreeNamesDynamic<character>,
Recycling TRecycling = Recycling::Private>
template<bool TConst>
template<typename... TArgs>
| bool GoToCreateChildIfNotExistent |
( |
const NameType & | name, |
|
|
TArgs &&... | args ) |
|
inline |
Moves this cursor 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 cursor 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 the 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 1120 of file stringtree.hpp.
template<typename TAllocator , typename T , typename TNodeHandler = StringTreeNamesDynamic<character>,
Recycling TRecycling = Recycling::Private>
template<bool TConst>
template<typename... TArgs>
| 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 operator()(const NameType&).
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 the constructor of each node that is created. |
- Returns
- The number of nodes created.
Definition at line 1238 of file stringtree.hpp.
template<typename TAllocator , typename T , typename TNodeHandler = StringTreeNamesDynamic<character>,
Recycling TRecycling = Recycling::Private>
template<bool TConst>
Follows the given path from the currently represented node to the target node and returns a new cursor instance..
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 cursors. 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 cursor 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 1172 of file stringtree.hpp.
