鴻蒙OS Deque

Deque

public interface Deque<E>
extends Queue<E>

支持兩端元素插入和移除的線(xiàn)性集合。 名稱(chēng) deque 是“雙端隊(duì)列”的縮寫(xiě)，通常發(fā)音為“deck”。 大多數(shù) Deque 實(shí)現(xiàn)對(duì)其可能包含的元素?cái)?shù)量沒(méi)有固定限制，但此接口支持容量受限的雙端隊(duì)列以及沒(méi)有固定大小限制的雙端隊(duì)列。

該接口定義了訪(fǎng)問(wèn)雙端隊(duì)列兩端元素的方法。 提供了插入、刪除和檢查元素的方法。 這些方法中的每一種都以?xún)煞N形式存在：一種在操作失敗時(shí)拋出異常，另一種返回一個(gè)特殊值（null 或 false，取決于操作）。 后一種形式的插入操作是專(zhuān)門(mén)為容量受限的 Deque 實(shí)現(xiàn)而設(shè)計(jì)的； 在大多數(shù)實(shí)現(xiàn)中，插入操作不會(huì)失敗。

下表總結(jié)了上述十二種方法：

該接口擴(kuò)展了 Queue 接口。 當(dāng)雙端隊(duì)列用作隊(duì)列時(shí)，會(huì)產(chǎn)生 FIFO（先進(jìn)先出）行為。 元素在雙端隊(duì)列的末尾添加并從開(kāi)頭刪除。 從 Queue 接口繼承的方法與 Deque 方法完全等價(jià)，如下表所示：

雙端隊(duì)列也可以用作 LIFO（后進(jìn)先出）堆棧。應(yīng)優(yōu)先使用此接口而不是舊的 Stack 類(lèi)。當(dāng)雙端隊(duì)列用作堆棧時(shí)，從雙端隊(duì)列的開(kāi)頭推送和彈出元素。 Stack 方法完全等同于 Deque 方法，如下表所示：

請(qǐng)注意，當(dāng)雙端隊(duì)列用作隊(duì)列或堆棧時(shí)，peek 方法同樣有效；在任何一種情況下，元素都是從雙端隊(duì)列的開(kāi)頭繪制的。

該接口提供了兩種移除內(nèi)部元素的方法，removeFirstOccurrence 和 removeLastOccurrence。

與 List 接口不同，此接口不支持對(duì)元素的索引訪(fǎng)問(wèn)。

雖然沒(méi)有嚴(yán)格要求 Deque 實(shí)現(xiàn)禁止插入 null 元素，但強(qiáng)烈鼓勵(lì)他們這樣做。強(qiáng)烈建議允許使用 null 元素的任何 Deque 實(shí)現(xiàn)的用戶(hù)不要利用插入 null 的能力。這是因?yàn)?null 被各種方法用作特殊返回值來(lái)指示雙端隊(duì)列為空。

Deque 實(shí)現(xiàn)通常不定義 equals 和 hashCode 方法的基于元素的版本，而是從類(lèi) Object 繼承基于身份的版本。

此接口是 Java 集合框架的成員。

方法總結(jié)

