鸿蒙OS Deque

Deque

public interface Deque<E>
extends Queue<E>

支持两端元素插入和移除的线性集合。 名称 deque 是“双端队列”的缩写，通常发音为“deck”。 大多数 Deque 实现对其可能包含的元素数量没有固定限制，但此接口支持容量受限的双端队列以及没有固定大小限制的双端队列。

该接口定义了访问双端队列两端元素的方法。 提供了插入、删除和检查元素的方法。 这些方法中的每一种都以两种形式存在：一种在操作失败时抛出异常，另一种返回一个特殊值（null 或 false，取决于操作）。 后一种形式的插入操作是专门为容量受限的 Deque 实现而设计的； 在大多数实现中，插入操作不会失败。

下表总结了上述十二种方法：

该接口扩展了 Queue 接口。 当双端队列用作队列时，会产生 FIFO（先进先出）行为。 元素在双端队列的末尾添加并从开头删除。 从 Queue 接口继承的方法与 Deque 方法完全等价，如下表所示：

双端队列也可以用作 LIFO（后进先出）堆栈。应优先使用此接口而不是旧的 Stack 类。当双端队列用作堆栈时，从双端队列的开头推送和弹出元素。 Stack 方法完全等同于 Deque 方法，如下表所示：

请注意，当双端队列用作队列或堆栈时，peek 方法同样有效；在任何一种情况下，元素都是从双端队列的开头绘制的。

该接口提供了两种移除内部元素的方法，removeFirstOccurrence 和 removeLastOccurrence。

与 List 接口不同，此接口不支持对元素的索引访问。

虽然没有严格要求 Deque 实现禁止插入 null 元素，但强烈鼓励他们这样做。强烈建议允许使用 null 元素的任何 Deque 实现的用户不要利用插入 null 的能力。这是因为 null 被各种方法用作特殊返回值来指示双端队列为空。

Deque 实现通常不定义 equals 和 hashCode 方法的基于元素的版本，而是从类 Object 继承基于身份的版本。

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

方法总结

修饰符和类型	方法	描述
boolean	add(E e)	如果可以在不违反容量限制的情况下立即将指定元素插入此双端队列表示的队列中（换句话说，在此双端队列的尾部），则在成功时返回 true 并在当前没有可用空间时抛出 IllegalStateException .
void	addFirst(E e)	如果可以在不违反容量限制的情况下立即插入指定元素，则在此双端队列的前面插入指定元素，如果当前没有可用空间，则抛出 IllegalStateException。
void	addLast(E e)	如果可以在不违反容量限制的情况下立即插入指定元素，则在此双端队列末尾插入指定元素，如果当前没有可用空间，则抛出 IllegalStateException。
boolean	contains(Object o)	如果此双端队列包含指定元素，则返回 true。
IteratorE	descendingIterator()	以相反的顺序返回此双端队列中元素的迭代器。
E	element()	检索但不删除此双端队列表示的队列的头部（换句话说，此双端队列的第一个元素）。
E	getFirst()	检索但不删除此双端队列的第一个元素。
E	getLast()	检索但不删除此双端队列的最后一个元素。
IteratorE	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 继承的方法
addAll, clear, containsAll, equals, hashCode, isEmpty, parallelStream, removeAll, removeIf, retainAll, spliterator, stream, toArray, toArray

从接口 java.lang.Iterable 继承的方法
forEach

方法详情

addFirst

void addFirst(E e)

如果可以在不违反容量限制的情况下立即插入指定元素，则在此双端队列的前面插入指定元素，如果当前没有可用空间，则抛出 IllegalStateException。 当使用容量受限的双端队列时，通常最好使用方法 offerFirst(E)。

参数：

参数名称	参数描述
e	要添加的元素

Throws:

Throw名称	Throw描述
IllegalStateException	如果此时由于容量限制无法添加元素
ClassCastException	如果指定元素的类阻止它被添加到这个双端队列
NullPointerException	如果指定元素为空且此双端队列不允许空元素
IllegalArgumentException	如果指定元素的某些属性阻止它被添加到这个双端队列

