Interface Deque<E>

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

Все надинтерфейсы:: Collection<E>, Iterable<E>, Queue<E>

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

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

public interface Deque<E> extends Queue<E>

Линейный набор, который поддерживает вставку и удаление элементов с обоих концов. Название дека является сокращением от «двухконцевой очереди» и обычно произносится как «дек». Большинство 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
Метод стека	Эквивалентный метод `Deque`
`push(e)`	`addFirst(e)`
`pop()`	`removeFirst()`
`peek()`	`getFirst()`

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

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

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

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

Реализации 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)`	Удаляет последнее вхождение указанного элемента из этого списка.
`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).

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

addLast

void addLast(E e)

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

Этот метод эквивалентен add(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 только тем, что выбрасывает исключение, если очередь пуста.

Возвращает:: начало этой очереди
Исключения:: NoSuchElementException - если эта очередь пуста

removeLast

E removeLast()

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

Возвращает:: хвост этой очереди
Исключения:: NoSuchElementException - если эта очередь пуста

pollFirst

E pollFirst()

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

Возвращает:: начало этой очереди или null если очередь пуста

pollLast

E pollLast()

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

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

getFirst

E getFirst()

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

Возвращает:: начало этой очереди
Исключения:: NoSuchElementException - если эта очередь пуста

getLast

E getLast()

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

Возвращает:: хвост этой очереди
Исключения:: 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-элементов (необязательно)

add

boolean add(E e)

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

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

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

offer

boolean offer(E e)

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

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

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

remove

E remove()

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

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

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

poll

E poll()

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

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

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

element

E element()

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

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

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

peek

E peek()

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

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

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

addAll

boolean addAll(Collection<? extends E> c)

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

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

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

Specified by:

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

Parameters:

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

Returns:

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

Throws:

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

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

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

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

See Also:

Collection.add(Object)

push

void push(E e)

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

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

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

pop

E pop()

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

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

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

remove

boolean remove(Object o)

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

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

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

contains

boolean contains(Object o)

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

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

size

int size()

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

Specified by:: size в интерфейсе Collection<E>
Returns:: количество элементов в этом deque

iterator

Iterator<E> iterator()

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

Specified by:: iterator в интерфейсе Collection<E>
Specified by:: iterator в интерфейсе Iterable<E>
Returns:: итератор по элементам в этом deque в правильном порядке

descendingIterator

Iterator<E> descendingIterator()

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

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

© 1993, 2021, 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/17/docs/api/java.base/java/util/Deque.html