修飾符和類(lèi)型	方法	描述
boolean	add(E e)	如果可以在不違反容量限制的情況下立即將指定元素插入此雙端隊(duì)列表示的隊(duì)列中（換句話(huà)說(shuō)，在此雙端隊(duì)列的尾部），則在成功時(shí)返回 true 并在當(dāng)前沒(méi)有可用空間時(shí)拋出 IllegalStateException .
void	addFirst(E e)	如果可以在不違反容量限制的情況下立即插入指定元素，則在此雙端隊(duì)列的前面插入指定元素，如果當(dāng)前沒(méi)有可用空間，則拋出 IllegalStateException。
void	addLast(E e)	如果可以在不違反容量限制的情況下立即插入指定元素，則在此雙端隊(duì)列末尾插入指定元素，如果當(dāng)前沒(méi)有可用空間，則拋出 IllegalStateException。
boolean	contains(Object o)	如果此雙端隊(duì)列包含指定元素，則返回 true。
IteratorE	descendingIterator()	以相反的順序返回此雙端隊(duì)列中元素的迭代器。
E	element()	檢索但不刪除此雙端隊(duì)列表示的隊(duì)列的頭部（換句話(huà)說(shuō)，此雙端隊(duì)列的第一個(gè)元素）。
E	getFirst()	檢索但不刪除此雙端隊(duì)列的第一個(gè)元素。
E	getLast()	檢索但不刪除此雙端隊(duì)列的最后一個(gè)元素。
IteratorE	iterator()	以正確的順序返回此雙端隊(duì)列中元素的迭代器。
boolean	offer(E e)	如果可以在不違反容量限制的情況下立即執(zhí)行此操作，則將指定元素插入此雙端隊(duì)列表示的隊(duì)列中（換句話(huà)說(shuō)，在此雙端隊(duì)列的尾部），成功時(shí)返回 true，如果當(dāng)前沒(méi)有可用空間則返回 false。
boolean	offerFirst(E e)	在此雙端隊(duì)列的前面插入指定元素，除非它違反容量限制。
boolean	offerLast(E e)	在此雙端隊(duì)列末尾插入指定元素，除非它違反容量限制。
E	peek()	檢索但不刪除此雙端隊(duì)列表示的隊(duì)列的頭部（換句話(huà)說(shuō)，此雙端隊(duì)列的第一個(gè)元素），如果此雙端隊(duì)列為空，則返回 null。
E	peekFirst()	檢索但不刪除此雙端隊(duì)列的第一個(gè)元素，如果此雙端隊(duì)列為空，則返回 null。
E	peekLast()	檢索但不刪除此雙端隊(duì)列的最后一個(gè)元素，如果此雙端隊(duì)列為空，則返回 null。
E	poll()	檢索并刪除此雙端隊(duì)列表示的隊(duì)列的頭部（換句話(huà)說(shuō)，此雙端隊(duì)列的第一個(gè)元素），如果此雙端隊(duì)列為空，則返回 null。
E	pollFirst()	檢索并刪除此雙端隊(duì)列的第一個(gè)元素，如果此雙端隊(duì)列為空，則返回 null。
E	pollLast()	檢索并刪除此雙端隊(duì)列的最后一個(gè)元素，如果此雙端隊(duì)列為空，則返回 null。
E	pop()	從這個(gè)雙端隊(duì)列表示的堆棧中彈出一個(gè)元素。
void	push(E e)	如果可以在不違反容量限制的情況下立即將元素推送到此雙端隊(duì)列表示的堆棧上（換句話(huà)說(shuō)，在此雙端隊(duì)列的頭部），則如果當(dāng)前沒(méi)有可用空間則拋出 IllegalStateException。
E	remove()	檢索并刪除此雙端隊(duì)列表示的隊(duì)列的頭部（換句話(huà)說(shuō)，此雙端隊(duì)列的第一個(gè)元素）。
boolean	remove(Object o)	從此雙端隊(duì)列中刪除第一次出現(xiàn)的指定元素。
E	removeFirst()	檢索并刪除此雙端隊(duì)列的第一個(gè)元素。
boolean	removeFirstOccurrence(Object o)	從此雙端隊(duì)列中刪除第一次出現(xiàn)的指定元素。
E	removeLast()	檢索并刪除此雙端隊(duì)列的最后一個(gè)元素。
boolean	removeLastOccurrence(Object o)	從此雙端隊(duì)列中刪除最后一次出現(xiàn)的指定元素。
int	size()	返回此雙端隊(duì)列中的元素?cái)?shù)。

從接口 java.util.Collection 繼承的方法
addAll, clear, containsAll, equals, hashCode, isEmpty, parallelStream, removeAll, removeIf, retainAll, spliterator, stream, toArray, toArray

從接口 java.lang.Iterable 繼承的方法
forEach

方法詳情

addFirst

void addFirst(E e)

如果可以在不違反容量限制的情況下立即插入指定元素，則在此雙端隊(duì)列的前面插入指定元素，如果當(dāng)前沒(méi)有可用空間，則拋出 IllegalStateException。 當(dāng)使用容量受限的雙端隊(duì)列時(shí)，通常最好使用方法 offerFirst(E)。

參數(shù)：

參數(shù)名稱(chēng)	參數(shù)描述
e	要添加的元素

