javadoc.com.google.common.collect.MinMaxPriorityQueue.html Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of guava-osgi

Repackaging of Google Guava libraries as OSGi bundle

The newest version!








MinMaxPriorityQueue (Guava: Google Core Libraries for Java 11.0.1 API)























  
      Overview 
      Package 
    Class 
      Use 
      Tree 
      Deprecated 
      Index 
      Help 
  









 PREV CLASS 
 NEXT CLASS

  FRAMES   
 NO FRAMES   
 







  SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD









com.google.common.collect


Class MinMaxPriorityQueue<E>
java.lang.Object
  java.util.AbstractCollection<E>
      java.util.AbstractQueue<E>
          com.google.common.collect.MinMaxPriorityQueue<E>


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



@Beta
public final class MinMaxPriorityQueue<E>extends AbstractQueue<E>




A double-ended priority queue, which provides constant-time access to both
 its least element and its greatest element, as determined by the queue's
 specified comparator. If no comparator is given at construction time, the
 natural order of elements is used.

 
As a Queue it functions exactly as a PriorityQueue: its
 head element -- the implicit target of the methods peek(), poll() and AbstractQueue.remove() -- is defined as the least element in
 the queue according to the queue's comparator. But unlike a regular priority
 queue, the methods peekLast(), pollLast() and
 removeLast() are also provided, to act on the greatest element
 in the queue instead.

 
A min-max priority queue can be configured with a maximum size. If so,
 each time the size of the queue exceeds that value, the queue automatically
 removes its greatest element according to its comparator (which might be the
 element that was just added). This is different from conventional bounded
 queues, which either block or reject new elements when full.

 
This implementation is based on the
 min-max heap
 developed by Atkinson, et al. Unlike many other double-ended priority queues,
 it stores elements in a single array, as compact as the traditional heap data
 structure used in PriorityQueue.

 
This class is not thread-safe, and does not accept null elements.

 
Performance notes:

 

 The retrieval operations peek(), peekFirst(), peekLast(), AbstractQueue.element(), and size are constant-time
 
The enqueing and dequeing operations (offer(E), add(E), and
     all the forms of poll() and AbstractQueue.remove()) run in O(log n) time
 
The AbstractCollection.remove(Object) and AbstractCollection.contains(java.lang.Object) operations require
     linear (O(n)) time
 
If you only access one end of the queue, and don't use a maximum size,
     this class is functionally equivalent to PriorityQueue, but
     significantly slower.
 




Since:
  8.0
Author:
  Sverre Sundsdal, Torbjorn Gannholm










Nested Class Summary



static class
MinMaxPriorityQueue.Builder<B>



          The builder class used in creation of min-max priority queues.


 






Method Summary



 boolean
add(E element)



          Adds the given element to this queue.



 boolean
addAll(Collection<? extends E> newElements)



           



 void
clear()



           



 Comparator<? super E>
comparator()



          Returns the comparator used to order the elements in this queue.



static



<E extends Comparable<E>> 


MinMaxPriorityQueue<E>



create()



          Creates a new min-max priority queue with default settings: natural order,
 no maximum size, no initial contents, and an initial expected size of 11.



static



<E extends Comparable<E>> 


MinMaxPriorityQueue<E>



create(Iterable<? extends E> initialContents)



          Creates a new min-max priority queue using natural order, no maximum size,
 and initially containing the given elements.



static MinMaxPriorityQueue.Builder<Comparable>
expectedSize(int expectedSize)



          Creates and returns a new builder, configured to build MinMaxPriorityQueue instances sized appropriately to hold expectedSize elements.



 Iterator<E>
iterator()



          Returns an iterator over the elements contained in this collection,
 in no particular order.



static MinMaxPriorityQueue.Builder<Comparable>
maximumSize(int maximumSize)



          Creates and returns a new builder, configured to build MinMaxPriorityQueue instances that are limited to maximumSize
 elements.



 boolean
offer(E element)



          Adds the given element to this queue.



static



<B> MinMaxPriorityQueue.Builder<B>



orderedBy(Comparator<B> comparator)



          Creates and returns a new builder, configured to build MinMaxPriorityQueue instances that use comparator to determine the
 least and greatest elements.



 E
peek()



           



 E
peekFirst()



          Retrieves, but does not remove, the least element of this queue, or returns
 null if the queue is empty.



 E
peekLast()



          Retrieves, but does not remove, the greatest element of this queue, or
 returns null if the queue is empty.



 E
poll()



           



 E
pollFirst()



          Removes and returns the least element of this queue, or returns null if the queue is empty.



 E
pollLast()



          Removes and returns the greatest element of this queue, or returns null if the queue is empty.



 E
removeFirst()



          Removes and returns the least element of this queue.



 E
removeLast()



          Removes and returns the greatest element of this queue.



 int
size()



           



 Object[]
toArray()



           


 


Methods inherited from class java.util.AbstractQueue


element, remove


 


Methods inherited from class java.util.AbstractCollection


contains, containsAll, isEmpty, remove, removeAll, retainAll, toArray, toString


 


Methods inherited from class java.lang.Object


clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait


 


Methods inherited from interface java.util.Collection


