树叶云鸿蒙OS教程：鸿蒙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 集合框架的成员。

方法总结

方法详情

addFirst

void addFirst(E e)

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

参数：

Throws:

addLast

void addLast(E e)

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

此方法等效于 add(E)。

参数：

Throws:

offerFirst

boolean offerFirst(E e)

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

参数：

返回:

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

Throws:

offerLast

boolean offerLast(E e)

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

参数：

返回:

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

Throws:

removeFirst

E removeFirst()

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

返回:

这个双端队列的头

Throws:

removeLast

E removeLast()

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

返回:

这个双端队列的尾巴

Throws:

pollFirst

E pollFirst()

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

返回:

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

pollLast

E pollLast()

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

返回:

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

getFirst

E getFirst()

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

返回:

这个双端队列的头

Throws:

getLast

E getLast()

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

返回:

这个双端队列的尾巴

Throws:

peekFirst

E peekFirst()

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

返回:

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

peekLast

E peekLast()

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

返回:

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

removeFirstOccurrence

boolean removeFirstOccurrence(Object o)

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

参数：

返回:

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

Throws:

removeLastOccurrence

boolean removeLastOccurrence(Object o)

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

参数：

返回:

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

Throws:

add

boolean add(E e)

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

此方法等效于 addLast(E)。

指定者：

添加接口CollectionE

指定者：

添加接口QueueE

参数：

返回:

true（由 Collection#add 指定）

Throws:

offer

boolean offer(E e)

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

此方法等效于 offerLast(E)。

指定者：

接口QueueE中的offer

参数：

返回:

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

Throws:

remove

E remove()

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

此方法等效于 removeFirst()。

指定者：

在接口 QueueE 中删除

返回：

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

Throws:

poll

E poll()

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

此方法等效于 pollFirst()。

指定者：

在接口 QueueE 中轮询

返回：

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

element

E element()

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

此方法等效于 getFirst()。

指定者：

接口 QueueE 中的元素

返回：

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

Throws:

peek

E peek()

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

此方法等效于 peekFirst()。

指定者：

查看接口 QueueE

返回：

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

push

void push(E e)

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

此方法等效于 addFirst(E)。

参数：

Throws:

pop

E pop()

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

此方法等效于 removeFirst()。

返回:

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

Throws:

remove

boolean remove(Object o)

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

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

指定者：

在接口 CollectionE 中删除

参数:

返回:

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

Throws:

contains

boolean contains(Object o)

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

指定者：

包含在接口 CollectionE 中

参数：

返回:

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

Throws:

size

int size()

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

指定者：

接口 CollectionE 中的大小

返回:

此双端队列中的元素数量

iterator

IteratorE iterator()

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

指定者：

接口 CollectionE 中的迭代器

指定者：

接口 IterableE 中的迭代器

返回:

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

descendingIterator

IteratorE descendingIterator()

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

返回:

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