鸿蒙OS List

List

public interface List<E>
extends Collection<E>

有序集合（也称为序列）。 此界面的用户可以精确控制每个元素在列表中的插入位置。 用户可以通过整数索引（列表中的位置）访问元素，并在列表中搜索元素。

与集合不同，列表通常允许重复元素。 更正式地说，列表通常允许元素 e1 和 e2 对，例如 e1.equals(e2)，并且如果它们完全允许 null 元素，它们通常允许多个 null 元素。 有人可能希望通过在用户尝试插入它们时抛出运行时异常来实现一个禁止重复的列表，这并非不可想象，但我们希望这种用法很少见。

List 接口对迭代器、add、remove、equals 和 hashCode 方法的合约添加了超出 Collection 接口中指定的附加规定。 为方便起见，此处还包括其他继承方法的声明。

List 接口提供了四种对列表元素进行位置（索引）访问的方法。 列表（如 Java 数组）是从零开始的。 请注意，对于某些实现（例如 LinkedList 类），这些操作的执行时间可能与索引值成正比。 因此，如果调用者不知道实现，则迭代列表中的元素通常比通过它索引更可取。

List 接口提供了一个特殊的迭代器，称为 ListIterator，除了 Iterator 接口提供的正常操作之外，它还允许元素插入和替换以及双向访问。 提供了一种方法来获取从列表中指定位置开始的列表迭代器。

List 接口提供了两种方法来搜索指定的对象。 从性能的角度来看，应谨慎使用这些方法。 在许多实现中，它们将执行代价高昂的线性搜索。

List 接口提供了两种方法来有效地在列表中的任意点插入和删除多个元素。

注意：虽然允许列表将自身包含为元素，但建议格外小心：equals 和 hashCode 方法不再在此类列表上得到很好的定义。

一些列表实现对它们可能包含的元素有限制。 例如，一些实现禁止空元素，而一些实现对其元素的类型有限制。 尝试添加不合格的元素会引发未经检查的异常，通常是 NullPointerException 或 ClassCastException。 尝试查询不合格元素的存在可能会引发异常，或者它可能只是返回 false； 一些实现会表现出前一种行为，而另一些会表现出后者。 更一般地，尝试对不合格元素进行操作，其完成不会导致将不合格元素插入到列表中，这可能会引发异常，也可能会成功，这取决于实现的选择。 此类异常在此接口的规范中被标记为“可选”。

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

方法总结

修饰符和类型	方法	描述
void	add(int index, E element)	在此列表中的指定位置插入指定元素（可选操作）。
boolean	add(E e)	将指定元素附加到此列表的末尾（可选操作）。
boolean	addAll(int index, Collection<? extends E> c)	将指定集合中的所有元素插入到此列表中的指定位置（可选操作）。
boolean	addAll(Collection<? extends E> c)	将指定集合中的所有元素附加到此列表的末尾，按照指定集合的迭代器返回的顺序（可选操作）。
void	clear()	从此列表中删除所有元素（可选操作）。
boolean	contains(Object o)	如果此列表包含指定元素，则返回 true。
boolean	containsAll(Collection<?> c)	如果此列表包含指定集合的所有元素，则返回 true。
boolean	equals(Object o)	比较指定对象与此列表是否相等。
E	get(int index)	返回此列表中指定位置的元素。
int	hashCode()	返回此列表的哈希码值。
int	indexOf(Object o)	返回此列表中指定元素第一次出现的索引，如果此列表不包含该元素，则返回 -1。
boolean	isEmpty()	如果此列表不包含任何元素，则返回 true。
IteratorE	iterator()	以正确的顺序返回此列表中元素的迭代器。
int	lastIndexOf(Object o)	返回此列表中指定元素最后一次出现的索引，如果此列表不包含该元素，则返回 -1。
ListIteratorE	listIterator()	返回此列表中元素的列表迭代器（以正确的顺序）。
ListIteratorE	listIterator(int index)	返回此列表中元素的列表迭代器（以正确的顺序），从列表中的指定位置开始。
E	remove(int index)	移除此列表中指定位置的元素（可选操作）。
boolean	remove(Object o)	如果指定元素存在，则从该列表中删除第一次出现的指定元素（可选操作）。
boolean	removeAll(Collection<?> c)	从此列表中删除包含在指定集合中的所有元素（可选操作）。
default void	replaceAll(UnaryOperatorE operator)	将此列表的每个元素替换为将运算符应用于该元素的结果。
boolean	retainAll(Collection<?> c)	仅保留此列表中包含在指定集合中的元素（可选操作）。
E	set(int index, E element)	将此列表中指定位置的元素替换为指定元素（可选操作）。
int	size()	返回此列表中的元素数。
default void	sort(Comparator<? super E> c)	根据指定 Comparator 产生的顺序对该列表进行排序。
default SpliteratorE	spliterator()	在此列表中的元素上创建一个 Spliterator。
ListE	subList(int fromIndex, int toIndex)	返回此列表在指定的 fromIndex（包括）和 toIndex（不包括）之间的部分的视图。
Object[]	toArray()	以正确的顺序（从第一个元素到最后一个元素）返回包含此列表中所有元素的数组。
<T> T[]	toArray(T[] a)	以正确的顺序（从第一个元素到最后一个元素）返回一个包含此列表中所有元素的数组； 返回数组的运行时类型是指定数组的运行时类型。

