This public, inner class implements an iterator that does not apply to the concept of standard Java iterators. The rational for this is the fact that the class provides mechanics to sorting the child nodes, which requires allocation of quite more resources than a usual container iterator. Therefore objects of this type are not supposed to be passed around and copied on the fly. Instead, instances should rather created once and then re-used in subsequent iterations.
Sorting of child nodes can be done using a built-in comparison function which works on the child names (path names) and allows to choose ascending and descending order and to ignore letter case, respectively be sensitive about it. Besides this, a custom comparison function for child name based sorting can be established as well as a custom function used to sort by attributes of the custom template type T. See methods sortByPathname and sortByValue for details on sorting.
Objects of this type can initialized, respectively reset to distinct start nodes by providing objects of type
to overloaded methods setStart. Then the iteration is performed with method next and its end is detected with method isValid. During iteration, method Skip stops the iteration of the current node and continues with its next sibling.
Recursiveness of iteration is controlled with method setRecursionDepth.
Finally, the generation of a string representing the actual path to the current iteration node relative to the start node can be activated. See pathGeneration for information about this feature.
For more information on iterators see description of outer class StringTree.
Inner Classes | |
class | NameAndNode |
class | RecursionData |
class | Sorter |
Public Methods | |
Walker () | |
int | depth () |
Cursor | getCursor () |
AString | getPath (AString target) |
AString | getPath (AString target, CurrentData targetData) |
AString | getPathToNode () |
StringTree< T > | getStringTree () |
void | invalidate () |
boolean | isInvalid () |
boolean | isValid () |
String | name () |
boolean | next () |
void | pathGeneration (Switch generatePath) |
void | setRecursionDepth (int _recursionDepth) |
void | setStart () |
void | setStart (Cursor cursor) |
void | setStart (Walker other) |
void | setValue (T value) |
int | size () |
void | skip () |
void | sortByPathname (Comparator< String > pathSorter) |
void | sortByPathname (SortOrder order) |
void | sortByPathname (SortOrder order, Case sensitivity) |
void | sortByValue (Comparator< T > valueSorter) |
T | value () |
Protected Fields | |
AString | actPath = new AString() |
int | recursionDepth = Integer.MAX_VALUE |
Sorter | sorter = new Sorter() |
ArrayList< RecursionData > | stack = new ArrayList<RecursionData>() |
int | stackSize = 0 |
Protected Methods | |
Node | actNode () |
void | setStart (StringTree< T >.Node newNode) |
Walker | ( | ) |
Constructor
|
protected |
Internal method to identify the actual node.
int depth | ( | ) |
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, use a combination of method getCursor and Cursor.depth.
Cursor getCursor | ( | ) |
Creates a cursor referencing the same node that this walker references.
Overloaded version providing default value CurrentData.CLEAR
for paramter targetData.
target | The target to append the path to. |
AString getPath | ( | AString | target, |
CurrentData | targetData | ||
) |
Writes the results of getPathToNode and name, separated by a separator char.
Note that this method can be used only if path generation was activated prior to the current iteration. Activation is performed with method pathGeneration.
target | The target to append the path to. |
targetData | Denotes whether target should be cleared prior to appending the path. Defaults to CurrentData.Clear. |
AString getPathToNode | ( | ) |
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 with method name.
Note that this method can be used only if path generation was activated prior to the current iteration. Activation is performed with method pathGeneration.
Note, that the AString returned must not be modified by the receiver.
StringTree<T> getStringTree | ( | ) |
Return the StringTree we are working on.
void invalidate | ( | ) |
boolean isInvalid | ( | ) |
Returns the opposite of isValid.
true
if this is an invalid cursor that must not be used, false
otherwise. boolean isValid | ( | ) |
Determines if this is a valid walker. Walkers may become invalid after invocations of method next at the end of the iteration and become valid with the invocation of one of the overloaded methods setStart (when invoked with valid objects).
true
if this is a valid cursor. If invalid, false
is returned and the cursor must not be used. String name | ( | ) |
Returns the name of the node that this walker currently represents. The name of the node corresponds to the path segment or child name that was used to create it.
boolean next | ( | ) |
Goes to the next node.
void pathGeneration | ( | Switch | generatePath | ) |
With this method, the generation of the actual path string is activated. The given character is used as separation character. The current path can be received using method getPath.
The method must be invoked prior to start walking with method next, otherwise undefined behavior might occur while 'walking'.
generatePath | Denotes whether the path should be generated or not. |
void setRecursionDepth | ( | int | _recursionDepth | ) |
Sets the requested recursion dept. A value of 0
or negative sets unlimited recursion depth.
Please note the explanation of recursion depth parameter in section Recursive Iteration of the parent class description.
_recursionDepth | Sets the new recursion dept. Use 0 for unlimited recursion. |
void setStart | ( | ) |
Resets this walker to work with the root node of its outer StringTree.
void setStart | ( | Cursor | cursor | ) |
Resets this walker to represent the node that the given cursor object represents.
cursor | The cursor to copy the represented node from. |
|
protected |
Resets this walker to represent to the given node.
newNode | The new node to start from |
void setStart | ( | Walker | other | ) |
Resets this walker to represent the same node that the given other walker object represents.
other | The walker to copy the represented node from. |
void setValue | ( | T | value | ) |
Sets the given value to the actual node object.
value | The value to set. |
int size | ( | ) |
Returns the number of direct children of the currently represented node.
void skip | ( | ) |
Skips remaining children of the current node and continues with its next sibling.
void sortByPathname | ( | Comparator< String > | pathSorter | ) |
Sets the sorting of children by their path name, using the given delegate.
Overloaded methods, which allow different sorting mechanics exist. This method should be invoked prior to the invocation of one of the setStart methods which start the iteration. Invocation during iteration is allowed, but only nodes that have not been visited yet will be affected by the new sorting.
pathSorter | A custom comparison method used for sorting the children of the nodes. |
void sortByPathname | ( | SortOrder | order | ) |
Overloaded version providing default value Case.IGNORE
for parameter sensitivity.
order | The sort order. Defaults to SortOrder.Ascending. |
Sets the sorting of children by their path name, using the built-in comparison method, which in turn uses C# method String.Compare.
Overloaded methods, which allow different sorting mechanics exist. This method should be invoked prior to the invocation of one of the setStart methods which start the iteration. Invocation during iteration is allowed, but only nodes that have not been visited yet will be affected by the new sorting.
order | The sort order. |
sensitivity | Denotes whether sorting is case sensitive or not. Defaults to Case.IGNORE. |
void sortByValue | ( | Comparator< T > | valueSorter | ) |
Sets the sorting of children by their template value, using the given delegate.
Overloaded methods, which allow different sorting mechanics exist. This method should be invoked prior to the invocation of one of the setStart methods which start the iteration. Invocation during iteration is allowed, but only nodes that have not been visited yet will be affected by the new sorting.
valueSorter | A custom comparison method used for sorting the children of the nodes. |
T value | ( | ) |
Retrieves the current StringTree nodes value.
The path to the actual node (excluding the name of the actual node).
|
protected |
The requested depth of iteration recursion.
The sorter object. This is a fixed member of the parent class providing a method to sort children by name or value type T.
|
protected |
A stack holding the recursive list of child maps and the idx of their current child. Implemented as a vector in combination with member stackSize, to reuse allocated storage space.
|
protected |
The current use of the stack.