Интерфейс Deque<E>

public interface Deque<E>
extends Queue<E>

Линейный набор, поддерживающий вставку и удаление элементов с обоих концов. Название deque сокращение от "double ended queue" и обычно произносится как "дек". Большинство Deque реализаций не устанавливают никаких ограничений на количество элементов, которые они могут содержать, но этот интерфейс поддерживает ограниченные по емкости деки, а также те, у которых нет ограничений на размер.

Этот интерфейс определяет методы для доступа к элементам на обоих концах дека. Предоставляются методы для вставки, удаления и проверки элемента. Каждый из этих методов существует в двух формах: одна выбрасывает исключение, если операция завершается неудачно, другая возвращает специальное значение (либо null , либо false, в зависимости от операции). Последняя форма операции вставки специально разработана для использования с реализациями ограниченных по емкости Deque ; в большинстве реализаций операции вставки не могут завершиться неудачей.

Двенадцать описанных выше методов суммированы в следующей таблице:

	Первый элемент (голова)		Последний элемент (хвост)
	Выбрасывает исключение	Специальное значение	Выбрасывает исключение	Специальное значение
Вставка	addFirst(e)	offerFirst(e)	addLast(e)	offerLast(e)
Удаление	removeFirst()	pollFirst()	removeLast()	pollLast()
Проверка	getFirst()	peekFirst()	getLast()	peekLast()

Этот интерфейс расширяет интерфейс Queue. При использовании дека в качестве очереди происходит поведение FIFO (First-In-First-Out). Элементы добавляются в конец дека и удаляются с начала. Методы, унаследованные от интерфейса Queue, точно эквивалентны методам Deque, как показано в следующей таблице:

Метод Queue	Эквивалентный метод Deque
add(e)	addLast(e)
offer(e)	offerLast(e)
remove()	removeFirst()
poll()	pollFirst()
element()	getFirst()
peek()	peekFirst()

Деки также могут использоваться в качестве стеков LIFO (Last-In-First-Out). Этот интерфейс следует использовать вместо устаревшего класса Stack. При использовании дека в качестве стека элементы помещаются и извлекаются с начала дека. Методы стека точно эквивалентны методам Deque , как показано в таблице ниже:

Метод стека	Эквивалентный метод Deque
push(e)	addFirst(e)
pop()	removeFirst()
peek()	peekFirst()

Обратите внимание, что метод peek работает одинаково хорошо, когда дек используется в качестве очереди или стека; в обоих случаях элементы берутся с начала дека.

Этот интерфейс предоставляет два метода для удаления внутренних элементов, removeFirstOccurrence и removeLastOccurrence.

В отличие от интерфейса List, этот интерфейс не поддерживает индексированный доступ к элементам.

Хотя реализация Deque не обязана запрещать вставку элементов null, это настоятельно рекомендуется. Пользователям любых реализаций Deque, которые допускают элементы null, настоятельно рекомендуется не пользоваться возможностью вставки null. Это связано с тем, что null используется в качестве специального значения возврата различными методами для указания того, что дек пустой.

Реализации Deque обычно не определяют версий методов equals и hashCode , основанных на элементах, а вместо этого наследуют версии, основанные на идентификаторах, из класса Object.

Этот интерфейс является членом Java Collections Framework.

Методы

addFirst

void addFirst(E e)

Вставляет указанный элемент в начало данного объекта deque, если это возможно сделать немедленно без нарушения ограничений по емкости, выбросив IllegalStateException если свободной памяти в данный момент нет. При использовании deque с ограниченной емкостью, обычно предпочтительнее использовать метод offerFirst(E).

Параметры:

e - добавляемый элемент

Исключения:

IllegalStateException - если элемент не может быть добавлен в данный момент из-за ограничений по емкости

ClassCastException - если класс указанного элемента препятствует его добавлению в эту очередь

NullPointerException - если указанный элемент имеет значение null, и данная deque не допускает null-элементов

IllegalArgumentException - если некоторые свойства указанного элемента препятствуют его добавлению в эту очередь

addLast

void addLast(E e)

Параметры:

e - добавляемый элемент

Исключения:

IllegalStateException - если элемент не может быть добавлен в данный момент из-за ограничений по емкости

ClassCastException - если класс указанного элемента препятствует его добавлению в эту очередь

NullPointerException - если указанный элемент имеет значение null, и данная deque не допускает null-элементов

IllegalArgumentException - если некоторые свойства указанного элемента препятствуют его добавлению в эту очередь

offerFirst

boolean offerFirst(E e)