Throws:

Throw名稱(chēng)	Throw描述
IllegalStateException	如果此時(shí)由于容量限制無(wú)法添加元素
ClassCastException	如果指定元素的類(lèi)阻止它被添加到這個(gè)雙端隊(duì)列
NullPointerException	如果指定元素為空且此雙端隊(duì)列不允許空元素
IllegalArgumentException	如果指定元素的某些屬性阻止它被添加到這個(gè)雙端隊(duì)列

addLast

void addLast(E e)

如果可以在不違反容量限制的情況下立即插入指定元素，則在此雙端隊(duì)列末尾插入指定元素，如果當(dāng)前沒(méi)有可用空間，則拋出 IllegalStateException。 當(dāng)使用容量受限的雙端隊(duì)列時(shí)，通常最好使用方法 offerLast(E)。

此方法等效于 add(E)。

參數(shù)：

參數(shù)名稱(chēng)	參數(shù)描述
e	要添加的元素

Throws:

Throw名稱(chēng)	Throw描述
IllegalStateException	如果此時(shí)由于容量限制無(wú)法添加元素
ClassCastException	如果指定元素的類(lèi)阻止它被添加到這個(gè)雙端隊(duì)列
NullPointerException	如果指定元素為空且此雙端隊(duì)列不允許空元素
IllegalArgumentException	如果指定元素的某些屬性阻止它被添加到這個(gè)雙端隊(duì)列

offerFirst

boolean offerFirst(E e)

在此雙端隊(duì)列的前面插入指定元素，除非它違反容量限制。 當(dāng)使用容量受限的雙端隊(duì)列時(shí)，此方法通常優(yōu)于 addFirst(E) 方法，后者僅通過(guò)拋出異?？赡軣o(wú)法插入元素。

參數(shù)：

參數(shù)名稱(chēng)	參數(shù)描述
e	要添加的元素

返回:

如果元素已添加到此雙端隊(duì)列，則為 true，否則為 false

Throws:

Throw名稱(chēng)	Throw描述
ClassCastException	如果指定元素的類(lèi)阻止它被添加到這個(gè)雙端隊(duì)列
NullPointerException	如果指定元素為空且此雙端隊(duì)列不允許空元素
IllegalArgumentException	如果指定元素的某些屬性阻止它被添加到這個(gè)雙端隊(duì)列

offerLast

boolean offerLast(E e)

在此雙端隊(duì)列末尾插入指定元素，除非它違反容量限制。 當(dāng)使用容量受限的雙端隊(duì)列時(shí)，此方法通常優(yōu)于 addLast(E) 方法，后者僅通過(guò)拋出異?？赡軣o(wú)法插入元素。

參數(shù)：

參數(shù)名稱(chēng)	參數(shù)描述
e	要添加的元素

返回:

如果元素已添加到此雙端隊(duì)列，則為 true，否則為 false

Throws:

Throw名稱(chēng)	Throw描述
ClassCastException	如果指定元素的類(lèi)阻止它被添加到這個(gè)雙端隊(duì)列
NullPointerException	如果指定元素為空且此雙端隊(duì)列不允許空元素
IllegalArgumentException	如果指定元素的某些屬性阻止它被添加到這個(gè)雙端隊(duì)列

removeFirst

E removeFirst()

檢索并刪除此雙端隊(duì)列的第一個(gè)元素。 此方法與 pollFirst 的不同之處僅在于如果此雙端隊(duì)列為空，它將引發(fā)異常。

返回:

這個(gè)雙端隊(duì)列的頭

Throws:

Throw名稱(chēng)	Throw描述
NoSuchElementException	如果此雙端隊(duì)列為空

removeLast

E removeLast()

檢索并刪除此雙端隊(duì)列的最后一個(gè)元素。 此方法與 pollLast 的不同之處僅在于如果此雙端隊(duì)列為空，它將引發(fā)異常。

返回:

這個(gè)雙端隊(duì)列的尾巴

Throws:

Throw名稱(chēng)	Throw描述
NoSuchElementException	如果此雙端隊(duì)列為空

pollFirst

E pollFirst()

檢索并刪除此雙端隊(duì)列的第一個(gè)元素，如果此雙端隊(duì)列為空，則返回 null。

