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

~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

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.

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

  - The cursor must point to an element of this tree.
  - (1 <= position <= numberOfChildren).

  Return Value

  Returns true if the child exists.

  Exceptions

  - ICursorInvalidException
  - IPositionInvalidException

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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

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

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

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

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

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.

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

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.

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

  - IOutOfMemory
  - ICursorInvalidException

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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.

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

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

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

  - None

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  - None

#### Inherited Protected Data

  - None