Вставляет указанный элемент в начало данного объекта deque, если это возможно сделать без нарушения ограничений по емкости. При использовании deque с ограниченной емкостью, этот метод обычно предпочтительнее метода addFirst(E), который может не вставить элемент только с помощью исключения.

Параметры:

e - добавляемый элемент

Возвращает:

true если элемент был добавлен в эту очередь, иначе false

Исключения:

ClassCastException - если класс указанного элемента препятствует его добавлению в эту очередь

NullPointerException - если указанный элемент имеет значение null, и данная deque не допускает null-элементов

IllegalArgumentException - если некоторые свойства указанного элемента препятствуют его добавлению в эту очередь

offerLast

boolean offerLast(E e)

Вставляет указанный элемент в конец данного объекта deque, если это возможно сделать без нарушения ограничений по емкости. При использовании deque с ограниченной емкостью, этот метод обычно предпочтительнее метода addLast(E), который может не вставить элемент только с помощью исключения.

Параметры:

e - добавляемый элемент

Возвращает:

true если элемент был добавлен в эту очередь, иначе false

Исключения:

ClassCastException - если класс указанного элемента препятствует его добавлению в эту очередь

NullPointerException - если указанный элемент имеет значение null, и данная deque не допускает null-элементов

IllegalArgumentException - если некоторые свойства указанного элемента препятствуют его добавлению в эту очередь

removeFirst

E removeFirst()

Возвращает и удаляет первый элемент данной очереди deque. Этот метод отличается от pollFirst только тем, что он генерирует исключение, если данная deque пуста.

Возвращает:

голова этой очереди

Исключения:

NoSuchElementException - если данная deque пуста

removeLast

E removeLast()

Возвращает и удаляет последний элемент данной очереди deque. Этот метод отличается от pollLast только тем, что он генерирует исключение, если данная deque пуста.

Возвращает:

хвост этой очереди

Исключения:

NoSuchElementException - если данная deque пуста

pollFirst

E pollFirst()

Возвращает и удаляет первый элемент данной очереди deque, или возвращает null если данная deque пуста.

Возвращает:

голова этой очереди, или null если данная deque пуста

pollLast

E pollLast()

Возвращает и удаляет последний элемент данной очереди deque, или возвращает null если данная deque пуста.

Возвращает:

хвост этой очереди, или null если данная deque пуста

getFirst

E getFirst()

Возвращает, но не удаляет, первый элемент данной очереди deque. Этот метод отличается от peekFirst только тем, что он генерирует исключение, если данная deque пуста.

Возвращает:

голова этой очереди

Исключения:

NoSuchElementException - если данная deque пуста

getLast

E getLast()

Возвращает, но не удаляет, последний элемент данной очереди deque. Этот метод отличается от peekLast только тем, что он генерирует исключение, если данная deque пуста.

Возвращает:

хвост этой очереди

Исключения:

NoSuchElementException - если данная deque пуста

peekFirst

E peekFirst()

Возвращает, но не удаляет, первый элемент данной очереди deque, или возвращает null если данная deque пуста.

Возвращает:

голова этой очереди, или null если данная deque пуста

peekLast

E peekLast()

Возвращает, но не удаляет, последний элемент данной очереди deque, или возвращает null если данная deque пуста.

Возвращает:

хвост этой очереди, или null если данная deque пуста

removeFirstOccurrence

boolean removeFirstOccurrence(Object o)

Удаляет первое вхождение указанного элемента из данной очереди deque. Если в очереди нет элемента, она остается неизменной. Более формально, удаляет первый элемент e такой, что (o==null ? e==null : o.equals(e)) (если такой элемент существует). Возвращает true если данная deque содержала указанный элемент (или эквивалентно, если данная deque изменилась в результате вызова).

Параметры:

o - элемент, который нужно удалить из данной очереди, если он присутствует

Возвращает:

true если элемент был удален в результате этого вызова

Исключения:

ClassCastException - если класс указанного элемента несовместим с этой очередью (необязательно)

NullPointerException - если указанный элемент имеет значение null, и данная deque не допускает null-элементов (необязательно)

removeLastOccurrence

boolean removeLastOccurrence(Object o)

Удаляет последнее вхождение указанного элемента из данной очереди deque. Если в очереди нет элемента, она остается неизменной. Более формально, удаляет последний элемент e такой, что (o==null ? e==null : o.equals(e)) (если такой элемент существует). Возвращает true если данная deque содержала указанный элемент (или эквивалентно, если данная deque изменилась в результате вызова).

Параметры:

o - элемент, который нужно удалить из данной очереди, если он присутствует