addLast

void addLast(E e)

如果可以在不违反容量限制的情况下立即插入指定元素，则在此双端队列末尾插入指定元素，如果当前没有可用空间，则抛出 IllegalStateException。 当使用容量受限的双端队列时，通常最好使用方法 offerLast(E)。

此方法等效于 add(E)。

参数：

参数名称	参数描述
e	要添加的元素

Throws:

Throw名称	Throw描述
IllegalStateException	如果此时由于容量限制无法添加元素
ClassCastException	如果指定元素的类阻止它被添加到这个双端队列
NullPointerException	如果指定元素为空且此双端队列不允许空元素
IllegalArgumentException	如果指定元素的某些属性阻止它被添加到这个双端队列

offerFirst

boolean offerFirst(E e)

在此双端队列的前面插入指定元素，除非它违反容量限制。 当使用容量受限的双端队列时，此方法通常优于 addFirst(E) 方法，后者仅通过抛出异常可能无法插入元素。

参数：

参数名称	参数描述
e	要添加的元素

返回:

如果元素已添加到此双端队列，则为 true，否则为 false

Throws:

Throw名称	Throw描述
ClassCastException	如果指定元素的类阻止它被添加到这个双端队列
NullPointerException	如果指定元素为空且此双端队列不允许空元素
IllegalArgumentException	如果指定元素的某些属性阻止它被添加到这个双端队列

offerLast

boolean offerLast(E e)

在此双端队列末尾插入指定元素，除非它违反容量限制。 当使用容量受限的双端队列时，此方法通常优于 addLast(E) 方法，后者仅通过抛出异常可能无法插入元素。

参数：

参数名称	参数描述
e	要添加的元素

返回:

如果元素已添加到此双端队列，则为 true，否则为 false

Throws:

Throw名称	Throw描述
ClassCastException	如果指定元素的类阻止它被添加到这个双端队列
NullPointerException	如果指定元素为空且此双端队列不允许空元素
IllegalArgumentException	如果指定元素的某些属性阻止它被添加到这个双端队列

removeFirst

E removeFirst()

检索并删除此双端队列的第一个元素。 此方法与 pollFirst 的不同之处仅在于如果此双端队列为空，它将引发异常。

返回:

这个双端队列的头

Throws:

Throw名称	Throw描述
NoSuchElementException	如果此双端队列为空

removeLast

E removeLast()

检索并删除此双端队列的最后一个元素。 此方法与 pollLast 的不同之处仅在于如果此双端队列为空，它将引发异常。

返回:

这个双端队列的尾巴

Throws:

Throw名称	Throw描述
NoSuchElementException	如果此双端队列为空

pollFirst

E pollFirst()

检索并删除此双端队列的第一个元素，如果此双端队列为空，则返回 null。

返回:

此双端队列的头部，如果此双端队列为空，则返回 null

pollLast

E pollLast()

检索并删除此双端队列的最后一个元素，如果此双端队列为空，则返回 null。

返回:

此双端队列的尾部，如果此双端队列为空，则返回 null

getFirst

E getFirst()

检索但不删除此双端队列的第一个元素。 此方法与 peekFirst 的不同之处仅在于如果此双端队列为空，它将引发异常。

返回:

这个双端队列的头

Throws:

Throw名称	Throw描述
NoSuchElementException	如果此双端队列为空

getLast

E getLast()

检索但不删除此双端队列的最后一个元素。 此方法与 peekLast 的不同之处仅在于如果此双端队列为空，它将引发异常。

返回:

这个双端队列的尾巴

Throws:

Throw名称	Throw描述
NoSuchElementException	如果此双端队列为空

peekFirst

E peekFirst()

检索但不删除此双端队列的第一个元素，如果此双端队列为空，则返回 null。

返回:

此双端队列的头部，如果此双端队列为空，则返回 null

peekLast

E peekLast()

检索但不删除此双端队列的最后一个元素，如果此双端队列为空，则返回 null。

