鴻蒙OS Deque

Deque

public interface Deque<E>
extends Queue<E>

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

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

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

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

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

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

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

與 List 接口不同，此接口不支持對元素的索引訪問。

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

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

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

方法總結(jié)

修飾符和類型	方法	描述
boolean	add(E e)	如果可以在不違反容量限制的情況下立即將指定元素插入此雙端隊列表示的隊列中（換句話說，在此雙端隊列的尾部），則在成功時返回 true 并在當(dāng)前沒有可用空間時拋出 IllegalStateException .
void	addFirst(E e)	如果可以在不違反容量限制的情況下立即插入指定元素，則在此雙端隊列的前面插入指定元素，如果當(dāng)前沒有可用空間，則拋出 IllegalStateException。
void	addLast(E e)	如果可以在不違反容量限制的情況下立即插入指定元素，則在此雙端隊列末尾插入指定元素，如果當(dāng)前沒有可用空間，則拋出 IllegalStateException。
boolean	contains(Object o)	如果此雙端隊列包含指定元素，則返回 true。
IteratorE	descendingIterator()	以相反的順序返回此雙端隊列中元素的迭代器。
E	element()	檢索但不刪除此雙端隊列表示的隊列的頭部（換句話說，此雙端隊列的第一個元素）。
E	getFirst()	檢索但不刪除此雙端隊列的第一個元素。
E	getLast()	檢索但不刪除此雙端隊列的最后一個元素。
IteratorE	iterator()	以正確的順序返回此雙端隊列中元素的迭代器。
boolean	offer(E e)	如果可以在不違反容量限制的情況下立即執(zhí)行此操作，則將指定元素插入此雙端隊列表示的隊列中（換句話說，在此雙端隊列的尾部），成功時返回 true，如果當(dāng)前沒有可用空間則返回 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)	如果可以在不違反容量限制的情況下立即將元素推送到此雙端隊列表示的堆棧上（換句話說，在此雙端隊列的頭部），則如果當(dāng)前沒有可用空間則拋出 IllegalStateException。
E	remove()	檢索并刪除此雙端隊列表示的隊列的頭部（換句話說，此雙端隊列的第一個元素）。
boolean	remove(Object o)	從此雙端隊列中刪除第一次出現(xiàn)的指定元素。
E	removeFirst()	檢索并刪除此雙端隊列的第一個元素。
boolean	removeFirstOccurrence(Object o)	從此雙端隊列中刪除第一次出現(xiàn)的指定元素。
E	removeLast()	檢索并刪除此雙端隊列的最后一個元素。
boolean	removeLastOccurrence(Object o)	從此雙端隊列中刪除最后一次出現(xiàn)的指定元素。
int	size()	返回此雙端隊列中的元素數(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)

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

參數(shù)：

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

Throws:

Throw名稱	Throw描述
IllegalStateException	如果此時由于容量限制無法添加元素
ClassCastException	如果指定元素的類阻止它被添加到這個雙端隊列
NullPointerException	如果指定元素為空且此雙端隊列不允許空元素
IllegalArgumentException	如果指定元素的某些屬性阻止它被添加到這個雙端隊列

addLast

void addLast(E e)

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

此方法等效于 add(E)。

參數(shù)：

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

Throws:

Throw名稱	Throw描述
IllegalStateException	如果此時由于容量限制無法添加元素
ClassCastException	如果指定元素的類阻止它被添加到這個雙端隊列
NullPointerException	如果指定元素為空且此雙端隊列不允許空元素
IllegalArgumentException	如果指定元素的某些屬性阻止它被添加到這個雙端隊列

offerFirst

boolean offerFirst(E e)

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

參數(shù)：

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

返回:

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

Throws:

Throw名稱	Throw描述
ClassCastException	如果指定元素的類阻止它被添加到這個雙端隊列
NullPointerException	如果指定元素為空且此雙端隊列不允許空元素
IllegalArgumentException	如果指定元素的某些屬性阻止它被添加到這個雙端隊列

offerLast

boolean offerLast(E e)

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

參數(shù)：

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

返回:

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

Throws:

Throw名稱	Throw描述
ClassCastException	如果指定元素的類阻止它被添加到這個雙端隊列
NullPointerException	如果指定元素為空且此雙端隊列不允許空元素
IllegalArgumentException	如果指定元素的某些屬性阻止它被添加到這個雙端隊列

removeFirst

E removeFirst()

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

返回:

這個雙端隊列的頭

Throws:

Throw名稱	Throw描述
NoSuchElementException	如果此雙端隊列為空

removeLast

E removeLast()

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

返回:

這個雙端隊列的尾巴

Throws:

Throw名稱	Throw描述
NoSuchElementException	如果此雙端隊列為空

pollFirst

E pollFirst()

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

返回:

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

pollLast

E pollLast()

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

返回:

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

getFirst

E getFirst()

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

返回:

這個雙端隊列的頭

Throws:

Throw名稱	Throw描述
NoSuchElementException	如果此雙端隊列為空

getLast

E getLast()

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

返回:

這個雙端隊列的尾巴

