Collaboration diagram for StringTree< T >.Cursor:

Class Description

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.

Public Methods
	Cursor ()

Cursor	clone ()

boolean	deleteChild (String childName)

int	deleteChildren ()

int	depth ()

Object	getNode ()

StringTree< T >	getStringTree ()

boolean	isInvalid ()

boolean	isRoot ()

boolean	isValid ()

boolean	moveTo (String path)

boolean	moveToAndCreateNonExistingPart (String path)

boolean	moveToAndCreateNonExistingPart (Substring path)

boolean	moveToChild (String childName)

boolean	moveToChildCreate (String childName)

Substring	moveToExistingPart (String path)

Substring	moveToExistingPart (Substring path)

boolean	moveToParent ()

boolean	moveToParentUnchecked ()

Cursor	root ()

String	searchName ()

boolean	searchNodeNameAndDeleteNode ()

void	searchPath (AString target)

void	searchPath (AString target, CurrentData targetData)

void	setValue (T value)

int	size ()

T	value ()

Protected Fields
boolean[]	booleanOutputParam

Node	node

Protected Methods
	Cursor (Node _node)

Node	createPathAndReturnLeaf (Node node, Substring path)

Node	followPath (Node node, Substring path)

Package Access Methods
boolean	equals (Cursor other)

Constructor & Destructor Documentation

◆ Cursor() [1/2]

Cursor ( Node _node )

protected

Internal constructor

Note: Although public, this is an internal constructor. It is public for technical reasons, i.e. that inner sibling class Walker can access it.

Parameters

_node The node to refer to.

◆ Cursor() [2/2]

Cursor ( )

Public constructor. Creates a cursor which is not valid.

Member Function Documentation

◆ clone()

Cursor clone ( )

Return a copy of ourselves.

Returns: A clone.

◆ createPathAndReturnLeaf()

Node createPathAndReturnLeaf	(	Node	node,
		Substring	path
	)

protected

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.

◆ deleteChild()

boolean deleteChild ( String childName )

Deletes the child named childName from the node that this cursor refers to. The cursor itself is not changed.

Parameters

childName The name of the desired child.

Returns: true if the child existed and was deleted, false otherwise.

◆ deleteChildren()

int deleteChildren ( )

Deletes the children of the node that this cursor refers to. The cursor itself is not changed.

Returns: The number of children that were deleted.

◆ depth()

int depth ( )

Determines the depth of the node represented by this cursor. This is done by counting the iterations needed to reach the root node of the tree.

Returns: The distance from this node to the root node.

◆ equals()

boolean equals ( Cursor other )

package

Comparison operator.

Parameters

other The object to compare ourselves to.

Returns: true if this and given cursor are equal, false otherwise.

◆ followPath()

Node followPath	(	Node	node,
		Substring	path
	)

protected

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

◆ getNode()

Object getNode ( )

Return the current object.

Note: Although public, this is an internal method. It is public for technical reasons, i.e. that inner sibling class Walker can access it.

Returns: The StringTree object.

◆ getStringTree()

StringTree<T> getStringTree ( )

Return the StringTree we are working on.

Returns: The StringTree object.

◆ isInvalid()

boolean isInvalid ( )

Returns the opposite of isValid.

Returns: true if this is an invalid cursor that must not be used, false otherwise.

◆ isRoot()

boolean isRoot ( )

Returns true if this cursor represents the root node of the StringTree, false otherwise.

Returns: true if this is the root node, false otherwise.

◆ isValid()

boolean isValid ( )

Determines if this is a valid cursor. Cursors usually do not get invalid. See method moveToParent for more information about how cursors may get invalid and how this is useful.

Returns: true if this is a valid cursor. If invalid, false is returned and the cursor must not be used.

◆ moveTo()

boolean moveTo ( String path )

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.

◆ moveToAndCreateNonExistingPart() [1/2]

boolean moveToAndCreateNonExistingPart ( String path )

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.

◆ moveToAndCreateNonExistingPart() [2/2]

boolean moveToAndCreateNonExistingPart ( Substring path )

Overloaded version accepting a Substring.

Parameters

path	The path to move along.

Returns: false if the complete path existed, true if a part of it was created.

◆ moveToChild()

boolean moveToChild ( String childName )

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.

◆ moveToChildCreate()

boolean moveToChildCreate ( String childName )

Moves this cursor to the child node named childName. If no child with this name exists, one will be created.

This method checks the given childName to not equal to "." or ".." and that it does not contain the separation character. If it does, false is returned and in debug compilations an ALIB_DBG.WARNING is reported.