Возвращает:

true если элемент был удален в результате этого вызова

Исключения:

ClassCastException - если класс указанного элемента несовместим с этой очередью (необязательно)

NullPointerException - если указанный элемент имеет значение null, и данная deque не допускает null-элементов (необязательно)

add

boolean add(E e)

Определено в:

add в интерфейсе Collection<E>

Определено в:

add в интерфейсе Queue<E>

Параметры:

e - добавляемый элемент

Возвращает:

true (как указано в Collection.add(E))

Исключения:

IllegalStateException - если элемент не может быть добавлен в данный момент из-за ограничений по емкости

ClassCastException - если класс указанного элемента препятствует его добавлению в эту очередь

NullPointerException - если указанный элемент имеет значение null, и данная deque не допускает null-элементов

IllegalArgumentException - если некоторые свойства указанного элемента препятствуют его добавлению в эту очередь

offer

boolean offer(E e)

Указано в:

offer в интерфейсе Queue<E>

Параметры:

e - добавляемый элемент

Возвращает:

true если элемент был добавлен в эту очередь, иначе false

Исключение:

ClassCastException - если класс указанного элемента препятствует его добавлению в эту очередь

NullPointerException - если указанный элемент равен null, а эта очередь не допускает null-элементы

IllegalArgumentException - если некоторые свойства указанного элемента препятствуют его добавлению в эту очередь

remove

E remove()

Указано в:

remove в интерфейсе Queue<E>

Возвращает:

голова очереди, представленная этой очередью

Исключение:

NoSuchElementException - если эта очередь пуста

poll

E poll()

Указано в:

poll в интерфейсе Queue<E>

Возвращает:

первый элемент этой очереди, или null , если эта очередь пуста

element

E element()

Указано в:

element в интерфейсе Queue<E>

Возвращает:

голова очереди, представленная этой очередью

Исключение:

NoSuchElementException - если эта очередь пуста

peek

E peek()

Указано в:

peek в интерфейсе Queue<E>

Возвращает:

голова очереди, представленной этой очередью, или null , если эта очередь пуста

push

void push(E e)

Параметры:

e - добавляемый элемент

Исключение:

IllegalStateException - если элемент не может быть добавлен в данный момент из-за ограничений по емкости

ClassCastException - если класс указанного элемента препятствует его добавлению в эту очередь

NullPointerException - если указанный элемент равен null, а эта очередь не допускает null-элементы

IllegalArgumentException - если некоторые свойства указанного элемента препятствуют его добавлению в эту очередь

pop

E pop()

Возвращает:

элемент в начале этой очереди (который является вершиной стека, представленного этой очередью)

Исключение:

NoSuchElementException - если эта очередь пуста

remove

boolean remove(Object o)

Указано в:

remove в интерфейсе Collection<E>

Параметры:

o - элемент, который нужно удалить из этой очереди, если он присутствует

Возвращает:

true , если элемент был удален в результате этого вызова

Исключение:

ClassCastException - если тип указанного элемента несовместим с этой очередью (необязательно)

NullPointerException - если указанный элемент равен null, а эта очередь не допускает null-элементы (необязательно)

contains

boolean contains(Object o)

Возвращает true , если эта очередь содержит указанный элемент. Более формально, возвращает true тогда и только тогда, когда эта очередь содержит по крайней мере один элемент e такой, что (o==null ? e==null : o.equals(e)).

Указано в:

contains в интерфейсе Collection<E>

Параметры:

o - элемент, присутствие которого в этой очереди нужно проверить

Возвращает:

true , если эта очередь содержит указанный элемент

Исключение:

ClassCastException - если тип указанного элемента несовместим с этой очередью (необязательно)

NullPointerException - если указанный элемент равен null, а эта очередь не допускает null-элементы (необязательно)

size

int size()

Возвращает количество элементов в этой очереди.

Указано в:

size в интерфейсе Collection<E>

Возвращает:

количество элементов в этой очереди

iterator

Iterator<E> iterator()

Возвращает итератор по элементам этой очереди в правильной последовательности. Элементы будут возвращаться в порядке от первого (головы) до последнего (хвоста).

Указано в:

iterator в интерфейсе Collection<E>

Указано в:

iterator в интерфейсе Iterable<E>

Возвращает:

итератор по элементам этой очереди в правильной последовательности

descendingIterator

Iterator<E> descendingIterator()

Возвращает итератор по элементам этой очереди в обратном порядке. Элементы будут возвращаться в порядке от последнего (хвоста) до первого (головы).

Возвращает:

итератор по элементам этой очереди в обратном порядке