# Class PriorityQueue<E>

java.lang.Object
java.util.AbstractCollection<E>
java.util.AbstractQueue<E>
java.util.PriorityQueue<E>

All Implemented Interfaces:
  `Iterable<E>, Collection<E>, Queue<E>`

public class PriorityQueue<E> extends AbstractQueue<E>
A PriorityQueue holds elements on a priority heap, which orders the elements according to their natural order or according to the comparator specified at construction time. If the queue uses natural ordering, only elements that are comparable are permitted to be inserted into the queue.

The least element of the specified ordering is stored at the head of the queue and the greatest element is stored at the tail of the queue.

A PriorityQueue is not synchronized. If multiple threads will have to access it concurrently, use the `PriorityBlockingQueue`.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `PriorityQueue()`
  Constructs a priority queue with an initial capacity of 11 and natural ordering.
  `PriorityQueue(int initialCapacity)`
  Constructs a priority queue with the specified capacity and natural ordering.
  `PriorityQueue(int initialCapacity, Comparator<? super E> comparator)`
  Constructs a priority queue with the specified capacity and comparator.
  `PriorityQueue(Collection<? extends E> c)`
  Constructs a priority queue that contains the elements of a collection.
  `PriorityQueue(PriorityQueue<? extends E> c)`
  Constructs a priority queue that contains the elements of another priority queue.
  `PriorityQueue(SortedSet<? extends E> c)`
  Constructs a priority queue that contains the elements of a sorted set.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `add(E o)`
  Adds the specified object to the priority queue.
  `void`
  `clear()`
  Removes all the elements of the priority queue.
  `Comparator<? super E>`
  `comparator()`
  Gets the comparator of the priority queue.
  `boolean`
  `contains(Object object)`
  Answers if there is an element in this queue equals to the object.
  `Iterator<E>`
  `iterator()`
  Gets the iterator of the priority queue, which will not return elements in any specified ordering.
  `boolean`
  `offer(E o)`
  Inserts the element to the priority queue.
  `E`
  `peek()`
  Gets but does not remove the head of the queue.
  `E`
  `poll()`
  Gets and removes the head of the queue.
  `boolean`
  `remove(Object o)`
  Removes the specified object from the priority queue.
  `int`
  `size()`
  Gets the size of the priority queue.
  `Object[]`
  `toArray()`
  Returns all the elements in an array.
  `<T> T[]`
  `toArray(T[] array)`
  Returns all the elements in an array, and the type of the result array is the type of the argument array.

  ### Methods inherited from class AbstractQueue

  `addAll, element, remove`
  Modifier and Type
  Method
  Description
  `boolean`
  `addAll(Collection<? extends E> c)`
  Adds all the elements of a collection to the queue.
  `E`
  `element()`
  Returns but does not remove the element at the head of the queue.
  `E`
  `remove()`
  Removes the element at the head of the queue and returns it.

  ### Methods inherited from class AbstractCollection

  `containsAll, isEmpty, removeAll, retainAll, toString`
  Modifier and Type
  Method
  Description
  `boolean`
  `containsAll(Collection<?> collection)`
  Tests whether this `Collection` contains all objects contained in the specified `Collection`.
  `boolean`
  `isEmpty()`
  Returns if this `Collection` contains no elements.
  `boolean`
  `removeAll(Collection<?> collection)`
  Removes all occurrences in this `Collection` of each object in the specified `Collection` (optional).
  `boolean`
  `retainAll(Collection<?> collection)`
  Removes all objects from this `Collection` that are not also found in the `Collection` passed (optional).
  `String`
  `toString()`
  Returns the string representation of this `Collection`.

  ### Methods inherited from class Object

  `clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`
  Modifier and Type
  Method
  Description
  `protected Object`
  `clone()`
  `boolean`
  `equals(Object obj)`
  Indicates whether some other object is "equal to" this one.
  `final Class`
  `getClass()`
  Returns the runtime class of an object.
  `int`
  `hashCode()`
  Returns a hash code value for the object.
  `final void`
  `notify()`
  Wakes up a single thread that is waiting on this object's monitor.
  `final void`
  `notifyAll()`
  Wakes up all threads that are waiting on this object's monitor.
  `final void`
  `wait()`
  Causes current thread to wait until another thread invokes the method or the method for this object.
  `final void`
  `wait(long timeout)`
  Causes current thread to wait until either another thread invokes the method or the method for this object, or a specified amount of time has elapsed.
  `final void`
  `wait(long timeout, int nanos)`
  Causes current thread to wait until another thread invokes the method or the method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed.

  ### Methods inherited from interface Collection

  `equals, hashCode`
  Modifier and Type
  Method
  Description
  `boolean`
  `equals(Object object)`
  Compares the argument to the receiver, and returns true if they represent the same object using a class specific comparison.
  `int`
  `hashCode()`
  Returns an integer hash code for the receiver.