返回:

此双端队列的尾部，如果此双端队列为空，则返回 null

removeFirstOccurrence

boolean removeFirstOccurrence(Object o)

从此双端队列中删除第一次出现的指定元素。 如果双端队列不包含该元素，则它保持不变。 更正式地说，删除第一个元素 e 使得 (o==null ? e==null : o.equals(e)) （如果存在这样的元素）。 如果此双端队列包含指定元素（或等效地，如果此双端队列因调用而更改），则返回 true。

参数：

参数名称	参数描述
o	要从此双端队列中删除的元素（如果存在）

返回:

如果由于此调用而删除了元素，则为 true

Throws:

Throw名称	Throw描述
ClassCastException	如果指定元素的类与此双端队列不兼容（可选）
NullPointerException	如果指定元素为空且此双端队列不允许空元素（可选）

removeLastOccurrence

boolean removeLastOccurrence(Object o)

从此双端队列中删除最后一次出现的指定元素。 如果双端队列不包含该元素，则它保持不变。 更正式地说，删除最后一个元素 e 使得 (o==null ? e==null : o.equals(e)) （如果存在这样的元素）。 如果此双端队列包含指定元素（或等效地，如果此双端队列因调用而更改），则返回 true。

参数：

参数名称	参数描述
o	要从此双端队列中删除的元素（如果存在）

返回:

如果由于此调用而删除了元素，则为 true

Throws:

Throw名称	Throw描述
ClassCastException	如果指定元素的类与此双端队列不兼容（可选）
NullPointerException	如果指定元素为空且此双端队列不允许空元素（可选）

add

boolean add(E e)

如果可以在不违反容量限制的情况下立即将指定元素插入此双端队列表示的队列中（换句话说，在此双端队列的尾部），则在成功时返回 true 并在当前没有可用空间时抛出 IllegalStateException . 当使用容量受限的双端队列时，通常最好使用 offer。

此方法等效于 addLast(E)。

指定者：

添加接口CollectionE

指定者：

添加接口QueueE

参数：

参数名称	参数描述
e	要添加的元素

返回:

true（由 Collection#add 指定）

Throws:

Throw名称	Throw描述
IllegalStateException	如果此时由于容量限制无法添加元素
ClassCastException	如果指定元素的类阻止它被添加到这个双端队列
NullPointerException	如果指定元素为空且此双端队列不允许空元素
IllegalArgumentException	如果指定元素的某些属性阻止它被添加到这个双端队列

offer

boolean offer(E e)

如果可以在不违反容量限制的情况下立即执行此操作，则将指定元素插入此双端队列表示的队列中（换句话说，在此双端队列的尾部），成功时返回 true，如果当前没有可用空间则返回 false。 当使用容量受限的双端队列时，此方法通常优于 add(E) 方法，后者仅通过抛出异常可能无法插入元素。

此方法等效于 offerLast(E)。

指定者：

接口QueueE中的offer

参数：

参数名称	参数描述
e	要添加的元素

返回:

如果元素已添加到此双端队列，则为 true，否则为 false

Throws:

Throw名称	Throw描述
ClassCastException	如果指定元素的类阻止它被添加到这个双端队列
NullPointerException	如果指定元素为空且此双端队列不允许空元素
IllegalArgumentException	如果指定元素的某些属性阻止它被添加到这个双端队列

remove

E remove()

检索并删除此双端队列表示的队列的头部（换句话说，此双端队列的第一个元素）。 此方法与 poll 的不同之处仅在于如果此双端队列为空，它将引发异常。

此方法等效于 removeFirst()。

指定者：

在接口 QueueE 中删除

返回：

此双端队列表示的队列的头部

Throws:

Throw名称	Throw描述
NoSuchElementException	如果此双端队列为空

poll

E poll()

检索并删除此双端队列表示的队列的头部（换句话说，此双端队列的第一个元素），如果此双端队列为空，则返回 null。

此方法等效于 pollFirst()。