contains, containsAll, equals, hashCode, isEmpty, remove, removeAll, retainAll, toArray


 








Method Detail




create
public static <E extends Comparable<E>> MinMaxPriorityQueue<E> create()

Creates a new min-max priority queue with default settings: natural order,
 no maximum size, no initial contents, and an initial expected size of 11.








create
public static <E extends Comparable<E>> MinMaxPriorityQueue<E> create(Iterable<? extends E> initialContents)

Creates a new min-max priority queue using natural order, no maximum size,
 and initially containing the given elements.








orderedBy
public static <B> MinMaxPriorityQueue.Builder<B> orderedBy(Comparator<B> comparator)

Creates and returns a new builder, configured to build MinMaxPriorityQueue instances that use comparator to determine the
 least and greatest elements.








expectedSize
public static MinMaxPriorityQueue.Builder<Comparable> expectedSize(int expectedSize)

Creates and returns a new builder, configured to build MinMaxPriorityQueue instances sized appropriately to hold expectedSize elements.








maximumSize
public static MinMaxPriorityQueue.Builder<Comparable> maximumSize(int maximumSize)

Creates and returns a new builder, configured to build MinMaxPriorityQueue instances that are limited to maximumSize
 elements. Each time a queue grows beyond this bound, it immediately
 removes its greatest element (according to its comparator), which might be
 the element that was just added.








size
public int size()


Specified by:
size in interface Collection<E>
Specified by:
size in class AbstractCollection<E>








add
public boolean add(E element)

Adds the given element to this queue. If this queue has a maximum size,
 after adding element the queue will automatically evict its
 greatest element (according to its comparator), which may be element itself.


Specified by:
add in interface Collection<E>
Specified by:
add in interface Queue<E>
Overrides:
add in class AbstractQueue<E>



Returns:
true always





addAll
public boolean addAll(Collection<? extends E> newElements)


Specified by:
addAll in interface Collection<E>
Overrides:
addAll in class AbstractQueue<E>








offer
public boolean offer(E element)

Adds the given element to this queue. If this queue has a maximum size,
 after adding element the queue will automatically evict its
 greatest element (according to its comparator), which may be element itself.








poll
public E poll()








peek
public E peek()








pollFirst
public E pollFirst()

Removes and returns the least element of this queue, or returns null if the queue is empty.








removeFirst
public E removeFirst()

Removes and returns the least element of this queue.



Throws:
NoSuchElementException - if the queue is empty





peekFirst
public E peekFirst()

Retrieves, but does not remove, the least element of this queue, or returns
 null if the queue is empty.








pollLast
public E pollLast()

Removes and returns the greatest element of this queue, or returns null if the queue is empty.








removeLast
public E removeLast()

Removes and returns the greatest element of this queue.



Throws:
NoSuchElementException - if the queue is empty





peekLast
public E peekLast()

Retrieves, but does not remove, the greatest element of this queue, or
 returns null if the queue is empty.








iterator
public Iterator<E> iterator()

Returns an iterator over the elements contained in this collection,
 in no particular order.

 The iterator is fail-fast: If the MinMaxPriorityQueue is modified
 at any time after the iterator is created, in any way except through the
 iterator's own remove method, the iterator will generally throw a
 ConcurrentModificationException. Thus, in the face of concurrent
 modification, the iterator fails quickly and cleanly, rather than risking
 arbitrary, non-deterministic behavior at an undetermined time in the
 future.

 
Note that the fail-fast behavior of an iterator cannot be guaranteed
 as it is, generally speaking, impossible to make any hard guarantees in the
 presence of unsynchronized concurrent modification.  Fail-fast iterators
 throw ConcurrentModificationException on a best-effort basis.
 Therefore, it would be wrong to write a program that depended on this
 exception for its correctness: the fail-fast behavior of iterators
 should be used only to detect bugs.


Specified by:
iterator in interface Iterable<E>
Specified by:
iterator in interface Collection<E>
Specified by:
iterator in class AbstractCollection<E>



Returns:
an iterator over the elements contained in this collection





clear
public void clear()


Specified by:
clear in interface Collection<E>
Overrides:
clear in class AbstractQueue<E>








toArray
public Object[] toArray()


Specified by:
toArray in interface Collection<E>
Overrides:
toArray in class AbstractCollection<E>








comparator
public Comparator<? super E> comparator()

Returns the comparator used to order the elements in this queue. Obeys the
 general contract of PriorityQueue.comparator, but returns Ordering.natural() instead of null to indicate natural ordering.

















  
      Overview 
      Package 
    Class 
      Use 
      Tree 
      Deprecated 
      Index 
      Help 
  









 PREV CLASS 
 NEXT CLASS

  FRAMES   
 NO FRAMES   
 







  SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD






Copyright © 2010-2012. All Rights Reserved.

javadoc.com.google.common.collect.MinMaxPriorityQueue.html Maven / Gradle / Ivy

com.google.common.collect Class MinMaxPriorityQueue<E>

create

create

orderedBy

expectedSize

maximumSize

size

add

addAll

offer

poll

peek

pollFirst

removeFirst

peekFirst

pollLast

removeLast

peekLast

iterator

clear

toArray

comparator

com.google.common.collect
Class MinMaxPriorityQueue<E>