This public, inner class provides the main interface into outer class StringTree. Only with an object of this class, new nodes can be inserted and removed. As the name indicates, an object of this class represents a current position within a StringTree.
The class is very lightweight. In fact, besides a pointer to the StringTree it works on, the only other member is a pointer to the currently represented node of the StringTree. This allows to copy and move instances of this class very efficiently.
For more information on the how this class is used, see Inserting, Retrieving And Deleting Nodes.
Creates child nodes corresponding to the given path. If the first node already exists, nothing is done and null
is returned as this is considered an error. If the given path is empty the given node is returned as this is not considered an error.
Child names "."
and ".."
are ignored, but considered an error. In debug builds, an ALIB_DBG.WARNING is reported.
The final leaf node is returned.
- Parameters
-
| node | The start node. |
[in,out] | path | Creation path. Will be consumed if not errorneous. |
- Returns
- The leaf node of all created nodes.
null
in the case that the first child given in path already exists.
Finds a child node along the path given, but does not create new nodes. Incomplete results may occur if a child along the path was not found. In this case, parameter path contains the remaining path, excluding a leading separator.
A leading slash (aka StringTree<T>.separator) allows absolute path addressing, which means the root of node is searched if a leading separator is found.
Besides normal child names, this method accepts
- multiple separator characters (ignored)
- child name "." (ignored)
- child name ".." for parent node
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, the paths:
/a/../b
and
/a/../../b
both evaluate to
/b
assumed that /a and /b exist.
- Parameters
-
| node | The start node. |
[in,out] | path | Creation path. Will be consumed as far as the path exits. |
- Returns
- The node found
bool MoveTo |
( |
String |
path | ) |
|
|
inline |
Moves this cursor along the given path.
The method supports absolute and relative path addressing: If path begins with a separation character, then the cursor is moved to the root of the StringTree. Furthermore, child name "."
is ignored and just skipped while if ".."
is found in the path, the cursor is moved to its parent. Repeated separation characters are ignored.
If a child along the path does not exist, this cursor remains unchanged and false
is returned. This includes the case that child name ".."
is read while the cursor references the root node.
See MoveToExistingPart and MoveToAndCreateNonExistingPart for alternatives.
- Parameters
-
path | The path to move along. |
- Returns
- A std.pair of a reference to this cursor and a boolean value. The boolean value indicates if the path existed and the move to the node specified by path was performed.
bool MoveToAndCreateNonExistingPart |
( |
String |
path | ) |
|
|
inline |
Moves this cursor along the existing portion of the given path and then creates any non-existing, remaining portion.
Child names "."
and ".."
in the creation portion of the given path are ignored, but considered an error. In debug builds, an ALIB_DBG.WARNING is reported.
See MoveTo and MoveToExistingPart for alternatives.
- Parameters
-
path | The path to move along. |
- Returns
false
if the complete path existed, true
if a part of it was created.
bool MoveToChild |
( |
String |
childName | ) |
|
|
inline |
Moves this cursor to the child node named childName. If no child with this name exists, the cursor remains as is and false
is returned.
This method does not check the given childName to to be valid (i.e not equal to "."
or ".."
or contain a separator character. Children with this name do not exist and should not be found. However, in debug compilations, an ALIB_DBG.WARNING is reported.
- Parameters
-
childName | The name of the desired child. |
- Returns
true
if the child existed and this object is valid, false
otherwise.
bool SearchNodeNameAndDeleteNode |
( |
| ) |
|
|
inline |
Deletes the node that this cursor refers to from the tree. If this cursor did not represent the root node, then after the operation, the cursor refers to the parent node. Otherwise, only the children are deleted and the cursor remains representing the same (root) node.
The method involves a call to SearchName, which - as documented - is not considered to be efficient. If the name of the current node is known, then it is advised to use method DeleteChild on the parent of this node.
- Returns
true
if this node was not the root node and could be removed from the parent. false
if this not was the root node.
Builds a path string from the root node to this node. This is done in reverse order, starting from this node using method SearchName. Hence, this method is not considered efficient! For each depth-level of the represented node, a 'reverse' search in the parent's map of children is involved.
It is recommended to search for other ways to keep track of the current path of a cursor - outside of this class and use this method for e.g. for debug purposes or really rare cases.
- 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. |