返回:

此雙端隊(duì)列的頭部，如果此雙端隊(duì)列為空，則返回 null

pollLast

E pollLast()

檢索并刪除此雙端隊(duì)列的最后一個(gè)元素，如果此雙端隊(duì)列為空，則返回 null。

返回:

此雙端隊(duì)列的尾部，如果此雙端隊(duì)列為空，則返回 null

getFirst

E getFirst()

檢索但不刪除此雙端隊(duì)列的第一個(gè)元素。 此方法與 peekFirst 的不同之處僅在于如果此雙端隊(duì)列為空，它將引發(fā)異常。

返回:

這個(gè)雙端隊(duì)列的頭

Throws:

Throw名稱(chēng)	Throw描述
NoSuchElementException	如果此雙端隊(duì)列為空

getLast

E getLast()

檢索但不刪除此雙端隊(duì)列的最后一個(gè)元素。 此方法與 peekLast 的不同之處僅在于如果此雙端隊(duì)列為空，它將引發(fā)異常。

返回:

這個(gè)雙端隊(duì)列的尾巴

Throws:

Throw名稱(chēng)	Throw描述
NoSuchElementException	如果此雙端隊(duì)列為空

peekFirst

E peekFirst()

檢索但不刪除此雙端隊(duì)列的第一個(gè)元素，如果此雙端隊(duì)列為空，則返回 null。

返回:

此雙端隊(duì)列的頭部，如果此雙端隊(duì)列為空，則返回 null

peekLast

E peekLast()

檢索但不刪除此雙端隊(duì)列的最后一個(gè)元素，如果此雙端隊(duì)列為空，則返回 null。

返回:

此雙端隊(duì)列的尾部，如果此雙端隊(duì)列為空，則返回 null

removeFirstOccurrence

boolean removeFirstOccurrence(Object o)

從此雙端隊(duì)列中刪除第一次出現(xiàn)的指定元素。 如果雙端隊(duì)列不包含該元素，則它保持不變。 更正式地說(shuō)，刪除第一個(gè)元素 e 使得 (o==null ? e==null : o.equals(e)) （如果存在這樣的元素）。 如果此雙端隊(duì)列包含指定元素（或等效地，如果此雙端隊(duì)列因調(diào)用而更改），則返回 true。

參數(shù)：

參數(shù)名稱(chēng)	參數(shù)描述
o	要從此雙端隊(duì)列中刪除的元素（如果存在）

返回:

如果由于此調(diào)用而刪除了元素，則為 true

Throws:

Throw名稱(chēng)	Throw描述
ClassCastException	如果指定元素的類(lèi)與此雙端隊(duì)列不兼容（可選）
NullPointerException	如果指定元素為空且此雙端隊(duì)列不允許空元素（可選）

removeLastOccurrence

boolean removeLastOccurrence(Object o)

從此雙端隊(duì)列中刪除最后一次出現(xiàn)的指定元素。 如果雙端隊(duì)列不包含該元素，則它保持不變。 更正式地說(shuō)，刪除最后一個(gè)元素 e 使得 (o==null ? e==null : o.equals(e)) （如果存在這樣的元素）。 如果此雙端隊(duì)列包含指定元素（或等效地，如果此雙端隊(duì)列因調(diào)用而更改），則返回 true。

參數(shù)：

參數(shù)名稱(chēng)	參數(shù)描述
o	要從此雙端隊(duì)列中刪除的元素（如果存在）

返回:

如果由于此調(diào)用而刪除了元素，則為 true

Throws:

Throw名稱(chēng)	Throw描述
ClassCastException	如果指定元素的類(lèi)與此雙端隊(duì)列不兼容（可選）
NullPointerException	如果指定元素為空且此雙端隊(duì)列不允許空元素（可選）

add

boolean add(E e)

如果可以在不違反容量限制的情況下立即將指定元素插入此雙端隊(duì)列表示的隊(duì)列中（換句話(huà)說(shuō)，在此雙端隊(duì)列的尾部），則在成功時(shí)返回 true 并在當(dāng)前沒(méi)有可用空間時(shí)拋出 IllegalStateException . 當(dāng)使用容量受限的雙端隊(duì)列時(shí)，通常最好使用 offer。

