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

Параметры типа:: E - тип элементов, хранимых в этом очереди с двумя концами

Все суперинтерфейсы:: 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 не накладывают ограничений на количество элементов, но этот интерфейс поддерживает также деки с ограниченной емкостью и деки без ограничения размера.

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

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

Сводка методов 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
Метод `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 как указано в таблице ниже:

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

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

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

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

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

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

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

С момента:: 1.6

END_OF_DOCUMENT_MARKER

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

Модификатор и тип	Метод	Описание
`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).

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

размер

int size()

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

Определяется:: size в интерфейсе Collection<E>
Возвращает:: количество элементов в этом deque

итератор

Iterator<E> iterator()

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

Определяется:: iterator в интерфейсе Collection<E>
Определяется:: iterator в интерфейсе Iterable<E>
Возвращает:: итератор по элементам в этом deque в правильном порядке

descendingIterator

Iterator<E> descendingIterator()

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

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

reversed

default Deque<E> reversed()

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

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

© 1993, 2023, 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://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Deque.html