指定者：

在接口 QueueE 中轮询

返回：

此双端队列的第一个元素，如果此双端队列为空，则返回 null

element

E element()

检索但不删除此双端队列表示的队列的头部（换句话说，此双端队列的第一个元素）。 此方法与 peek 的不同之处仅在于如果此双端队列为空，它将引发异常。

此方法等效于 getFirst()。

指定者：

接口 QueueE 中的元素

返回：

此双端队列表示的队列的头部

Throws:

Throw名称	Throw描述
NoSuchElementException	如果此双端队列为空

peek

E peek()

检索但不删除此双端队列表示的队列的头部（换句话说，此双端队列的第一个元素），如果此双端队列为空，则返回 null。

此方法等效于 peekFirst()。

指定者：

查看接口 QueueE

返回：

此双端队列表示的队列的头部，如果此双端队列为空，则返回 null

push

void push(E e)

如果可以在不违反容量限制的情况下立即将元素推送到此双端队列表示的堆栈上（换句话说，在此双端队列的头部），则如果当前没有可用空间则抛出 IllegalStateException。

此方法等效于 addFirst(E)。

参数：

参数名称	参数描述
e	要推送的元素

Throws:

Throw名称	Throw描述
IllegalStateException	如果此时由于容量限制无法添加元素
ClassCastException	如果指定元素的类阻止它被添加到这个双端队列
NullPointerException	如果指定元素为空且此双端队列不允许空元素
IllegalArgumentException	如果指定元素的某些属性阻止它被添加到这个双端队列

pop

E pop()

从这个双端队列表示的堆栈中弹出一个元素。 换句话说，删除并返回此双端队列的第一个元素。

此方法等效于 removeFirst()。

返回:

这个双端队列前面的元素（这是这个双端队列表示的堆栈的顶部）

Throws:

Throw名称	Throw描述
NoSuchElementException	如果此双端队列为空

remove

boolean remove(Object o)

从此双端队列中删除第一次出现的指定元素。 如果双端队列不包含该元素，则它保持不变。 更正式地说，删除第一个元素 e 使得 (o==null ? e==null : o.equals(e)) （如果存在这样的元素）。 如果此双端队列包含指定元素（或等效地，如果此双端队列因调用而更改），则返回 true。

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

指定者：

在接口 CollectionE 中删除

参数:

参数名称	参数描述
o	要从此双端队列中删除的元素（如果存在）

返回:

如果由于此调用而删除了元素，则为 true

Throws:

Throw名称	Throw描述
ClassCastException	如果指定元素的类与此双端队列不兼容（可选）
NullPointerException	如果指定元素为空且此双端队列不允许空元素（可选）

contains

boolean contains(Object o)

如果此双端队列包含指定元素，则返回 true。 更正式地说，当且仅当此双端队列包含至少一个元素 e 使得 (o==null ? e==null : o.equals(e)) 时返回 true。

指定者：

包含在接口 CollectionE 中

参数：

参数名称	参数描述
o	要测试其在此双端队列中的存在的元素

返回:

如果此双端队列包含指定元素，则为 true

Throws:

Throw名称	Throw描述
ClassCastException	如果指定元素的类型与此双端队列不兼容（可选）
NullPointerException	如果指定元素为空且此双端队列不允许空元素（可选）

size

int size()

返回此双端队列中的元素数。

指定者：

接口 CollectionE 中的大小

返回:

此双端队列中的元素数量

iterator

IteratorE iterator()

以正确的顺序返回此双端队列中元素的迭代器。 元素将按从第一个（头）到最后一个（尾）的顺序返回。

指定者：

接口 CollectionE 中的迭代器

指定者：

接口 IterableE 中的迭代器

返回:

以正确顺序对该双端队列中的元素进行迭代

descendingIterator

IteratorE descendingIterator()

以相反的顺序返回此双端队列中元素的迭代器。 元素将按从最后（尾）到第一个（头）的顺序返回。

返回:

以相反顺序对该双端队列中的元素进行迭代