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

Type Parameters:: E - тип элементов, хранящихся в этом deque

Все суперинтерфейсы:: Collection<E>, Iterable<E>, Queue<E>, SequencedCollection<E>

Все известные подинтерфейсы:: BlockingDeque<E>

Все известные реализующие классы:: ArrayDeque, ConcurrentLinkedDeque, LinkedBlockingDeque, LinkedList

public interface Deque<E> extends Queue<E>, SequencedCollection<E>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Since:: 1.6

Краткое описание методов

Модификатор и тип	Метод	Описание
`boolean`	`add(E e)`	Вставляет указанный элемент в очередь, представленную этим деком (другими словами, в конец этого дека), если это возможно сделать немедленно без нарушения ограничений по емкости, возвращает `true` при успехе и выбрасывает `IllegalStateException`, если в настоящее время нет места.
`boolean`	`addAll(Collection<? extends E> c)`	Добавляет все элементы из указанного набора в конец этого дека, как если бы вызывали `addLast(E)` для каждого из них в порядке, в котором они возвращаются итератором набора.
`void`	`addFirst(E e)`	Вставляет указанный элемент в начало этого дека, если это возможно сделать немедленно без нарушения ограничений по емкости, выбрасывает `IllegalStateException`, если в настоящее время нет места.
`void`	`addLast(E e)`	Вставляет указанный элемент в конец этого дека, если это возможно сделать немедленно без нарушения ограничений по емкости, выбрасывает `IllegalStateException`, если в настоящее время нет места.
`boolean`	`contains(Object o)`	Возвращает `true`, если этот дек содержит указанный элемент.
`Iterator<E>`	`descendingIterator()`	Возвращает итератор по элементам этого дека в обратном порядке.
`E`	`element()`	Получает, но не удаляет, голову очереди, представленной этим деком (другими словами, первый элемент этого дека).
`E`	`getFirst()`	Получает, но не удаляет, первый элемент этого дека.
`E`	`getLast()`	Получает, но не удаляет, последний элемент этого дека.
`Iterator<E>`	`iterator()`	Возвращает итератор по элементам этого дека в правильном порядке.
`boolean`	`offer(E e)`	Вставляет указанный элемент в очередь, представленную этим деком (другими словами, в конец этого дека), если это возможно сделать немедленно без нарушения ограничений по емкости, возвращает `true` при успехе и `false`, если в настоящее время нет места.
`boolean`	`offerFirst(E e)`	Вставляет указанный элемент в начало этого дека, если это не нарушит ограничения по емкости.
`boolean`	`offerLast(E e)`	Вставляет указанный элемент в конец этого дека, если это не нарушит ограничения по емкости.
`E`	`peek()`	Получает, но не удаляет, голову очереди, представленной этим деком (другими словами, первый элемент этого дека), или возвращает `null`, если этот дек пуст.
`E`	`peekFirst()`	Получает, но не удаляет, первый элемент этого дека, или возвращает `null`, если этот дек пуст.
`E`	`peekLast()`	Получает, но не удаляет, последний элемент этого дека, или возвращает `null`, если этот дек пуст.
`E`	`poll()`	Получает и удаляет голову очереди, представленной этим деком (другими словами, первый элемент этого дека), или возвращает `null`, если этот дек пуст.
`E`	`pollFirst()`	Получает и удаляет первый элемент этого дека, или возвращает `null`, если этот дек пуст.
`E`	`pollLast()`	Получает и удаляет последний элемент этого дека, или возвращает `null`, если этот дек пуст.
`E`	`pop()`	Извлекает элемент из стека, представленного этим деком.
`void`	`push(E e)`	Помещает элемент в стек, представленный этим деком (другими словами, в начало этого дека), если это возможно сделать немедленно без нарушения ограничений по емкости, выбрасывает `IllegalStateException`, если в настоящее время нет места.
`E`	`remove()`	Получает и удаляет голову очереди, представленной этим деком (другими словами, первый элемент этого дека).
`boolean`	`remove(Object o)`	Удаляет первое вхождение указанного элемента из этого дека.
`E`	`removeFirst()`	Получает и удаляет первый элемент этого дека.
`boolean`	`removeFirstOccurrence(Object o)`	Удаляет первое вхождение указанного элемента из этого дека.
`E`	`removeLast()`	Получает и удаляет последний элемент этого дека.
`boolean`	`removeLastOccurrence(Object o)`	Удаляет последнее вхождение указанного элемента из этого дека.
`default Deque<E>`	`reversed()`	Возвращает представление этого набора в обратном порядке.
`int`	`size()`	Возвращает количество элементов в этом деке.

Методы, объявленные в интерфейсе java.util.Collection

clear, containsAll, equals, hashCode, isEmpty, parallelStream, removeAll, removeIf, retainAll, spliterator, stream, toArray, toArray, toArray

Методы, объявленные в интерфейсе java.lang.Iterable

forEach

Подробное описание методов

addFirst

void addFirst(E e)

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