从接口 java.util.Collection 继承的方法
parallelStream, removeIf, stream

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

方法详情

size

int size()

返回此列表中的元素数。 如果此列表包含多个 Integer.MAX_VALUE 元素，则返回 Integer.MAX_VALUE。

指定者：

接口 CollectionE 中的大小

返回:

此列表中的元素数

isEmpty

boolean isEmpty()

如果此列表不包含任何元素，则返回 true。

指定者：

接口 CollectionE 中的 isEmpty

返回:

如果此列表不包含任何元素，则为 true

contains

boolean contains(Object o)

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

指定者：

包含在接口 CollectionE 中

参数：

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

返回:

如果此列表包含指定元素，则为 true

Throws:

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

iterator

IteratorE iterator()

以正确的顺序返回此列表中元素的迭代器。

指定者：

接口 CollectionE 中的迭代器

指定者：

接口 IterableE 中的迭代器

返回:

以正确顺序遍历此列表中的元素的迭代器

toArray

Object[] toArray()

以正确的顺序（从第一个元素到最后一个元素）返回包含此列表中所有元素的数组。

返回的数组将是“安全的”，因为此列表不维护对它的引用。 （换句话说，即使此列表由数组支持，此方法也必须分配一个新数组）。 因此，调用者可以自由修改返回的数组。

此方法充当基于数组和基于集合的 API 之间的桥梁。

指定者：

接口 CollectionE 中的 toArray

返回:

以正确顺序包含此列表中所有元素的数组

toArray

<T> T[] toArray(T[] a)

以正确的顺序（从第一个元素到最后一个元素）返回一个包含此列表中所有元素的数组；返回数组的运行时类型是指定数组的运行时类型。如果列表适合指定的数组，则在其中返回。否则，将使用指定数组的运行时类型和此列表的大小分配一个新数组。

如果列表适合指定的数组并有剩余空间（即，数组的元素多于列表），则数组中紧随列表末尾的元素设置为 null。 （仅当调用者知道列表不包含任何空元素时，这对确定列表的长度很有用。）

与 toArray() 方法一样，此方法充当基于数组的 API 和基于集合的 API 之间的桥梁。此外，此方法允许对输出数组的运行时类型进行精确控制，并且在某些情况下可用于节省分配成本。

假设 x 是一个已知仅包含字符串的列表。以下代码可用于将列表转储到新分配的 String 数组中：

     String[] y = x.toArray(new String[0]); 

请注意，toArray(new Object[0]) 在功能上与 toArray() 相同。

指定者：

接口 CollectionE 中的 toArray

类型参数：

类型参数名称	类型参数描述
T	包含集合的数组的运行时类型

参数:

参数名称	参数描述
a	这个列表的元素要存储到的数组，如果它足够大的话； 否则，将为此目的分配相同运行时类型的新数组。

返回:

包含此列表元素的数组

Throws:

Throw名称	Throw描述
ArrayStoreException	如果指定数组的运行时类型不是此列表中每个元素的运行时类型的超类型
NullPointerException	如果指定的数组为空

add

boolean add(E e)

将指定元素附加到此列表的末尾（可选操作）。

支持此操作的列表可能会限制可以添加到此列表的元素。 特别是，一些列表会拒绝添加空元素，而另一些列表则会对可能添加的元素类型施加限制。 列表类应在其文档中明确指定对可以添加哪些元素的任何限制。

指定者：

添加接口CollectionE

参数:

参数名称	参数描述
e	要附加到此列表的元素

返回:

true（由 Collection#add 指定）

Throws:

Throw名称	Throw描述
UnsupportedOperationException	如果此列表不支持添加操作
ClassCastException	如果指定元素的类阻止它被添加到这个列表中
NullPointerException	如果指定元素为空且此列表不允许空元素
IllegalArgumentException	如果此元素的某些属性阻止它被添加到此列表中

remove

boolean remove(Object o)

如果指定元素存在，则从该列表中删除第一次出现的指定元素（可选操作）。 如果此列表不包含该元素，则它不变。 更正式地说，删除具有最低索引 i 的元素，使得 (o==null ? get(i)==null : o.equals(get(i))) （如果存在这样的元素）。 如果此列表包含指定的元素（或等效地，如果此列表因调用而更改），则返回 true。

指定者：

在接口 CollectionE 中删除

参数：

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

返回:

如果此列表包含指定元素，则为 true

Throws:

Throw名称	Throw描述
ClassCastException	如果指定元素的类型与此列表不兼容（可选）
NullPointerException	如果指定元素为空且此列表不允许空元素（可选）
UnsupportedOperationException	如果此列表不支持删除操作

containsAll

boolean containsAll(Collection<?> c)

如果此列表包含指定集合的所有元素，则返回 true。

指定者：

接口 CollectionE 中的 containsAll

参数：

参数名称	参数描述
c	要检查此列表中包含的集合

返回:

如果此列表包含指定集合的所有元素，则为 true

Throws:

Throw名称	Throw描述
ClassCastException	如果指定集合中的一个或多个元素的类型与此列表不兼容（可选）
NullPointerException	如果指定的集合包含一个或多个空元素并且此列表不允许空元素（可选），或者指定的集合为空

addAll

boolean addAll(Collection<? extends E> c)

将指定集合中的所有元素附加到此列表的末尾，按照指定集合的迭代器返回的顺序（可选操作）。 如果在操作正在进行时修改了指定的集合，则此操作的行为是未定义的。 （请注意，如果指定的集合是这个列表，并且它是非空的，则会发生这种情况。）

指定者：

接口 CollectionE 中的 addAll

参数：

参数名称	参数描述
c	包含要添加到此列表的元素的集合

返回:

如果此列表因调用而更改，则为 true

Throws:

Throw名称	Throw描述
UnsupportedOperationException	如果此列表不支持 addAll 操作
ClassCastException	如果指定集合的元素的类阻止它被添加到此列表中
NullPointerException	如果指定的集合包含一个或多个空元素并且此列表不允许空元素，或者指定的集合为空
IllegalArgumentException	如果指定集合的某个元素的某些属性阻止它被添加到此列表中

addAll

boolean addAll(int index, Collection<? extends E> c)

将指定集合中的所有元素插入到此列表中的指定位置（可选操作）。 将当前位于该位置的元素（如果有）和任何后续元素向右移动（增加它们的索引）。 新元素将按照指定集合的迭代器返回的顺序出现在此列表中。 如果在操作正在进行时修改了指定的集合，则此操作的行为是未定义的。 （请注意，如果指定的集合是这个列表，并且它是非空的，则会发生这种情况。）

参数：

参数名称	参数描述
index	插入指定集合中第一个元素的索引
c	包含要添加到此列表的元素的集合

返回:

如果此列表因调用而更改，则为 true

Throws:

Throw名称	Throw描述
UnsupportedOperationException	如果此列表不支持 addAll 操作
ClassCastException	如果指定集合的元素的类阻止它被添加到此列表中
NullPointerException	如果指定的集合包含一个或多个空元素并且此列表不允许空元素，或者指定的集合为空
IllegalArgumentException	如果指定集合的某个元素的某些属性阻止它被添加到此列表中
IndexOutOfBoundsException	如果索引超出范围 (index < 0 || index > size())

removeAll

boolean removeAll(Collection<?> c)

从此列表中删除包含在指定集合中的所有元素（可选操作）。

指定者：

接口 CollectionE 中的 removeAll

参数：

参数名称	参数描述
c	包含要从此列表中删除的元素的集合

返回:

如果此列表因调用而更改，则为 true

Throws:

Throw名称	Throw描述
UnsupportedOperationException	如果此列表不支持 removeAll 操作
ClassCastException	如果此列表的某个元素的类与指定的集合不兼容（可选）
NullPointerException	如果此列表包含空元素并且指定的集合不允许空元素（可选），或者指定的集合为空

retainAll

boolean retainAll(Collection<?> c)

仅保留此列表中包含在指定集合中的元素（可选操作）。 换句话说，从这个列表中删除所有不包含在指定集合中的元素。

指定者：

接口CollectionE中的retainAll

参数：

