public interface Deque<E>

ExtendsCollection<E>, Iterable<E>, Queue<E>

Known subtypesArrayDeque, LinkedList

A kind of collection that can insert or remove element at both ends(“double ended queue”). Mostly a deque has no limit of its size.

Extending from Queue, a deque can be used as a Queue which behavior is first-in-first-out. Furthermore, a deque can also be used as a Stack(legacy class) which behavior is last-in-first-out.

A typical deque does not allow null to be inserted as its element, while some implementations allow it. But null should not be inserted even in these implementations, since method poll return null to indicate that there is no element left in the deque.

A deque can also remove interior elements by removeFirstOccurrence and removeLastOccurrence methods. A deque can not access elements by index.

Type parameter E: the type of elements in this collection

Methods

public abstract void addFirst(E e)Inserts an element at the head of this deque if it dose not violate size limit immediately.
public abstract void addLast(E e)Inserts an element at the tail of this deque if it dose not violate size limit immediately.
public abstract boolean offerFirst(E e)Inserts an element at the head of this deque unless it would violate size limit.
public abstract boolean offerLast(E e)Inserts an element at the tail of this deque unless it would violate size limit.
public abstract E removeFirst()Gets and removes the head element of this deque.
public abstract E removeLast()Gets and removes the tail element of this deque.
public abstract E pollFirst()Gets and removes the head element of this deque.
public abstract E pollLast()Gets and removes the tail element of this deque.
public abstract E getFirst()Gets but not removes the head element of this deque.
public abstract E getLast()Gets but not removes the tail element of this deque.
public abstract E peekFirst()Gets but not removes the head element of this deque.
public abstract E peekLast()Gets but not removes the tail element of this deque.
public abstract boolean removeFirstOccurrence(Object o)Removes the first equivalent element of the specified object.
public abstract boolean removeLastOccurrence(Object o)Removes the last equivalent element of the specified object.
public abstract void push(E e)Pushes the element to the deque(at the head of the deque), just same as addFirst(E).
public abstract E pop()Pops the head element of the deque, just same as removeFirst().
public abstract Iterator<E> descendingIterator()Returns the iterator in reverse order, from tail to head.

Inherited methods

From Queue

offer, poll, remove, peek, element

From Collection

add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, remove, removeAll, retainAll, size, toArray, toArray, removeIf

From Iterable

forEach

Method details

addFirst

public abstract void addFirst(E e)
Inserts an element at the head of this deque if it dose not violate size limit immediately. It is better to use offerFirst(E) if a deque is size-limited.

Parameters

e E
the element

Throws

IllegalStateException
if it can not add now due to size limit
ClassCastException
if the class of element can not be added into this deque
NullPointerException
if the element is null and the deque can not contain null element
IllegalArgumentException
if the element can not be added due to some property.

addLast

public abstract void addLast(E e)
Inserts an element at the tail of this deque if it dose not violate size limit immediately. It is better to use offerLast(E) if a deque is size-limited.

Parameters

e E
the element

Throws

IllegalStateException
if it can not add now due to size limit
ClassCastException
if the class of element can not be added into this deque
NullPointerException
if the element is null and the deque can not contain null element
IllegalArgumentException
if the element can not be added due to some property.

offerFirst

public abstract boolean offerFirst(E e)
Inserts an element at the head of this deque unless it would violate size limit. It is better than the addFirst(E) method in a size-limited deque, because the latter one may fail to add the element only by throwing an exception.

Parameters

e E
the element

Returns

true if the operation succeeds or false if it fails.

Throws

ClassCastException
if the class of element can not be added into this deque
NullPointerException
if the element is null and the deque can not contain null element
IllegalArgumentException
if the element can not be added due to some property.

offerLast

public abstract boolean offerLast(E e)
Inserts an element at the tail of this deque unless it would violate size limit. It is better than the addLast(E) method in a size-limited deque, because the latter one may fail to add the element only by throwing an exception.

Parameters

e E
the element

Returns

true if the operation succeeds or false if it fails

Throws

ClassCastException
if the class of element can not be added into this deque
NullPointerException
if the element is null and the deque can not contain null element
IllegalArgumentException
if the element can not be added due to some property

removeFirst

public abstract E removeFirst()
Gets and removes the head element of this deque. This method throws an exception if the deque is empty.

Returns

the head element

Throws

NoSuchElementException
if the deque is empty

removeLast

public abstract E removeLast()
Gets and removes the tail element of this deque. This method throws an exception if the deque is empty.

Returns

the tail element

Throws

NoSuchElementException
if the deque is empty

pollFirst

public abstract E pollFirst()
Gets and removes the head element of this deque. This method returns null if the deque is empty.

Returns

the head element or null if the deque is empty

pollLast

public abstract E pollLast()
Gets and removes the tail element of this deque. This method returns null if the deque is empty.

Returns

the tail element or null if the deque is empty

getFirst

public abstract E getFirst()
Gets but not removes the head element of this deque. This method throws an exception if the deque is empty.

Returns

the head element

Throws

NoSuchElementException
if the deque is empty

getLast

public abstract E getLast()
Gets but not removes the tail element of this deque. This method throws an exception if the deque is empty.

Returns

the tail element

Throws

NoSuchElementException
if the deque is empty

peekFirst

public abstract E peekFirst()
Gets but not removes the head element of this deque. This method returns null if the deque is empty.

Returns

the head element or null if the deque is empty

peekLast

public abstract E peekLast()
Gets but not removes the tail element of this deque. This method returns null if the deque is empty.

Returns

the tail element or null if the deque is empty

removeFirstOccurrence

public abstract boolean removeFirstOccurrence(Object o)
Removes the first equivalent element of the specified object. If the deque does not contain the element, it is unchanged and returns false.

Parameters

o Object
the element to be removed

Returns

true if the operation succeeds or false if the deque does not contain the element.

Throws

ClassCastException
if the class of the element is incompatible with the deque
NullPointerException
if the element is null and the deque can not contain null element

removeLastOccurrence

public abstract boolean removeLastOccurrence(Object o)
Removes the last equivalent element of the specified object. If the deque does not contain the element, it is unchanged and returns false.

Parameters

o Object
the element to be removed

Returns

true if the operation succeeds or false if the deque does not contain the element.

Throws

ClassCastException
if the class of the element is incompatible with the deque
NullPointerException
if the element is null and the deque can not contain null element

push

public abstract void push(E e)
Pushes the element to the deque(at the head of the deque), just same as addFirst(E).

Parameters

e E
the element

Throws

IllegalStateException
if it can not add now due to size limit
ClassCastException
if the class of element can not be added into this deque
NullPointerException
if the element is null and the deque can not contain null element
IllegalArgumentException
if the element can not be added due to some property.

pop

public abstract E pop()
Pops the head element of the deque, just same as removeFirst().

Returns

the head element

Throws

NoSuchElementException
if the deque is empty

descendingIterator

public abstract Iterator<E> descendingIterator()
Returns the iterator in reverse order, from tail to head.

Returns

the iterator in reverse order