此方法等效于 addLast(E)。

指定者：

添加接口CollectionE

指定者：

添加接口QueueE

參數(shù)：

參數(shù)名稱(chēng)	參數(shù)描述
e	要添加的元素

返回:

true（由 Collection#add 指定）

Throws:

Throw名稱(chēng)	Throw描述
IllegalStateException	如果此時(shí)由于容量限制無(wú)法添加元素
ClassCastException	如果指定元素的類(lèi)阻止它被添加到這個(gè)雙端隊(duì)列
NullPointerException	如果指定元素為空且此雙端隊(duì)列不允許空元素
IllegalArgumentException	如果指定元素的某些屬性阻止它被添加到這個(gè)雙端隊(duì)列

offer

boolean offer(E e)

如果可以在不違反容量限制的情況下立即執(zhí)行此操作，則將指定元素插入此雙端隊(duì)列表示的隊(duì)列中（換句話(huà)說(shuō)，在此雙端隊(duì)列的尾部），成功時(shí)返回 true，如果當(dāng)前沒(méi)有可用空間則返回 false。 當(dāng)使用容量受限的雙端隊(duì)列時(shí)，此方法通常優(yōu)于 add(E) 方法，后者僅通過(guò)拋出異?？赡軣o(wú)法插入元素。

此方法等效于 offerLast(E)。

指定者：

接口QueueE中的offer

參數(shù)：

參數(shù)名稱(chēng)	參數(shù)描述
e	要添加的元素

返回:

如果元素已添加到此雙端隊(duì)列，則為 true，否則為 false

Throws:

Throw名稱(chēng)	Throw描述
ClassCastException	如果指定元素的類(lèi)阻止它被添加到這個(gè)雙端隊(duì)列
NullPointerException	如果指定元素為空且此雙端隊(duì)列不允許空元素
IllegalArgumentException	如果指定元素的某些屬性阻止它被添加到這個(gè)雙端隊(duì)列

remove

E remove()

檢索并刪除此雙端隊(duì)列表示的隊(duì)列的頭部（換句話(huà)說(shuō)，此雙端隊(duì)列的第一個(gè)元素）。 此方法與 poll 的不同之處僅在于如果此雙端隊(duì)列為空，它將引發(fā)異常。

此方法等效于 removeFirst()。

指定者：

在接口 QueueE 中刪除

返回：

此雙端隊(duì)列表示的隊(duì)列的頭部

Throws:

Throw名稱(chēng)	Throw描述
NoSuchElementException	如果此雙端隊(duì)列為空

poll

E poll()

檢索并刪除此雙端隊(duì)列表示的隊(duì)列的頭部（換句話(huà)說(shuō)，此雙端隊(duì)列的第一個(gè)元素），如果此雙端隊(duì)列為空，則返回 null。

此方法等效于 pollFirst()。

指定者：

在接口 QueueE 中輪詢(xún)

返回：

此雙端隊(duì)列的第一個(gè)元素，如果此雙端隊(duì)列為空，則返回 null

element

E element()

檢索但不刪除此雙端隊(duì)列表示的隊(duì)列的頭部（換句話(huà)說(shuō)，此雙端隊(duì)列的第一個(gè)元素）。 此方法與 peek 的不同之處僅在于如果此雙端隊(duì)列為空，它將引發(fā)異常。

此方法等效于 getFirst()。

指定者：

接口 QueueE 中的元素

返回：

此雙端隊(duì)列表示的隊(duì)列的頭部

Throws:

Throw名稱(chēng)	Throw描述
NoSuchElementException	如果此雙端隊(duì)列為空

peek

E peek()

檢索但不刪除此雙端隊(duì)列表示的隊(duì)列的頭部（換句話(huà)說(shuō)，此雙端隊(duì)列的第一個(gè)元素），如果此雙端隊(duì)列為空，則返回 null。

此方法等效于 peekFirst()。

指定者：

查看接口 QueueE

返回：

此雙端隊(duì)列表示的隊(duì)列的頭部，如果此雙端隊(duì)列為空，則返回 null

push

void push(E e)