参数名称	参数描述
c	包含要保留在此列表中的元素的集合

返回:

如果此列表因调用而更改，则为 true

Throws:

Throw名称	Throw描述
UnsupportedOperationException	如果此列表不支持 retainAll 操作
ClassCastException	如果此列表的某个元素的类与指定的集合不兼容（可选）
NullPointerException	如果此列表包含空元素并且指定的集合不允许空元素（可选），或者指定的集合为空

replaceAll

default void replaceAll(UnaryOperatorE operator)

将此列表的每个元素替换为将运算符应用于该元素的结果。 操作员抛出的错误或运行时异常被转发给调用者。

参数：

参数名称	参数描述
operator	应用于每个元素的运算符

Throws:

Throw名称	Throw描述
UnsupportedOperationException	如果此列表不可修改。 如果无法替换元素或通常不支持修改，则实现可能会抛出此异常
NullPointerException	如果指定的运算符为空或运算符结果为空值且此列表不允许空元素（可选）

sort

default void sort(Comparator<? super E> c)

根据指定 Comparator 产生的顺序对该列表进行排序。

此列表中的所有元素必须使用指定的比较器进行相互比较（即 c.compare(e1, e2) 不得为列表中的任何元素 e1 和 e2 抛出 ClassCastException）。

如果指定的比较器为空，则此列表中的所有元素都必须实现 Comparable 接口，并且应使用元素的 Comparable。

此列表必须是可修改的，但不需要调整大小。

参数：

参数名称	参数描述
c	Comparator 用于比较列表元素。 空值表示应该使用元素的 Comparable

Throws:

Throw名称	Throw描述
ClassCastException	如果列表包含使用指定比较器不能相互比较的元素
UnsupportedOperationException	如果列表的列表迭代器不支持设置操作
IllegalArgumentException	（可选）如果发现比较器违反了比较器合同

clear

void clear()

从此列表中删除所有元素（可选操作）。 此调用返回后，列表将为空。

指定者：

在界面 CollectionE 中清除

Throws:

Throw名称	Throw描述
UnsupportedOperationException	如果此列表不支持清除操作

equals

boolean equals(Object o)

比较指定对象与此列表是否相等。 当且仅当指定对象也是一个列表时返回 true，两个列表具有相同的大小，并且两个列表中所有对应的元素对都相等。 （如果 (e1==null ? e2==null : e1.equals(e2)) 两个元素 e1 和 e2 相等。）换句话说，如果两个列表以相同的顺序包含相同的元素，则它们被定义为相等 . 此定义确保 equals 方法在 List 接口的不同实现中正常工作。

指定者：

接口 CollectionE 中的等于

覆盖：

类 Object 中的等于

参数：

参数名称	参数描述
o	要与此列表比较是否相等的对象

返回:

如果指定的对象等于此列表，则为 true

hashCode

int hashCode()

返回此列表的哈希码值。 列表的哈希码定义为以下计算的结果：

     int hashCode = 1;
     for (E e : list)
         hashCode = 31*hashCode + (e==null ? 0 : e.hashCode());

 

这确保 list1.equals(list2) 意味着 list1.hashCode()==list2.hashCode() 对于任何两个列表 list1 和 list2，这是 Object#hashCode 的一般合同所要求的。

指定者：

接口 CollectionE 中的 hashCode

覆盖：

类 Object 中的 hashCode

返回:

此列表的哈希码值

get

E get(int index)

返回此列表中指定位置的元素。

参数：

参数名称	参数描述
index	要返回的元素的索引

返回:

此列表中指定位置的元素

Throws:

Throw名称	Throw描述
IndexOutOfBoundsException	如果索引超出范围 (index < 0 || index >= size())

set

E set(int index, E element)

将此列表中指定位置的元素替换为指定元素（可选操作）。

参数：

参数名称	参数描述
index	要替换的元素的索引
element	要存储在指定位置的元素

返回:

先前在指定位置的元素

Throws:

Throw名称	Throw描述
UnsupportedOperationException	如果此列表不支持设置操作
ClassCastException	如果指定元素的类阻止它被添加到这个列表中
NullPointerException	如果指定元素为空且此列表不允许空元素
IllegalArgumentException	如果指定元素的某些属性阻止它被添加到此列表中
IndexOutOfBoundsException	如果索引超出范围 (index < 0 || index >= size())

add

void add(int index, E element)

在此列表中的指定位置插入指定元素（可选操作）。 将当前位于该位置的元素（如果有）和任何后续元素向右移动（将其索引加一）。