Throws:

Throw名稱	Throw描述
NoSuchElementException	如果此雙端隊列為空

peekFirst

E peekFirst()

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

返回:

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

peekLast

E peekLast()

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

返回:

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

removeFirstOccurrence

boolean removeFirstOccurrence(Object o)

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

參數(shù)：

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

返回:

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

Throws:

Throw名稱	Throw描述
ClassCastException	如果指定元素的類與此雙端隊列不兼容（可選）
NullPointerException	如果指定元素為空且此雙端隊列不允許空元素（可選）

removeLastOccurrence

boolean removeLastOccurrence(Object o)

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

參數(shù)：

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

返回:

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

Throws:

Throw名稱	Throw描述
ClassCastException	如果指定元素的類與此雙端隊列不兼容（可選）
NullPointerException	如果指定元素為空且此雙端隊列不允許空元素（可選）

add

boolean add(E e)

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

此方法等效于 addLast(E)。

指定者：

添加接口CollectionE

指定者：

添加接口QueueE

參數(shù)：

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

返回:

true（由 Collection#add 指定）

Throws:

Throw名稱	Throw描述
IllegalStateException	如果此時由于容量限制無法添加元素
ClassCastException	如果指定元素的類阻止它被添加到這個雙端隊列
NullPointerException	如果指定元素為空且此雙端隊列不允許空元素
IllegalArgumentException	如果指定元素的某些屬性阻止它被添加到這個雙端隊列

offer

boolean offer(E e)

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

此方法等效于 offerLast(E)。

指定者：

接口QueueE中的offer

參數(shù)：

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

返回:

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

Throws:

Throw名稱	Throw描述
ClassCastException	如果指定元素的類阻止它被添加到這個雙端隊列
NullPointerException	如果指定元素為空且此雙端隊列不允許空元素
IllegalArgumentException	如果指定元素的某些屬性阻止它被添加到這個雙端隊列

remove

E remove()

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

此方法等效于 removeFirst()。

指定者：

在接口 QueueE 中刪除

返回：

此雙端隊列表示的隊列的頭部

Throws:

Throw名稱	Throw描述
NoSuchElementException	如果此雙端隊列為空

poll

E poll()

檢索并刪除此雙端隊列表示的隊列的頭部（換句話說，此雙端隊列的第一個元素），如果此雙端隊列為空，則返回 null。

此方法等效于 pollFirst()。

指定者：

在接口 QueueE 中輪詢

返回：

此雙端隊列的第一個元素，如果此雙端隊列為空，則返回 null

element

E element()

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

此方法等效于 getFirst()。

指定者：

接口 QueueE 中的元素

返回：

此雙端隊列表示的隊列的頭部

Throws:

Throw名稱	Throw描述
NoSuchElementException	如果此雙端隊列為空

peek

E peek()

檢索但不刪除此雙端隊列表示的隊列的頭部（換句話說，此雙端隊列的第一個元素），如果此雙端隊列為空，則返回 null。

此方法等效于 peekFirst()。

指定者：

查看接口 QueueE

返回：

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

push

void push(E e)

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

此方法等效于 addFirst(E)。

參數(shù)：

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

Throws:

Throw名稱	Throw描述
IllegalStateException	如果此時由于容量限制無法添加元素
ClassCastException	如果指定元素的類阻止它被添加到這個雙端隊列
NullPointerException	如果指定元素為空且此雙端隊列不允許空元素
IllegalArgumentException	如果指定元素的某些屬性阻止它被添加到這個雙端隊列

pop

E pop()

從這個雙端隊列表示的堆棧中彈出一個元素。 換句話說，刪除并返回此雙端隊列的第一個元素。

此方法等效于 removeFirst()。

返回:

這個雙端隊列前面的元素（這是這個雙端隊列表示的堆棧的頂部）

Throws:

Throw名稱	Throw描述
NoSuchElementException	如果此雙端隊列為空

remove

boolean remove(Object o)

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

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

指定者：

在接口 CollectionE 中刪除

參數(shù):

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

返回:

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

Throws:

Throw名稱	Throw描述
ClassCastException	如果指定元素的類與此雙端隊列不兼容（可選）
NullPointerException	如果指定元素為空且此雙端隊列不允許空元素（可選）

contains

boolean contains(Object o)

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

指定者：

包含在接口 CollectionE 中

參數(shù)：

參數(shù)名稱	參數(shù)描述
o	要測試其在此雙端隊列中的存在的元素

返回:

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

Throws:

Throw名稱	Throw描述
ClassCastException	如果指定元素的類型與此雙端隊列不兼容（可選）
NullPointerException	如果指定元素為空且此雙端隊列不允許空元素（可選）

size

int size()

返回此雙端隊列中的元素數(shù)。

指定者：

接口 CollectionE 中的大小

返回:

此雙端隊列中的元素數(shù)量

iterator

IteratorE iterator()

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

指定者：

接口 CollectionE 中的迭代器

指定者：

接口 IterableE 中的迭代器

返回:

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

descendingIterator

IteratorE descendingIterator()

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

返回:

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