如果可以在不違反容量限制的情況下立即將元素推送到此雙端隊(duì)列表示的堆棧上（換句話(huà)說(shuō)，在此雙端隊(duì)列的頭部），則如果當(dāng)前沒(méi)有可用空間則拋出 IllegalStateException。

此方法等效于 addFirst(E)。

參數(shù)：

參數(shù)名稱(chēng)	參數(shù)描述
e	要推送的元素

Throws:

Throw名稱(chēng)	Throw描述
IllegalStateException	如果此時(shí)由于容量限制無(wú)法添加元素
ClassCastException	如果指定元素的類(lèi)阻止它被添加到這個(gè)雙端隊(duì)列
NullPointerException	如果指定元素為空且此雙端隊(duì)列不允許空元素
IllegalArgumentException	如果指定元素的某些屬性阻止它被添加到這個(gè)雙端隊(duì)列

pop

E pop()

從這個(gè)雙端隊(duì)列表示的堆棧中彈出一個(gè)元素。 換句話(huà)說(shuō)，刪除并返回此雙端隊(duì)列的第一個(gè)元素。

此方法等效于 removeFirst()。

返回:

這個(gè)雙端隊(duì)列前面的元素（這是這個(gè)雙端隊(duì)列表示的堆棧的頂部）

Throws:

Throw名稱(chēng)	Throw描述
NoSuchElementException	如果此雙端隊(duì)列為空

remove

boolean remove(Object o)

從此雙端隊(duì)列中刪除第一次出現(xiàn)的指定元素。 如果雙端隊(duì)列不包含該元素，則它保持不變。 更正式地說(shuō)，刪除第一個(gè)元素 e 使得 (o==null ? e==null : o.equals(e)) （如果存在這樣的元素）。 如果此雙端隊(duì)列包含指定元素（或等效地，如果此雙端隊(duì)列因調(diào)用而更改），則返回 true。

此方法等效于 removeFirstOccurrence(java.lang.Object)。

指定者：

在接口 CollectionE 中刪除

參數(shù):

參數(shù)名稱(chēng)	參數(shù)描述
o	要從此雙端隊(duì)列中刪除的元素（如果存在）

返回:

如果由于此調(diào)用而刪除了元素，則為 true

Throws:

Throw名稱(chēng)	Throw描述
ClassCastException	如果指定元素的類(lèi)與此雙端隊(duì)列不兼容（可選）
NullPointerException	如果指定元素為空且此雙端隊(duì)列不允許空元素（可選）

contains

boolean contains(Object o)

如果此雙端隊(duì)列包含指定元素，則返回 true。 更正式地說(shuō)，當(dāng)且僅當(dāng)此雙端隊(duì)列包含至少一個(gè)元素 e 使得 (o==null ? e==null : o.equals(e)) 時(shí)返回 true。

指定者：

包含在接口 CollectionE 中

參數(shù)：

參數(shù)名稱(chēng)	參數(shù)描述
o	要測(cè)試其在此雙端隊(duì)列中的存在的元素

返回:

如果此雙端隊(duì)列包含指定元素，則為 true

Throws:

Throw名稱(chēng)	Throw描述
ClassCastException	如果指定元素的類(lèi)型與此雙端隊(duì)列不兼容（可選）
NullPointerException	如果指定元素為空且此雙端隊(duì)列不允許空元素（可選）

size

int size()

返回此雙端隊(duì)列中的元素?cái)?shù)。

指定者：

接口 CollectionE 中的大小

返回:

此雙端隊(duì)列中的元素?cái)?shù)量

iterator

IteratorE iterator()

以正確的順序返回此雙端隊(duì)列中元素的迭代器。 元素將按從第一個(gè)（頭）到最后一個(gè)（尾）的順序返回。

指定者：

接口 CollectionE 中的迭代器

指定者：

接口 IterableE 中的迭代器

返回:

以正確順序?qū)υ撾p端隊(duì)列中的元素進(jìn)行迭代

descendingIterator

IteratorE descendingIterator()

以相反的順序返回此雙端隊(duì)列中元素的迭代器。 元素將按從最后（尾）到第一個(gè)（頭）的順序返回。

返回:

以相反順序?qū)υ撾p端隊(duì)列中的元素進(jìn)行迭代