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.


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


[view class]
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.


[view class]
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

Exceptions

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
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


[view class]
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


[view class]
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.


[view class]
isConsistent
public:
IBoolean isConsistent() const
Internal method for testing consistency of collection.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isEmpty
public:
IBoolean isEmpty() const
Returns true if the tree is empty.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
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


[view class]
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


[view class]
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


[view class]
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.


[view class]
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


[view class]
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

Return Value

Returns true if the child exists.

Exceptions

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
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


[view class]
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


[view class]
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


[view class]
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


[view class]
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


[view class]
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


[view class]
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


[view class]
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


[view class]
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


[view class]
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.


[view class]
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

    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

    Exception

    ICursorInvalidException

    Supported Platforms

    Windows OS/2 AIX
    Yes Yes Yes


    [view class]
    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

    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

    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.


    [view class]
    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.


    [view class]
    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


    [view class]
    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


    [view class]
    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


    [view class]
    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.


    [view class]
    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


    [view class]
    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


    [view class]
    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

    Inherited Public Data

    Inherited Protected Functions

    IATreeBase
    IATree

    Inherited Protected Data