### IAKeyCollection

  Because key collection is an abstract class, it cannot be used to create any objects. The key collection inherits from collection and defines the interfaces for the key property.

### IAKeyCollection - Member Functions and Data by Group

### Constructors & Destructor

You can construct and destruct objects of this class.

~IAKeyCollection

      public:
      ~IAKeyCollection()

  Removes all elements from the collection. Destructors are called for all elements contained in the collection and for elements that have been constructed in advance.

  Side Effects

  All cursors of the collection become undefined.

Supported Platforms

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

IAKeyCollection

  Overload 1

      public:
      IAKeyCollection(INotifier&)

  Use this constructor to create a collection with support for notification.

Supported Platforms

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

  Overload 2

      protected:
      IAKeyCollection(IAKeyCollection < Element, Key > const&)

  Constructs a collection. The collection is unbounded and is initially empty.
  Note: The collection constructor does not define whether any elements are constructed when the collection is constructed. For some classes, the element's default constructor may be invoked when the collection's constructor is invoked. This happens if a tabular or a diluted sequence implementation variant is used for a collection. The element's default constructor is used to allocate the required storage and initialize the elements. Therefore, a default constructor must be available for elements in such cases.

  Exception

  IOutOfMemory

Supported Platforms

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

  Overload 3

      protected:
      IAKeyCollection()

  The default constructor.

Supported Platforms

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

### Miscellaneous

Use these members to execute miscellaneous operations.

addOrReplaceElementWithKey

  If an element is contained in the collection where the key is equal to the key of the given element, sets the cursor to this element in the collection and replaces it with the given element. Otherwise, it adds the given element to the collection, and sets the cursor to the added element. If the given element is added, the contents of the element, not a pointer to it, is added.

  Preconditions

  - The cursor must belong to the collection.
  - If the collection is bounded, an element with the given key must be contained in the collection, or (numberOfElements() < maxNumberOfElements()).

  Side Effects

  If the element was added, all cursors of this collection, except the given cursor, become undefined.

  Return Value

  Returns true if the element was added. Returns false if the element was replaced.

  Exceptions

  IOutOfMemory

  ICursorInvalidException

  IFullException, if the collection is bounded

  Overload 1

      public:
      virtual bool addOrReplaceElementWithKey(Element const&)

Supported Platforms

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

  Overload 2

      public:
      virtual bool
        addOrReplaceElementWithKey( Element const&,
                                    ICursor& )

Supported Platforms

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

containsAllKeysFrom

      public:
      bool
        containsAllKeysFrom( IACollection < Element > const& ) const

  Returns true if all of the keys of the given collection are contained in the collection.

Supported Platforms

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

containsElementWithKey

      public:
      bool containsElementWithKey(Key const&) const

  Returns true if the collection contains an element with the same key as the given key.

Supported Platforms

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

elementWithKey

  Returns a reference to an element specified by the key.
  Note:

  1. For the version of IAKeyCollection::elementWithKey without a const suffix, do not manipulate the element in the collection in a way that changes the positioning property of the element.
  2. If there are several elements with the given key, an arbitrary one is returned.

  Precondition

  The given key is contained in the collection.

  Exception

  INotContainsKeyException

  Overload 1

      public:
      Element& elementWithKey(Key const&)

Supported Platforms

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

  Overload 2

      public:
      Element const& elementWithKey(Key const&) const

Supported Platforms

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

key

      public:
      Key const& key(Element const&) const

  Returns a reference to the key of the given element using the IAKeyCollection::key function provided for the element type.

Supported Platforms

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

locateElementWithKey

      public:
      bool locateElementWithKey(Key const&, ICursor&) const

  Locates an element in the collection with the same key as the given key. Sets the cursor to point to the element in the collection, or invalidates the cursor if no such element exists.

  If the collection contains several such elements, the first element in iteration order is located.

  Precondition

  The cursor must belong to the collection.

  Return Value

  Returns true if an element was found.

  Exception

  ICursorInvalidException

Supported Platforms

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

locateNextElementWithKey

      public:
      bool locateNextElementWithKey(Key const&, ICursor&) const

  Locates the next element in iteration order in the collection with the given key, starting at the element next to the one pointed to by the given cursor. Sets the cursor to point to the element in the collection. The cursor is invalidated if the end of the collection is reached and no more occurrences of such an element are left to be visited.
  Note: If you code a call to IACollection::locateFirst and a set of calls to locateNextElementWithKey(), each occurrence of an element will be visited exactly once in iteration order.

  Preconditions

  The cursor must belong to the collection and must point to an element of the collection.

  Return Value

  Returns true if an element was found.

  Exception

  ICursorInvalidException

Supported Platforms

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

locateOrAddElementWithKey

  Locates an element in the collection with the given key as described for the IACollection::locateElementWithKey function. If no such element exists, IACollection::locateOrAddElementWithKey adds the element as described in IACollection::add. The cursor is set to the located or added element.

  Preconditions

  - If the collection is bounded and an element with the given key is not already contained, (numberOfElements() < maxNumberOfElements()).
  - The cursor must belong to the collection.

  Side Effects

  If the element was added, all cursors of this collection, except the given cursor, become undefined.

  Return Value

  Returns true if the element was located. Returns false if the element could not be located but had to be added.

  Exceptions

  - IOutOfMemory
  - ICursorInvalidException
  - IFullException, if the collection is bounded

  Overload 1

      public:
      virtual bool
        locateOrAddElementWithKey( Element const&,
                                   ICursor& )

