### IAPriorityQueue

  A priority queue is a key sorted bag with restricted access. It is an ordered collection of zero or more elements. Keys and multiple elements are supported. Element equality is not supported.

  When an element is added, it is placed in the queue according to its key value or priority. The highest priority is indicated by the lowest key value. You can remove the element with the highest priority. Within the priority queue, elements are sorted according to ascending key values, as in other key collections. You can only remove the element with the lowest key value.

  For elements with equal priority, the priority queue has a first-in, first-out behavior.

### IAPriorityQueue - Member Functions and Data by Group

### Constructors & Destructor

You can construct and destruct objects of this class.

~IAPriorityQueue

      public:
      ~IAPriorityQueue()

  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

IAPriorityQueue

  Overload 1

      public:
      IAPriorityQueue(INotifier&)

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

Supported Platforms

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

  Overload 2

      protected:
      IAPriorityQueue(IAPriorityQueue < 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:
      IAPriorityQueue()

  The default constructor.

Supported Platforms

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

### Comparison

Use these members to compare a collection with a given collection.

compare

      public:
      long
        compare( IAPriorityQueue < Element,
                 Key > const&,
                 long ( * comparisonFunction ) ( Element const & ,
                 Element const & ) ) const

  Compares the collection with the given collection. Comparison yields <0 if the collection is less than the given collection, 0 if the collection is equal to the given collection, and >0 if the collection is greater than the given collection. Comparison is defined by the first pair of corresponding elements, in both collections, that are not equal. If such a pair exists, the collection with the greater element is the greater one. Otherwise, the collection with more elements is the greater one.
  Note:

  1. The given comparison function must return a result according to the following rules:
     >0
       if (element1 > element2)
     0
       if (element1 == element2)
     <0
       if (element1 < element2)
  2. For elements of type char*, compare() is not locale-sensitive by default. Because it uses strcmp() and not strcoll(), it compares the binary values representing the characters, and is not based on the LC_COLLATE category of the current locale. Its results are reliable only for code pages and character sets in which the collating sequence matches the sequence of binary representations. If you need a comparison based on the LC_COLLATE cateogory, then you must implement your own compare() function as described in Using Separate Functions:elink. in the Class Library User's Guide.

  Return Value

  Returns the result of the collection comparison.

Supported Platforms

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

### Element Addition/Removal

Use these members to add, remove or reorder elements within a collection.

dequeue

  Copies the first element of the collection to the given element, and removes it from the collection.

  Precondition

  The collection must not be empty.

  Side Effects

  All cursors of this collection become undefined.

  Exception

  IEmptyException

  Overload 1

      public:
      virtual void dequeue()

Supported Platforms

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

  Overload 2

      public:
      virtual void dequeue(Element&)

Supported Platforms

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

enqueue

  Adds the element to the collection, and sets the cursor to the added element. For ordinary queues, the given element is added as the last element. For priority queues, the element is added at a position determined by the ordering relation provided for the element or key type.

  Preconditions

  - The cursor must belong to the collection.
  - If the collection is bounded, (numberOfElements() < maxNumberOfElements()).

  Side Effects

  All cursors of this collection except the given cursor become undefined.

  Exceptions

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

  Overload 1

      public:
      virtual void enqueue(Element const&, ICursor&)

Supported Platforms

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

  Overload 2

      public:
      virtual void enqueue(Element const&)

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 IAEqualitySequence::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, 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

removeFirst

      public:
      virtual void removeFirst()

  Removes the first element from the collection. Element destructors are called as described in IACollection::removeAt.

  Precondition

  The collection must not be empty.

  Side Effects

  All cursors of this collection become undefined.

  Exception

  IEmptyException

Supported Platforms

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

### Miscellaneous

Use these members to perform miscellaneous functions.

containsAllKeysFrom

      public:
      bool
        containsAllKeysFrom( IARestrictedAccessCollection < 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

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

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

  1. For the version of 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

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 key() function provided for the element type.

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

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

### IAPriorityQueue - Inherited Member Functions and Data

#### Inherited Public Functions

  IARestrictedAccessCollection

  -     virtual ~IARestrictedAccessCollection()

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

  -     virtual bool add(Element const&)

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

  -     void adoptStreamer(IACollectionStreamer*)

  -     bool allElementsDo(IConstantApplicator < Element >&) const

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

  -     Element const& any() const

  -     Element const& anyElement() const

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

  -     INotifier& disableNotification()

  -     Element const& elementAt(ICursor const&) const

  -     Element const& elementAtPosition(IPosition) const

  -     INotifier& enableNotification(bool = true)

  -     Element const& first() const

  -     Element const& firstElement() const

  -     IARestrictedAccessCollection(INotifier&)

  -     bool isBounded() const

  -     bool isConsistent() const

  -     bool isEmpty() const

  -     bool isEnabledForNotification() const

  -     bool isFirst(ICursor const&) const

  -     bool isFirstAt(ICursor const&) const

  -     bool isFull() const

  -     bool isLast(ICursor const&) const

  -     bool isLastAt(ICursor const&) const

  -     Element const& last() const

  -     Element const& lastElement() const

  -     INumber maxNumberOfElements() const

  -     virtual ICursor* newCursor() const

  -     INotifier const& notifier() const

  -     INotifier& notifier()

  -     INotifier& notifyObservers(INotificationEvent const&)

  -     INumber numberOfElements() const

  -     virtual void operator <<=(IDataStream&)

  -     virtual void operator >>=(IDataStream&)

  -     operator INotifier &() const

  -     IPosition position(ICursor const&) const

  -     IPosition positionAt(ICursor const&) const

  -     virtual INumber removeAll()

  -     bool setToFirst(ICursor&) const

  -     bool setToLast(ICursor&) const

  -     bool setToNext(ICursor&) const

  -     void setToPosition(IPosition, ICursor&) const

  -     bool setToPrevious(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 const&)

  -     IACollectionBase()

  -     static ICursor* InterfaceFor(ICursorImpl* cursor)

  IARestrictedAccessCollection

  -     IARestrictedAccessCollection()

  -     IARestrictedAccessCollection( IARestrictedAccessCollection < Element > const& )

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

#### Inherited Protected Data

  - None