Interface Deque<E>

Type Parameters:

E - the type of elements in this collection

All Superinterfaces:

Collection<E>, Iterable<E>, Queue<E>

All Known Implementing Classes:

ArrayDeque, LinkedList

public interface Deque<E>
extends Queue<E>

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.

Since:

1.6

Method Summary

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

Methods inherited from interface Collection

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

Modifier and Type	Method	Description
boolean	add(E object)	Attempts to add object to the contents of this Collection (optional).
boolean	addAll(Collection<? extends E> collection)	Attempts to add all of the objects contained in Collection to the contents of this Collection (optional).
void	clear()	Removes all elements from this Collection, leaving it empty (optional).
boolean	contains(Object object)	Tests whether this Collection contains the specified object.
boolean	containsAll(Collection<?> collection)	Tests whether this Collection contains all objects contained in the specified Collection.
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.
boolean	isEmpty()	Returns if this Collection contains no elements.
Iterator<E>	iterator()	Returns an instance of Iterator that may be used to access the objects contained by this Collection.
boolean	remove(Object object)	Removes one instance of the specified object from this Collection if one is contained (optional).
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).
int	size()	Returns a count of how many objects this Collection contains.
Object[]	toArray()	Returns a new array containing all elements contained in this Collection.
<T> T[]	toArray(T[] array)	Returns an array containing all elements contained in this Collection.

Methods inherited from interface Queue

element, offer, peek, poll, remove

Modifier and Type	Method	Description
E	element()	Gets but does not remove the element at the head of the queue.
boolean	offer(E o)	Inserts the specified element into the queue provided that the condition allows such an operation.
E	peek()	Gets but does not remove the element at the head of the queue.
E	poll()	Gets and removes the element at the head of the queue, or returns null if there is no element in the queue.
E	remove()	Gets and removes the element at the head of the queue.

Method Details

addFirst

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 - 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

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 - 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

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 - 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

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 - 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

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

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

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

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

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

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

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

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

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 - 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

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 - 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

void push(E e)

Pushes the element to the deque(at the head of the deque), just same as addFirst(E).

Parameters:

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

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

Iterator<E> descendingIterator()

Returns the iterator in reverse order, from tail to head.

Returns:

the iterator in reverse order