### IATree

  A tree is a collection of nodes that can have an arbitrary number of references to other nodes. There can be no cycles or short-circuit references. A unique path connects every two nodes. One node is designated as the root of the tree.

### IATree - Member Functions and Data by Group

### Constructors & Destructor

Use these members to construct or destruct objects of the class.

~IATree

      public:
      ~IATree()

  Removes all elements from this tree.

  Side Effects

  All cursors of the tree become undefined.

Supported Platforms

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

IATree
  Construct or destruct an IATree object.

  Overload 1

      protected:
      IATree(IATree < Element > const&)

  Constructs a tree by copying all elements from the given tree.

  Exception

  IOutOfMemory

Supported Platforms

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

  Overload 2

      protected:
      IATree()

  Constructs a tree. The tree is initially empty; that is, it does not contain any nodes.

Supported Platforms

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

### Add or Remove Elements

Use these methods to add elements to or remove elements from the tree.

addAsChild

      public:
      void
        addAsChild( ITreeCursor const&,
                    IPosition,
                    Element const& )

  Adds the given element as a child with the given position to the node of this tree denoted by the given cursor.

  Preconditions

  - The cursor must point to an element of this tree.
  - (1 <= position <= numberOfChildren
  - The node denoted by the given cursor (of this tree) must not have a child at the given position.

  Exceptions

  - IOutOfMemoryException li.ICursorInvalidException li.IPositionInvalidException
  - IPositionAlreadyExistsException

Supported Platforms

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

addAsRoot

      public:
      void addAsRoot(Element const&)

  Adds the given element as root of the tree.

  Precondition

  The tree must not have a root; that is, it must be empty.

  Exceptions

  - IOutOfMemoryException. li.IRootAlreadyExistsException

Supported Platforms

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

removeAll

      public:
      INumber removeAll()

  Removes the subtree denoted by the given cursor (of this tree). The IACollection::removeAll function (without a cursor argument) removes all elements from this tree.

  Precondition

  The cursor must point to an element of this tree.

  Side Effects

  For removeSubtree, the given cursor is invalidated after removal.

  Exception

  ICursorInvalidException

Supported Platforms

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

removeSubtree

      public:
      INumber removeSubtree(ITreeCursor&)

  Removes the subtree denoted by the given cursor (of this tree). The IACollection::removeAll function (without a cursor argument) removes all elements from this tree.

  Precondition

  The cursor must point to an element of this tree.

  Side Effects

  For removeSubtree(), the given cursor is invalidated after removal.

  Exception

  ICursorInvalidException

Supported Platforms

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

replaceAt

      public:
      void replaceAt(ITreeCursor const&, Element const&)

  Replaces the element pointed to by the cursor with the given element.

  Precondition

  The cursor must point to an element of this tree.

  Exception

  ICursorInvalidException

Supported Platforms

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

### Collection Status

Use these methods to test the status of the collection.

isConsistent

      public:
      IBoolean isConsistent() const

  Internal method for testing consistency of collection.

Supported Platforms

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

isEmpty

      public:
      IBoolean isEmpty() const

  Returns true if the tree is empty.

Supported Platforms

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

numberOfElements

      public:
      INumber numberOfElements() const

  Returns the number of elements that the subtree denoted by the given cursor contains. The subtree root, inner, and leaf nodes are counted. The IACollection::numberOfElements function (without a cursor argument) counts the number of elements in the whole tree.

  Preconditions

  The cursor must belong to the tree and must point to an element in the tree.

  Exception

  ICursorInvalidException

Supported Platforms

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

numberOfLeaves

      public:
      INumber numberOfLeaves() const

  Returns the number of leaf elements that the subtree denoted by the given cursor contains. Leaves are nodes that have no children. The IATree::numberOfLeaves function (without a cursor argument) counts the number of leaves in the whole tree.

  Preconditions

  The cursor must belong to the tree and must point to an element in the tree.

  Exception

  ICursorInvalidException

Supported Platforms

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

numberOfSubtreeElements

      public:
      INumber numberOfSubtreeElements(ITreeCursor const&) const

  Returns the number of elements that the subtree denoted by the given cursor contains. The subtree root, inner, and leaf nodes are counted. The IACollection::numberOfElements function (without a cursor argument) counts the number of elements in the whole tree.

  Preconditions

  The cursor must belong to the tree and must point to an element in the tree.

  Exception

  ICursorInvalidException

Supported Platforms

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

numberOfSubtreeLeaves

      public:
      INumber numberOfSubtreeLeaves(ITreeCursor const&) const

  Returns the number of leaf elements that the subtree denoted by the given cursor contains. Leaves are nodes that have no children. The IATree::numberOfLeaves function (without a cursor argument) counts the number of leaves in the whole tree.

  Preconditions

  The cursor must belong to the tree and must point to an element in the tree.

  Exception

  ICursorInvalidException

Supported Platforms

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

### Cursor Support

These methods point a cursor at a particular element in the collection.

newCursor

      public:
      ITreeCursor* newCursor() const

  Creates a cursor for the tree. The cursor is initially invalid.

  Return Value

  Pointer to the cursor.

  Exception

  IOutOfMemory

Supported Platforms

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

setToChild

      public:
      IBoolean setToChild(IPosition, ITreeCursor&) const

  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

setToFirst

      public:
      IBoolean
        setToFirst( ITreeCursor&,
                    ITreeIterationOrder ) const

  Sets the cursor to the first node in the given iteration order. Invalidates the cursor if the tree is empty.

  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

setToFirstExistingChild

      public:
      IBoolean setToFirstExistingChild(ITreeCursor&) const

  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

setToLast

      public:
      IBoolean setToLast(ITreeCursor&, ITreeIterationOrder) const

  Sets the cursor to the last node in the given iteration order. Invalidates the cursor if the tree is empty.

  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

setToLastExistingChild

      public:
      IBoolean setToLastExistingChild(ITreeCursor&) const

  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

setToNext

      public:
      IBoolean setToNext(ITreeCursor&, ITreeIterationOrder) const

  Sets the cursor to the next node in the given iteration order. Invalidates the cursor if there is no next node.

  Precondition

  The cursor must point to an element of this tree.

  Return Value

  Returns true if the given cursor does not point to the last node (in iteration order).

  Exception

  ICursorInvalidException

Supported Platforms

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

setToNextExistingChild

      public:
      IBoolean setToNextExistingChild(ITreeCursor&) const

  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:
      IBoolean setToParent(ITreeCursor&) const

  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

setToPrevious

      public:
      IBoolean
        setToPrevious( ITreeCursor&,
                       ITreeIterationOrder ) const

  Sets the cursor to the previous node in the given iteration order. Invalidates the cursor if there is no previous node.

  Precondition

  The cursor must point to an element of this tree.

  Return Value

  Returns true if the given cursor does not point to the first node (in iteration order).

  Exception

  ICursorInvalidException

Supported Platforms

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

setToPreviousExistingChild

      public:
      IBoolean setToPreviousExistingChild(ITreeCursor&) const

  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:
      IBoolean setToRoot(ITreeCursor&) const

  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

### Do For All Elements

These methods apply actions to all the elements of the tree collection or any subtree of the collection.

allElementsDo
  These methods will apply an action to each element in the collection.

  Overload 1

      public:
      IBoolean
        allElementsDo( IApplicator < Element >&,
                       ITreeIterationOrder )

  Calls the applyTo() function of the given applicator for all elements of the subtree denoted by the given cursor (of this tree) until the apply To() function returns false. The elements are visited in iteration order. The allElementsDo() function returns (without a subtree cursor argument) iterates over all elements of the tree.
  Note:

  - The applyTo() function must not remove elements from or add them to the tree.

    Preconditions

    - The cursor must belong to this tree.
    - the cursor must point to an element of this tree.

    Return Value Returns true if the applyTo() function returns true for every element it is applied to.

    Exceptions

  - ICursorInvalidException.

Supported Platforms

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

  Overload 2

      public:
      IBoolean
        allElementsDo( IBoolean ( * applicatorFunction ) ( Element const&,
                        void * ),
                       ITreeIterationOrder ,
                       void* additionalArgument = 0 ) const

  Calls the given function for all elements of the subtree denoted by the given cursor (of this tree) until the given function returns false. The elements are visited in the given iteration order. Additional arguments can be passed to the given function using additionalArgument. The additional argument defaults to zero if no additional argument is given. The allElementsDo() function (without a subtree cursor argument) iterates over all elements of the tree.
  Note: The given function must not remove elements from or add elements to the tree.

  Return Value

  Returns true if the given function returns true for every element it is applied to.

  Preconditions

  - The cursor must belong to this tree.
  - The cursor must point to an element of this tree.

  Exception

  ICursorInvalidException

Supported Platforms

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

  Overload 3

      public:
      IBoolean
        allElementsDo( IConstantApplicator < Element >&,
                       ITreeIterationOrder ) const

  Calls the applyTo() function of the given applicator for all elements of the subtree denoted by the given cursor (of this tree) until the apply To() function returns false. The elements are visited in iteration order. The allElementsDo() function returns (without a subtree cursor argument) iterates over all elements of the tree.
  Note:

  - The applyTo() function must not remove elements from or add them to the tree.

    Preconditions

    - The cursor must belong to this tree.
    - the cursor must point to an element of this tree.

      Return Value

      Returns true if the applyTo() function returns true for every element it is applied to.

      Exceptions

    - ICursorInvalidException.

Supported Platforms

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

  Overload 4

      public:
      IBoolean
        allElementsDo( IBoolean ( * applicatorFunction ) ( Element&,
                        void * ),
                       ITreeIterationOrder ,
                       void* additionalArgument = 0 )

  Calls the given function for all elements of the subtree denoted by the given cursor (of this tree) until the given function returns false. The elements are visited in the given iteration order. Additional arguments can be passed to the given function using additionalArgument. The additional argument defaults to zero if no additional argument is given. The allElementsDo() function (without a subtree cursor argument) iterates over all elements of the tree.
  Note: The given function must not remove elements from or add elements to the tree.

  Return Value

  Returns true if the given function returns true for every element it is applied to.

  Preconditions

  - The cursor must belong to this tree.
  - The cursor must point to an element of this tree.

  Exception

  ICursorInvalidException

Supported Platforms

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

allSubtreeElementsDo
  Applies an action to all of the elements of a particular subtree of the tree.

  Overload 1

      public:
      IBoolean
        allSubtreeElementsDo( ITreeCursor const&,
                              IConstantApplicator < Element >&,
                              ITreeIterationOrder ) const

  Calls the applyTo() function of the given applicator for all elements of the subtree denoted by the given cursor (of this tree) until the apply To() function returns false. The elements are visited in iteration order. The allElementsDo() function returns (without a subtree cursor argument) iterates over all elements of the tree.
  Note:

  - The applyTo() function must not remove elements from or add them to the tree.

    Preconditions

    - The cursor must belong to this tree.
    - the cursor must point to an element of this tree.

      Return Value

      Returns true if the applyTo() function returns true for every element it is applied to.

      Exceptions

    - ICursorInvalidException.

Supported Platforms

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

  Overload 2

      public:
      IBoolean
        allSubtreeElementsDo( ITreeCursor const&,
                              IBoolean ( * applicatorFunction ) ( Element&,
                               void * ),
                              ITreeIterationOrder ,
                              void* additionalArgument = 0 )

  Calls the given function for all elements of the subtree denoted by the given cursor (of this tree) until the given function returns false. The elements are visited in the given iteration order. Additional arguments can be passed to the given function using additionalArgument. The additional argument defaults to zero if no additional argument is given. The allElementsDo() function (without a subtree cursor argument) iterates over all elements of the tree.
  Note: The given function must not remove elements from or add elements to the tree.

  Return Value

  Returns true if the given function returns true for every element it is applied to.

  Preconditions

  - The cursor must belong to this tree.
  - The cursor must point to an element of this tree.

  Exception

  ICursorInvalidException

Supported Platforms

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

  Overload 3

      public:
      IBoolean
        allSubtreeElementsDo( ITreeCursor const&,
                              IBoolean ( * applicatorFunction ) ( Element const&,
                               void * ),
                              ITreeIterationOrder ,
                              void* additionalArgument = 0 ) const

  Calls the given function for all elements of the subtree denoted by the given cursor (of this tree) until the given function returns false. The elements are visited in the given iteration order. Additional arguments can be passed to the given function using additionalArgument. The additional argument defaults to zero if no additional argument is given. The allElementsDo() function (without a subtree cursor argument) iterates over all elements of the tree.
  Note: The given function must not remove elements from or add elements to the tree.

  Return Value

  Returns true if the given function returns true for every element it is applied to.

  Preconditions

  - The cursor must belong to this tree.
  - The cursor must point to an element of this tree.

  Exception

  ICursorInvalidException

Supported Platforms

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

  Overload 4

      public:
      IBoolean
        allSubtreeElementsDo( ITreeCursor const&,
                              IApplicator < Element >&,
                              ITreeIterationOrder )

  Calls the applyTo() function of the given applicator for all elements of the subtree denoted by the given cursor (of this tree) until the apply To() function returns false. The elements are visited in iteration order. The allElementsDo() function returns (without a subtree cursor argument) iterates over all elements of the tree.
  Note:

  - The applyTo() function must not remove elements from or add them to the tree.

    Preconditions

    - The cursor must belong to this tree.
    - the cursor must point to an element of this tree.

      Return Value

      Returns true if the applyTo() function returns true for every element it is applied to.

      Exceptions

    - ICursorInvalidException.

Supported Platforms

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

### Element Access

Use these methods to access the elements of the collection.

elementAt
  Returns a reference to the element pointed to by the given cursor.

  Precondition

  The cursor must point to an element of this tree.

  Exception

  ICursorInvalidException

  Overload 1

      public:
      Element const& elementAt(ITreeCursor const&) const

Supported Platforms

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

  Overload 2

      public:
      Element& elementAt(ITreeCursor const&)

Supported Platforms

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

### Element Testing

Use these methods to test elements to see if they are leaf or root nodes.

childPositionAt

      public:
      IPosition childPositionAt(ITreeCursor const&) const

  Returns the position of the node pointed to by the given cursor as a child with respect to its parent node. The position of the root node is 1.

  Precondition

  The cursor must point to an element of this tree.

  Exception

  ICursorInvalidException

Supported Platforms

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

isLeaf

      public:
      IBoolean isLeaf(ITreeCursor const&) const

  Returns true if the node pointed to by the given cursor is a leaf node of the tree. A leaf node is a node with no children.

  Precondition

  The cursor must point to an element of this tree.

  Exception

  ICursorInvalidException

Supported Platforms

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

isRoot

      public:
      IBoolean isRoot(ITreeCursor const&) const

  Returns true if the node pointed to by the given cursor is the root node of the tree.

  Precondition

  The cursor must point to an element of this tree.

  Exception

  ICursorInvalidException

Supported Platforms

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

position

      public:
      IPosition position(ITreeCursor const&) const

  Returns the position of the node pointed to by the given cursor as a child with respect to its parent node. The position of the root node is 1.

  Precondition

  The cursor must point to an element of this tree.

  Exception

  ICursorInvalidException

Supported Platforms

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

### Streaming Support

These methods support streaming of elements to and from data streams.

adoptStreamer

      public:
      void adoptStreamer(IACollectionStreamer*)

  This method adopts a streamer object which is used to handle element streaming to and from a data stream.

Supported Platforms

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

operator <<=

      public:
      void operator <<=(IDataStream&)

  Streams in the stored elements to this collection. The adopted streamer object is used to do the streaming.

Supported Platforms

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

operator >>=

      public:
      void operator >>=(IDataStream&)

  Streams the elements of this collection out to the passed data stream. The adopted streamer object is used to do the element streaming.

Supported Platforms

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

### IATree - Inherited Member Functions and Data

#### Inherited Public Functions

  - None

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  IATreeBase

  -     ~IATreeBase()

  -     static ITreeCursorImpl& CrsrImplOf(ITreeCursor& cursor)

  -     static ITreeCursorImpl const&
          CrsrImplOf( ITreeCursor const& cursor )

  -     IATreeBase()

  -     IATreeBase(IATreeBase const&)

  -     static ITreeCursor* InterfaceFor(ITreeCursorImpl* cursor)

  IATree

  -     static Implementation& ImplOf(IATree < Element > const&)

#### Inherited Protected Data

  - None