Указано в:: addFirst в интерфейсе SequencedCollection<E>
Параметры:: e - добавляемый элемент
Исключения:: IllegalStateException - если элемент не может быть добавлен в данный момент из-за ограничений по емкости; ClassCastException - если класс указанного элемента препятствует его добавлению в этот дек; NullPointerException - если указанный элемент null, а этот дек не допускает null-элементов; IllegalArgumentException - если некоторые свойства указанного элемента препятствуют его добавлению в этот дек

addLast

void addLast(E e)

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

Этот метод эквивалентен методу add(E).

Указано в:: addLast в интерфейсе SequencedCollection<E>
Параметры:: e - добавляемый элемент
Исключения:: IllegalStateException - если элемент не может быть добавлен в данный момент из-за ограничений по емкости; ClassCastException - если класс указанного элемента препятствует его добавлению в этот дек; NullPointerException - если указанный элемент null, а этот дек не допускает null-элементов; IllegalArgumentException - если некоторые свойства указанного элемента препятствуют его добавлению в этот дек

offerFirst

boolean offerFirst(E e)

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

Параметры:: e - добавляемый элемент
Возвращает:: true, если элемент был добавлен в этот дек, иначе false
Исключения:: ClassCastException - если класс указанного элемента препятствует его добавлению в этот дек; NullPointerException - если указанный элемент null, а этот дек не допускает null-элементов; IllegalArgumentException - если некоторые свойства указанного элемента препятствуют его добавлению в этот дек

offerLast

boolean offerLast(E e)

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

Параметры:: e - добавляемый элемент
Возвращает:: true, если элемент был добавлен в этот дек, иначе false
Исключения:: ClassCastException - если класс указанного элемента препятствует его добавлению в этот дек; NullPointerException - если указанный элемент null, а этот дек не допускает null-элементов; IllegalArgumentException - если некоторые свойства указанного элемента препятствуют его добавлению в этот дек

removeFirst

E removeFirst()

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

Указано в:: removeFirst в интерфейсе SequencedCollection<E>
Возвращает:: голова этого дека
Исключения:: NoSuchElementException - если этот дек пустой

removeLast

E removeLast()

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

Указано в:: removeLast в интерфейсе SequencedCollection<E>
Возвращает:: хвост этого дека
Исключения:: NoSuchElementException - если этот дек пустой

pollFirst

E pollFirst()

Извлекает и удаляет первый элемент этого дека или возвращает null, если этот дек пустой.

Возвращает:: голова этого дека или null, если этот дек пустой

pollLast

E pollLast()

Извлекает и удаляет последний элемент этого дека или возвращает null, если этот дек пустой.

Возвращает:: хвост этого дека или null, если этот дек пустой

getFirst

E getFirst()

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

Указано в:: getFirst в интерфейсе SequencedCollection<E>
Возвращает:: голова этого дека
Исключения:: NoSuchElementException - если этот дек пустой

getLast

E getLast()

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

Указано в:: getLast в интерфейсе SequencedCollection<E>
Возвращает:: хвост этого дека
Исключения:: NoSuchElementException - если этот дек пустой

peekFirst

E peekFirst()

Извлекает, но не удаляет, первый элемент этого дека или возвращает null, если этот дек пустой.

Возвращает:: голова этого дека или null, если этот дек пустой

peekLast

E peekLast()

Извлекает, но не удаляет, последний элемент этого дека или возвращает null, если этот дек пустой.

Возвращает:: хвост этого дека или null, если этот дек пустой

removeFirstOccurrence

boolean removeFirstOccurrence(Object o)

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

Параметры:: o - элемент, который нужно удалить из этого дека, если он присутствует
Возвращает:: true, если элемент был удален в результате этого вызова
Исключения:: ClassCastException - если класс указанного элемента несовместим с этим деком (необязательно); NullPointerException - если указанный элемент null, а этот дек не допускает null-элементов (необязательно)

removeLastOccurrence

boolean removeLastOccurrence(Object o)

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

Параметры:: o - элемент, который нужно удалить из этого дека, если он присутствует
Возвращает:: true, если элемент был удален в результате этого вызова
Исключения:: ClassCastException - если класс указанного элемента несовместим с этим деком (необязательно); NullPointerException - если указанный элемент null, а этот дек не допускает null-элементов (необязательно)

END_OF_DOCUMENT_MARKER

add

boolean add(E e)

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

Этот метод эквивалентен addLast(E).

Specified by:: add в интерфейсе Collection<E>
Specified by:: add в интерфейсе Queue<E>
Parameters:: e - элемент для добавления
Returns:: true (как указано в Collection.add(E))
Throws:: IllegalStateException - если элемент не может быть добавлен в данный момент из-за ограничений по емкости; ClassCastException - если класс указанного элемента препятствует его добавлению в этот дек; NullPointerException - если указанный элемент имеет значение null, а этот дек не допускает null-элементов; IllegalArgumentException - если какие-либо свойства указанного элемента препятствуют его добавлению в этот дек

offer

boolean offer(E e)

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

Этот метод эквивалентен offerLast(E).