- ## Constructor Details

  - ### PriorityQueue

    public PriorityQueue()
    Constructs a priority queue with an initial capacity of 11 and natural ordering.

  - ### PriorityQueue

    public PriorityQueue(int initialCapacity)
    Constructs a priority queue with the specified capacity and natural ordering.
    Parameters:
      `initialCapacity` - the specified capacity.
    Throws:
      `IllegalArgumentException` - if the initialCapacity is less than 1.

  - ### PriorityQueue

    public PriorityQueue(int initialCapacity, Comparator<? super E> comparator)
    Constructs a priority queue with the specified capacity and comparator.
    Parameters:
      `initialCapacity` - the specified capacity.
      `comparator` - the specified comparator. If it is null, the natural ordering will be used.
    Throws:
      `IllegalArgumentException` - if the initialCapacity is less than 1.

  - ### PriorityQueue

    public PriorityQueue(Collection<? extends E> c)
    Constructs a priority queue that contains the elements of a collection. The constructed priority queue has the initial capacity of 110% of the size of the collection. The queue uses natural ordering to order its elements.
    Parameters:
      `c` - the collection whose elements will be added to the priority queue to be constructed.
    Throws:
      `ClassCastException` - if any of the elements in the collection are not comparable.
      `NullPointerException` - if any of the elements in the collection are null.

  - ### PriorityQueue

    public PriorityQueue(PriorityQueue<? extends E> c)
    Constructs a priority queue that contains the elements of another priority queue. The constructed priority queue has the initial capacity of 110% of the specified one. Both priority queues have the same comparator.
    Parameters:
      `c` - the priority queue whose elements will be added to the priority queue to be constructed.

  - ### PriorityQueue

    public PriorityQueue(SortedSet<? extends E> c)
    Constructs a priority queue that contains the elements of a sorted set. The constructed priority queue has the initial capacity of 110% of the size of the sorted set. The priority queue will have the same comparator as the sorted set.
    Parameters:
      `c` - the sorted set whose elements will be added to the priority queue to be constructed.

- ## Method Details

  - ### iterator

    public Iterator<E> iterator()
    Gets the iterator of the priority queue, which will not return elements in any specified ordering.
    Specified by:
      `iterator` in interface `Collection<E>`
    Specified by:
      `iterator` in interface `Iterable<E>`
    Specified by:
      `iterator` in class `AbstractCollection<E>`
    Returns:
      the iterator of the priority queue.

  - ### size

    public int size()
    Gets the size of the priority queue. If the size of the queue is greater than the Integer.MAX, then it returns Integer.MAX.
    Specified by:
      `size` in interface `Collection<E>`
    Specified by:
      `size` in class `AbstractCollection<E>`
    Returns:
      the size of the priority queue.

  - ### clear

    public void clear()
    Removes all the elements of the priority queue.
    Specified by:
      `clear` in interface `Collection<E>`
    Overrides:
      `clear` in class `AbstractQueue<E>`
    See Also:
      - `AbstractCollection.iterator()`
      - `AbstractCollection.isEmpty()`
      - `AbstractCollection.size()`

  - ### offer

    public boolean offer(E o)
    Inserts the element to the priority queue.
    Parameters:
      `o` - the element to add to the priority queue.
    Returns:
      always true
    Throws:
      `ClassCastException` - if the element cannot be compared with the elements in the priority queue using the ordering of the priority queue.
      `NullPointerException` - if `o` is `null`.

  - ### poll

    public E poll()
    Gets and removes the head of the queue.
    Returns:
      the head of the queue or null if the queue is empty.

  - ### peek

    public E peek()
    Gets but does not remove the head of the queue.
    Returns:
      the head of the queue or null if the queue is empty.

  - ### comparator

    public Comparator<? super E> comparator()
    Gets the comparator of the priority queue.
    Returns:
      the comparator of the priority queue or null if the natural ordering is used.

  - ### remove

    public boolean remove(Object o)
    Removes the specified object from the priority queue.
    Specified by:
      `remove` in interface `Collection<E>`
    Overrides:
      `remove` in class `AbstractCollection<E>`
    Parameters:
      `o` - the object to be removed.
    Returns:
      true if the object was in the priority queue, false if the object was not in the priority queue.

  - ### add

    public boolean add(E o)
    Adds the specified object to the priority queue.
    Specified by:
      `add` in interface `Collection<E>`
    Overrides:
      `add` in class `AbstractQueue<E>`
    Parameters:
      `o` - the object to be added.
    Returns:
      always true.
    Throws:
      `ClassCastException` - if the element cannot be compared with the elements in the priority queue using the ordering of the priority queue.
      `NullPointerException` - if `o` is `null`.

  - ### contains

    public boolean contains(Object object)
    Answers if there is an element in this queue equals to the object.
    Specified by:
      `contains` in interface `Collection<E>`
    Overrides:
      `contains` in class `AbstractCollection<E>`
    Parameters:
      `object` - the object to search for.
    Returns:
      `true` if object is an element of this `Collection`, `false` otherwise.
    See Also:
      - `AbstractCollection.contains(java.lang.Object)`

  - ### toArray

    public Object[] toArray()
    Returns all the elements in an array. The result is a copy of all the elements.
    Specified by:
      `toArray` in interface `Collection<E>`
    Overrides:
      `toArray` in class `AbstractCollection<E>`
    Returns:
      the Array of all the elements
    See Also:
      - `AbstractCollection.toArray()`

  - ### toArray

    public <T> T[] toArray(T[] array)
    Returns all the elements in an array, and the type of the result array is the type of the argument array. If the argument array is big enough, the elements from the queue will be stored in it(element immediately following the end of the queue is set to null, if any); otherwise, it will return a new array with the size of the argument array and size of the queue.
    Specified by:
      `toArray` in interface `Collection<E>`
    Overrides:
      `toArray` in class `AbstractCollection<E>`
    Type Parameters:
      `T` - the type of elements in the array
    Parameters:
      `array` - the array stores all the elements from the queue, if it has enough space; otherwise, a new array of the same type and the size of the queue will be used
    Returns:
      the Array of all the elements
    Throws:
      `ArrayStoreException` - if the type of the argument array is not compatible with every element in the queue
      `NullPointerException` - if the argument array is null
    See Also:
      - invalid reference

            java.util.AbstractCollection#toArray(T[])