### IAMultiwayTree

  A multiway tree, also known as an n-ary tree, is a special tree where each node can have up to n children.

  n must be greater than one. If n is one, the tree is a list. If n is zero, the structure loses its meaning.

  An example of using an multiway tree is a program used to build a family tree. (For simplicity, assume that the family tree is not concerned with information about spouses.) Whenever you discover a relative who is not already in your family tree, you enter the relative's name. If you know the parent's name, and the parent is already in the collection, the new relative is added as a child of the existing parent. If the parent is known but is not in the collection, a new collection is created, with the parent as the root element and the child as a child node of the parent. If you do not know the parent, the relative is entered as the root element of a new collection. You can also enter information about the children of a given relative; this information is used to attach a subtree, whose root node is the child, to the node of the parent of that child. Once you have established the collection, you can determine who is the parent or oldest known ancestor of a given relative, and you can display a list of all descendents of a given family member.

### IAMultiwayTree - Member Functions and Data by Group

### Constructors & Destructor

Use these members to construct objects of the class.

IAMultiwayTree

  Overload 1

      protected:
      IAMultiwayTree( IAMultiwayTree < numOfChildren,
                      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:
      IAMultiwayTree()

  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

### Miscellaneous

Use these members to execute miscellaneous tasks.

attachAsChild

      public:
      void
        attachAsChild( ITreeCursor const&,
                       IPosition,
                       IAMultiwayTree < numOfChildren,
                       Element > const& )

  Copies the subtree denoted by the given subtree cursor as a child with the given position of the node (of this tree) denoted by the given cursor. Removes this subtree from the given tree. The attachAsChild() function (without a subtree cursor argument) copies and removes the whole given tree.

  Be careful when this tree and the given tree are the same. In such cases you must not attach a subtree to one of its own children, because a cyclic tree structure would result. Because attachSubtreeAsChild() removes this subtree from this tree, you will never be able to access either this subtree or the given subtree attached to it. This practice can also lead to memory not being properly freed.

  This warning applies to both attachAsChild() and attachSubtreeAsChild().
  Note: These functions are implemented by copying a pointer to the subtree, rather than by copying all elements in the subtree.

  Preconditions

  - The cursor must point to an element of this tree.
  - The subtree cursor must point to an element of the given tree.
  - (1 <= position <= numberOfChildren).
  - The node denoted by the given cursor (of this tree) must not have a child at the given position.
  - If this tree and the given tree are the same, a subtree must not be attached to one of its own children.

  Exceptions

  - ICursorInvalidException
  - IPositionInvalidException
  - IChildAlreadyExistsException
  - ICyclicAttachException

Supported Platforms

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

attachAsRoot

      public:
      void
        attachAsRoot( IAMultiwayTree < numOfChildren,
                      Element > const& )

  Copies the subtree denoted by the cursor of the given tree to (the root of) this tree, and removes this subtree from the given tree. The attachAsRoot() function (without a cursor argument) copies and removes the whole given tree.
  Note: These functions are implemented by copying a pointer to the subtree, rather than by copying all elements in the subtree.

  Preconditions

  - The cursor must point to an element of this tree.
  - The tree must not have a root; that is, it must be empty.

  Exceptions

  - ICursorInvalidException
  - IRootAlreadyExistsException

Supported Platforms

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

attachSubtreeAsChild

      public:
      void
        attachSubtreeAsChild( ITreeCursor const&,
                              IPosition,
                              IAMultiwayTree < numOfChildren,
                              Element > const&,
                              ITreeCursor const& )

  Copies the subtree denoted by the given subtree cursor as a child with the given position of the node (of this tree) denoted by the given cursor. Removes this subtree from the given tree. The attachAsChild() function (without a subtree cursor argument) copies and removes the whole given tree.

  Be careful when this tree and the given tree are the same. In such cases you must not attach a subtree to one of its own children, because a cyclic tree structure would result. Because attachSubtreeAsChild() removes this subtree from this tree, you will never be able to access either this subtree or the given subtree attached to it. This practice can also lead to memory not being properly freed.

  This warning applies to both attachAsChild() and attachSubtreeAsChild().
  Note: These functions are implemented by copying a pointer to the subtree, rather than by copying all elements in the subtree.

  Preconditions

  - The cursor must point to an element of this tree.
  - The subtree cursor must point to an element of the given tree.
  - (1 <= position <= numberOfChildren:).
  - The node denoted by the given cursor (of this tree) must not have a child at the given position.
  - If this tree and the given tree are the same, a subtree must not be attached to one of its own children.

  Exceptions

  - ICursorInvalidException
  - IPositionInvalidException
  - IChildAlreadyExistsException
  - ICyclicAttachException

Supported Platforms

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

attachSubtreeAsRoot

      public:
      void
        attachSubtreeAsRoot( IAMultiwayTree < numOfChildren,
                             Element > const&,
                             ITreeCursor const& )

  Copies the subtree denoted by the cursor of the given tree to (the root of) this tree, and removes this subtree from the given tree. The attachAsRoot() function (without a cursor argument) copies and removes the whole given tree.
  Note: These functions are implemented by copying a pointer to the subtree, rather than by copying all elements in the subtree.

  Preconditions

  - The cursor must point to an element of this tree.
  - The tree must not have a root; that is, it must be empty.

  Exceptions

  - ICursorInvalidException
  - IRootAlreadyExistsException

Supported Platforms

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

copy

      public:
      void copy(IAMultiwayTree < numOfChildren, Element > 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

copySubtree

      public:
      void
        copySubtree( IAMultiwayTree < numOfChildren,
                     Element > const&,
                     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

hasChild

      public:
      bool hasChild(IPosition, ITreeCursor const&) const

  Returns true if the node pointed to by the given cursor has a child at the given position.

  Preconditions

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

  Exceptions

  - ICursorInvalidException
  - IPositionInvalidException

Supported Platforms

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

numberOfChildren

      public:
      INumber numberOfChildren() const

  Returns the number of children a node can possibly have. The actual number of children of any node will always be less than or equal to this number.

Supported Platforms

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

### IAMultiwayTree - Inherited Member Functions and Data

#### Inherited Public Functions

  IATree

  -     ~IATree()

  -     void
          addAsChild( ITreeCursor const&,
                      IPosition,
                      Element const& )

  -     void addAsRoot(Element const&)

  -     void adoptStreamer(IACollectionStreamer*)

  -     IBoolean
          allElementsDo( IApplicator < Element >&,
                         ITreeIterationOrder )

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

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

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

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

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

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

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

  -     IPosition childPositionAt(ITreeCursor const&) const

  -     Element& elementAt(ITreeCursor const&)

  -     Element const& elementAt(ITreeCursor const&) const

  -     IBoolean isConsistent() const

  -     IBoolean isEmpty() const

  -     IBoolean isLeaf(ITreeCursor const&) const

  -     IBoolean isRoot(ITreeCursor const&) const

  -     ITreeCursor* newCursor() const

  -     INumber numberOfElements() const

  -     INumber numberOfLeaves() const

  -     INumber numberOfSubtreeElements(ITreeCursor const&) const

  -     INumber numberOfSubtreeLeaves(ITreeCursor const&) const

  -     void operator <<=(IDataStream&)

  -     void operator >>=(IDataStream&)

  -     IPosition position(ITreeCursor const&) const

  -     INumber removeAll()

  -     INumber removeSubtree(ITreeCursor&)

  -     void replaceAt(ITreeCursor const&, Element const&)

  -     IBoolean setToChild(IPosition, ITreeCursor&) const

  -     IBoolean
          setToFirst( ITreeCursor&,
                      ITreeIterationOrder ) const

  -     IBoolean setToFirstExistingChild(ITreeCursor&) const

  -     IBoolean setToLast(ITreeCursor&, ITreeIterationOrder) const

  -     IBoolean setToLastExistingChild(ITreeCursor&) const

  -     IBoolean setToNext(ITreeCursor&, ITreeIterationOrder) const

  -     IBoolean setToNextExistingChild(ITreeCursor&) const

  -     IBoolean setToParent(ITreeCursor&) const

  -     IBoolean
          setToPrevious( ITreeCursor&,
                         ITreeIterationOrder ) const

  -     IBoolean setToPreviousExistingChild(ITreeCursor&) const

  -     IBoolean setToRoot(ITreeCursor&) const

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  IATreeBase

  -     ~IATreeBase()

  -     static ITreeCursorImpl& CrsrImplOf(ITreeCursor& cursor)

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

  -     IATreeBase(IATreeBase const&)

  -     IATreeBase()

  -     static ITreeCursor* InterfaceFor(ITreeCursorImpl* cursor)

  IATree

  -     IATree()

  -     IATree(IATree < Element > const&)

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

#### Inherited Protected Data

  - None