Specified by:: offer в интерфейсе Queue<E>
Parameters:: e - элемент для добавления
Returns:: true, если элемент был добавлен в этот дек, иначе false
Throws:: ClassCastException - если класс указанного элемента препятствует его добавлению в этот дек; NullPointerException - если указанный элемент имеет значение null, а этот дек не допускает null-элементов; IllegalArgumentException - если какие-либо свойства указанного элемента препятствуют его добавлению в этот дек

remove

E remove()

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

Этот метод эквивалентен removeFirst().

Specified by:: remove в интерфейсе Queue<E>
Returns:: голова очереди, представленной этим деком
Throws:: NoSuchElementException - если этот дек пуст

poll

E poll()

Извлекает и удаляет голову очереди, представленной этим деком (другими словами, первый элемент этого дека), или возвращает null, если этот дек пуст.

Этот метод эквивалентен pollFirst().

Specified by:: poll в интерфейсе Queue<E>
Returns:: первый элемент этого дека, или null, если этот дек пуст

element

E element()

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

Этот метод эквивалентен getFirst().

Specified by:: element в интерфейсе Queue<E>
Returns:: голова очереди, представленной этим деком
Throws:: NoSuchElementException - если этот дек пуст

peek

E peek()

Извлекает, но не удаляет, голову очереди, представленной этим деком (другими словами, первый элемент этого дека), или возвращает null, если этот дек пуст.

Этот метод эквивалентен peekFirst().

Specified by:: peek в интерфейсе Queue<E>
Returns:: голова очереди, представленной этим деком, или null, если этот дек пуст

addAll

boolean addAll(Collection<? extends E> c)

Добавляет все элементы в указанной коллекции в конец этого дека, как если бы вызывали addLast(E) для каждого из них в порядке, в котором они возвращаются итератором коллекции.

При использовании дека с ограниченной емкостью, обычно предпочтительнее отдельно вызывать offer для каждого элемента.

Исключение, возникающее при попытке добавить элемент, может привести к тому, что только некоторые элементы будут успешно добавлены, когда будет выброшено связанное исключение.

Specified by:

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

Parameters:

c - элементы, которые нужно вставить в этот дек

Returns:

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

Throws:

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

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

NullPointerException - если указанная коллекция содержит null-элемент, а этот дек не допускает null-элементов, или если указанная коллекция имеет значение null

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

See Also:

push

void push(E e)

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

Этот метод эквивалентен addFirst(E).

Parameters:: e - элемент для помещения в стек
Throws:: IllegalStateException - если элемент не может быть добавлен в данный момент из-за ограничений по емкости; ClassCastException - если класс указанного элемента препятствует его добавлению в этот дек; NullPointerException - если указанный элемент имеет значение null, а этот дек не допускает null-элементов; IllegalArgumentException - если какие-либо свойства указанного элемента препятствуют его добавлению в этот дек

pop

E pop()

Извлекает элемент из стека, представленного этим деком. Другими словами, удаляет и возвращает первый элемент этого дека.

Этот метод эквивалентен removeFirst().

Returns:: элемент в начале этого дека (который является вершиной стека, представленного этим деком)
Throws:: NoSuchElementException - если этот дек пуст

remove

boolean remove(Object o)

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

Этот метод эквивалентен removeFirstOccurrence(Object).

Specified by:: remove в интерфейсе Collection<E>
Parameters:: o - элемент, который нужно удалить из этого дека, если он присутствует
Returns:: true, если элемент был удален в результате этого вызова
Throws:: ClassCastException - если класс указанного элемента несовместим с этим деком (необязательно); NullPointerException - если указанный элемент имеет значение null, а этот дек не допускает null-элементов (необязательно)

contains

boolean contains(Object o)

Возвращает значение true, если в этой очереди есть указанный элемент. Более формально, возвращает true, если и только если эта очередь содержит по меньшей мере один элемент e, такой что Objects.equals(o, 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()

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

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

reversed

default Deque<E> reversed()

Возвращает представление этой коллекции в обратном порядке. Порядок встречи элементов в возвращаемом представлении — обратный порядку встречи элементов в этой коллекции. Обратный порядок влияет на все операции, чувствительные к порядку, включая те, что выполняются над коллекциями-представлениями возвращаемого представления. Если реализация коллекции допускает изменения в этом представлении, эти изменения «прописываются» в базовой коллекции. Изменения в базовой коллекции могут или не могут отображаться в этом представлении в обратном порядке, в зависимости от реализации.

Указано в:: reversed в интерфейсе SequencedCollection<E>
Требования к реализации:: Реализация в этом интерфейсе возвращает представление Deque в обратном порядке. Метод reversed() представления возвращает ссылку на эту Deque. Другие операции над представлением реализуются с помощью вызовов общедоступных методов этой Deque. Точное соотношение вызовов представления и вызовов этой Deque не определено. Однако операции, чувствительные к порядку, обычно ведут себя так, как если бы они делегировали соответствующему методу с обратной ориентацией. Например, вызов getFirst на представлении может привести к вызову getLast на этой Deque.
Возвращает:: представление этой коллекции в обратном порядке в качестве Deque
С:: 21

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://download.java.net/java/early_access/jdk24/docs/api/java.base/java/util/Deque.html