参数：

参数名称	参数描述
index	要插入指定元素的索引
element	要插入的元素

Throws:

Throw名称	Throw描述
UnsupportedOperationException	如果此列表不支持添加操作
ClassCastException	如果指定元素的类阻止它被添加到这个列表中
NullPointerException	如果指定元素为空且此列表不允许空元素
IllegalArgumentException	如果指定元素的某些属性阻止它被添加到此列表中
IndexOutOfBoundsException	如果索引超出范围 (index < 0 || index > size())

remove

E remove(int index)

移除此列表中指定位置的元素（可选操作）。 将任何后续元素向左移动（从它们的索引中减去 1）。 返回从列表中删除的元素。

参数：

参数名称	参数描述
index	要删除的元素的索引

返回:

先前在指定位置的元素

Throws:

Throw名称	Throw描述
UnsupportedOperationException	如果此列表不支持删除操作
IndexOutOfBoundsException	如果索引超出范围 (index < 0 || index >= size())

indexOf

int indexOf(Object o)

返回此列表中指定元素第一次出现的索引，如果此列表不包含该元素，则返回 -1。 更正式地说，返回满足 (o==null ? get(i)==null : o.equals(get(i))) 的最低索引 i，如果没有这样的索引，则返回 -1。

参数：

参数名称	参数描述
o	要搜索的元素

返回:

此列表中指定元素第一次出现的索引，如果此列表不包含该元素，则为 -1

Throws:

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

lastIndexOf

int lastIndexOf(Object o)

返回此列表中指定元素最后一次出现的索引，如果此列表不包含该元素，则返回 -1。 更正式地说，返回满足 (o==null ? get(i)==null : o.equals(get(i))) 的最高索引 i，如果没有这样的索引，则返回 -1。

参数：

参数名称	参数描述
o	要搜索的元素

返回:

此列表中指定元素最后一次出现的索引，如果此列表不包含该元素，则为 -1

Throws:

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

listIterator

ListIteratorE listIterator()

返回此列表中元素的列表迭代器（以正确的顺序）。

返回:

此列表中元素的列表迭代器（按正确顺序）

listIterator

ListIteratorE listIterator(int index)

返回此列表中元素的列表迭代器（以正确的顺序），从列表中的指定位置开始。 指定的索引指示初始调用 ListIterator#next 将返回的第一个元素。 对 ListIterator#previous 的初始调用将返回具有指定索引减一的元素。

参数：

参数名称	参数描述
index	要从列表迭代器返回的第一个元素的索引（通过调用 ListIterator#next）

返回:

此列表中元素的列表迭代器（按正确顺序），从列表中的指定位置开始

Throws:

Throw名称	Throw描述
IndexOutOfBoundsException	如果索引超出范围 (index < 0 || index > size())

subList

ListE subList(int fromIndex, int toIndex)

返回此列表在指定的 fromIndex（包括）和 toIndex（不包括）之间的部分的视图。 （如果 fromIndex 和 toIndex 相等，则返回列表为空。）返回列表由此列表支持，因此返回列表中的非结构性更改会反映在此列表中，反之亦然。 返回的列表支持此列表支持的所有可选列表操作。

这种方法消除了显式范围操作的需要（通常存在于数组中的那种）。 通过传递 subList 视图而不是整个列表，任何需要列表的操作都可以用作范围操作。 例如，以下习惯用法从列表中删除一系列元素：

      list.subList(from, to).clear(); 

可以为 indexOf 和 lastIndexOf 构造类似的习语，并且 Collections 类中的所有算法都可以应用于子列表。

如果后备列表（即此列表）以除通过返回列表之外的任何方式进行结构修改，则此方法返回的列表的语义将变为未定义。 （结构修改是改变这个列表的大小，或者以其他方式扰乱它，使得正在进行的迭代可能会产生不正确的结果。）

参数：

参数名称	参数描述
fromIndex	subList 的低端点（包括）
toIndex	subList 的高端（不包括）

返回:

此列表中指定范围的视图

Throws:

Throw名称	Throw描述
IndexOutOfBoundsException	对于非法端点索引值（fromIndex < 0 || toIndex > size || fromIndex > toIndex）

spliterator

default SpliteratorE spliterator()

在此列表中的元素上创建一个 Spliterator。

Spliterator 报告 Spliterator#SIZED 和 Spliterator#ORDERED。 实施应记录附加特征值的报告。

指定者：

接口 CollectionE 中的分离器

指定者：

接口 IterableE 中的分离器

返回:

此列表中元素的拆分器