Parameters

childName The name of the desired child.

Returns: true if the child was found or created, false otherwise.

◆ moveToExistingPart() [1/2]

Substring moveToExistingPart ( String path )

Moves this cursor along the existing portion of the given path. The method returns the remaining portion of the path that did not exist.

See moveTo and moveToAndCreateNonExistingPart for alternatives.

Parameters

path	The path to move along.

Returns: The unconsumed portion of the path. Empty if the path existed.

◆ moveToExistingPart() [2/2]

Substring moveToExistingPart ( Substring path )

Overloaded version accepting a Substring.

Parameters

path	The path to move along.

Returns: The unconsumed portion of the path. Empty if the path existed. The object returned is identical to given path.

◆ moveToParent()

boolean moveToParent ( )

Moves this cursor to its parent node. The method will not move a cursor that is already pointing to the root of the StringTree into an invalid state. Instead the cursor remains unchanged and false is returned.
The unchecked version moveToParentUnchecked will turn the cursor into an invalid state if no parent node exists. This is useful in two situations:

For effective iterating from any node up to the StringTree root node. The condition to check in such loop is isValid.
In situations when it is was already checked that a cursor does not represent the root node. This is demonstrated in the following sample taken from this classes' method searchPath:
Cursor iter= new Cursor( node );

while( !iter.isRoot() ) // <- not root?

{

if( target.length() > insertionPos )

target.insertChars( separator, 1, insertionPos );

target.insertAt( iter.searchName(), insertionPos );

iter.moveToParentUnchecked(); // <- non-checking version to avoid a redundant check.

}

Returns
true if this object was moved to its parent (had a parent), false otherwise.

◆ moveToParentUnchecked()

boolean moveToParentUnchecked ( )

Non-checking version of moveToParent.

Returns: true if this object is valid after the operation, false otherwise.

◆ root()

Cursor root ( )

Moves this cursor to the root of its StringTree.

Returns: this to allow concatenated calls

◆ searchName()

String searchName ( )

Returns the name of the node that this cursor represents. The method searches all children of this nodes' parent node and returns the key that this node was stored with. If the represented node is the root node, null is returned.

Note: In most situations the name of the node should be available in the context where an invocation of this method is considered. In other words, this method should be rarely needed and used under the presumption that it does not perform in constant execution time.

Returns: The name of the represented node.

◆ searchNodeNameAndDeleteNode()

boolean searchNodeNameAndDeleteNode ( )

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.

◆ searchPath() [1/2]

void searchPath ( AString target )

Overloaded version providing default value CurrentData.CLEAR for paramter targetData.

Parameters

target The target to append the path to.

◆ searchPath() [2/2]

void searchPath	(	AString	target,
		CurrentData	targetData
	)

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.

[DOX_ALIB_STRING_TREE_MOVETOPARENT]

◆ setValue()

void setValue ( T value )

Sets the given value to the actual node object.

Parameters

value The value to set.

◆ size()

int size ( )

Returns the number of direct children.

Returns: The number of children of the represented node.

◆ value()

T value ( )

Retrieves the value of the currently represented node.

Returns: The current nodes' value.

Member Data Documentation

◆ booleanOutputParam

boolean [] booleanOutputParam

protected

A temporary object following the "create once and reuse" design pattern.

◆ node

Node node

protected

The node this cursor represents.

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

StringTree.java

Class Description

Public Methods

Protected Fields

Protected Methods

Package Access Methods

Constructor & Destructor Documentation

◆ Cursor() [1/2]

◆ Cursor() [2/2]

Member Function Documentation

◆ clone()

◆ createPathAndReturnLeaf()

◆ deleteChild()

◆ deleteChildren()

◆ depth()

◆ equals()

◆ followPath()

◆ getNode()

◆ getStringTree()

◆ isInvalid()

◆ isRoot()

◆ isValid()

◆ moveTo()

◆ moveToAndCreateNonExistingPart() [1/2]

◆ moveToAndCreateNonExistingPart() [2/2]

◆ moveToChild()

◆ moveToChildCreate()

◆ moveToExistingPart() [1/2]

◆ moveToExistingPart() [2/2]

◆ moveToParent()

◆ moveToParentUnchecked()

◆ root()

◆ searchName()

◆ searchNodeNameAndDeleteNode()

◆ searchPath() [1/2]

◆ searchPath() [2/2]

◆ setValue()

◆ size()

◆ value()

Member Data Documentation

◆ booleanOutputParam

◆ node