ITreeCursor

For n-ary trees, cursors are used to point to nodes in the tree. Unlike cursors of flat collections, tree cursors stay defined when elements are added to the tree, or when elements othe than the one pointed to are removed. Cursors are used in operations to access the element information stored in a node. They are also used to designate a subtree of the tree, namely the subtree whose root node the cursor points to.

As for flat collections, a distinction is made between the abstract base class ITreeCursor, and cursor classes local to the tree classes themselves. The local, or nested, cursor classes are derived from the abstract base class.


ITreeCursor - Member Functions and Data by Group

Constructors & Destructor

Use these member functions to construct or destruct objects of the class.


[view class]
~ITreeCursor
public:
virtual ~ITreeCursor()

Removes all elements from this tree.

Side Effects

All cursors of the tree become undefined.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
ITreeCursor

Constructs the cursor and associates it with the given tree. The cursor is initially invalid.


Overload 1
protected:
ITreeCursor(ITreeCursor const&)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
protected:
ITreeCursor(Implementation*)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Cursor Settings

Use these member functions to set the cursor to required position.


[view class]
setToChild
public:
bool setToChild(IPosition)

Sets the cursor to the child with the given position of the node denoted by the given cursor (of this tree). Invalidates the cursor if this child does not exist.

Preconditions

Return Value

Returns true if the child exists.

Exceptions

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setToFirstExistingChild
public:
bool setToFirstExistingChild()

Sets the cursor to the first child of the node denoted by the given cursor (of this tree). Invalidates the cursor if the node has no child. A node with no child is a leaf node of the tree.

Preconditions

The cursor must point to an element of this tree.

Return Value

Returns true if the node has a child.

Exception

ICursorInvalidException

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setToLastExistingChild
public:
bool setToLastExistingChild()

Sets the cursor to the last child of the node denoted by the given cursor (of this tree). Invalidates the cursor if the node has no child. A node with no child is a leaf node of the tree.

Precondition

The cursor must point to an element of this tree.

Return Value

Returns true if the node has a child.

Exception

ICursorInvalidException

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setToNextExistingChild
public:
bool setToNextExistingChild()

Sets the cursor to the next existing sibling of the node denoted by the given cursor (of this tree). Invalidates the cursor if the node has no next sibling. A node with no next sibling is the last existing child of its parent.

Precondition

The cursor must point to an element of this tree.

Return Value

Returns true if the node has a next sibling.

Exception

ICursorInvalidException

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setToParent
public:
bool setToParent()

Sets the cursor to the parent of the node denoted by the given cursor (of this tree). Invalidates the cursor if the node has no parent. A node with no parent is the root node of its tree.

Precondition

The cursor must point to an element of this tree.

Return Value

Returns true if the node has a parent.

Exception

ICursorInvalidException

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setToPreviousExistingChild
public:
bool setToPreviousExistingChild()

Sets the cursor to the previous existing sibling of the node denoted by the given cursor (of this tree). Invalidates the cursor if the node has no previous sibling. A node with no previous sibling is the first existing child of its parent.

Precondition

The cursor must point to an element of this tree.

Return Value

Returns true if the node has a previous sibling.

Exception

ICursorInvalidException

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setToRoot
public:
bool setToRoot()

Sets the cursor to the root node of the tree. Invalidates the cursor if the tree is empty (that is, if no root node exists).

Precondition

The cursor must belong to this tree.

Return Value

Returns true if the tree is not empty.

Exception

ICursorInvalidException

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Cursor Validation

Use these members to validate the cursor.


[view class]
invalidate
public:
void invalidate()

Invalidates the cursor so that it no longer points to a node of the associated tree.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isValid
public:
bool isValid() const

Returns true if the cursor points to a node of the associated tree.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Miscellaneous

Use these members to execute miscellaneous functions.


[view class]
copy
public:
void copy(ITreeCursor const&)

Removes all elements from this tree, and copies the subtree denoted by the given cursor of the given tree to (the root of) this tree. The copy function (without a cursor argument) copies the whole given tree.

Preconditions

The cursor must point to an element of the given tree.

Exceptions

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
ImplOf
protected:
inline static Implementation& ImplOf(ITreeCursor const&)
Returns a reference to the implementation object for this tree cursor object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Operators

Use these members as operators.


[view class]
operator !=
public:
bool operator !=(ITreeCursor const&) const

Returns true if the cursor does not point to the same node of the same tree as the given cursor.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator =
public:
void operator =(ITreeCursor const&)

Copies all elements of the given tree to this tree.

Return Value

A reference to this tree.

Side Effects

All cursors of this tree become undefined.

Exception

IOutOfMemory

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
operator ==
public:
bool operator ==(ITreeCursor const&) const

Returns true if the cursor points to the same node of the same tree as the given cursor.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


ITreeCursor - Inherited Member Functions and Data

Inherited Public Functions

Inherited Public Data

Inherited Protected Functions

Inherited Protected Data