Supported Platforms

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

  Overload 2

      public:
      virtual bool locateOrAddElementWithKey(Element const&)

Supported Platforms

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

numberOfDifferentKeys

      public:
      INumber numberOfDifferentKeys() const

  Returns the number of different keys in the collection.

Supported Platforms

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

numberOfElementsWithKey

      public:
      INumber numberOfElementsWithKey(Key const&) const

  Returns the number of elements in the collection with the given key.

Supported Platforms

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

removeAllElementsWithKey

      public:
      virtual INumber removeAllElementsWithKey(Key const&)

  Removes all elements from the collection with the same key as the given key. Element destructors are called as described in IACollection::removeAt.

  Side Effects

  If any elements were removed, all cursors of this collection become undefined.

  Return Value

  The number of elements removed.

Supported Platforms

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

removeElementWithKey

      public:
      virtual bool removeElementWithKey(Key const&)

  Removes an element from the collection with the same key as the given key. If no such element exists, the collection remains unchanged. In collections with nonunique elements, an arbitrary occurrence of such an element will be removed. Element destructors are called as described in IAc Collection::removeAt:eref..

  Side Effects

  If an element was removed, all cursors of this collection become undefined.

  Return Value

  Returns true if an element was removed.

Supported Platforms

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

replaceElementWithKey

  Replaces an element with the same key as the given element by the given element, and sets the cursor to this element. If no such element exists, it invalidates the cursor. In collections with nonunique elements, an arbitrary occurrence of such an element will be replaced.

  Precondition

  The cursor must belong to the collection.

  Return Value

  Returns true if an element was replaced.

  Exceptions

  ICursorInvalidException

  Overload 1

      public:
      virtual bool
        replaceElementWithKey( Element const&,
                               ICursor& )

Supported Platforms

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

  Overload 2

      public:
      virtual bool replaceElementWithKey(Element const&)

Supported Platforms

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

setToNextWithDifferentKey

      public:
      bool setToNextWithDifferentKey(ICursor&) const

  Sets the cursor to the next element in the collection in iteration order with a key different from the key of the element pointed to by the given cursor. If no such element exists, the given cursor is no longer valid.

  Preconditions

  The cursor must belong to the collection and must point to an element of the collection.

  Return Value

  Returns true if a subsequent element was found whose key is different from the current key.

  Exception

  ICursorInvalidException

Supported Platforms

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

### IAKeyCollection - Inherited Member Functions and Data

#### Inherited Public Functions

  IACollection

  -     virtual ~IACollection()

  -     virtual bool add(Element const&, ICursor&)

  -     virtual bool add(Element const&)

  -     virtual void addAllFrom(IACollection < Element > const&)

  -     void adoptStreamer(IACollectionStreamer*)

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

  -     bool allElementsDo(IConstantApplicator < Element >&) const

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

  -     bool allElementsDo(IApplicator < Element >&)

  -     Element const& any() const

  -     Element const& anyElement() const

  -     virtual void copy(IACollection < Element > const&)

  -     INotifier& disableNotification()

  -     Element const& elementAt(ICursor const&) const

  -     Element& elementAt(ICursor const&)

  -     INotifier& enableNotification(bool = true)

  -     IACollection(INotifier&)

  -     bool isBounded() const

  -     bool isConsistent() const

  -     bool isEmpty() const

  -     bool isEnabledForNotification() const

  -     bool isFull() const

  -     INumber maxNumberOfElements() const

  -     virtual ICursor* newCursor() const

  -     ICursor* newMngCursor() const

  -     INotifier& notifier()

  -     INotifier const& notifier() const

  -     INotifier& notifyObservers(INotificationEvent const&)

  -     INumber numberOfElements() const

  -     virtual void operator <<=(IDataStream&)

  -     virtual void operator >>=(IDataStream&)

  -     operator INotifier &() const

  -     virtual INumber
          removeAll( bool ( * predicateFunction ) ( Element const&,
                     void * ) , void* additionalArgument = 0 )

  -     virtual INumber removeAll()

  -     virtual void removeAt(ICursor&)

  -     virtual void replaceAt(ICursor const&, Element const&)

  -     bool setToFirst(ICursor&) const

  -     bool setToNext(ICursor&) const

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  IACollectionBase

  -     ~IACollectionBase()

  -     static ICursorImpl const& CrsrImplOf(ICursor const& cursor)

  -     static ICursorImpl& CrsrImplOf(ICursor& cursor)

  -     IACollectionBase()

  -     IACollectionBase(IACollectionBase const&)

  -     static ICursor* InterfaceFor(ICursorImpl* cursor)

  IACollection

  -     IACollection(IACollection < Element > const&)

  -     IACollection()

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

#### Inherited Protected Data

  - None