Module java.base

Package java.util

Interface List<E>

类型参数:

E - 此列表中元素的类型

所有超接口:

Collection<E>, Iterable<E>, SequencedCollection<E>

所有已知实现类:

AbstractList, AbstractSequentialList, ArrayList, AttributeList, CopyOnWriteArrayList, LinkedList, RoleList, RoleUnresolvedList, Stack, Vector

       public interface List<E> extends SequencedCollection<E>
      

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

与集合不同，列表通常允许重复元素。更正式地说，列表通常允许成对的元素 e1 和 e2，使得 e1.equals(e2)，它们通常允许多个空元素（如果它们允许空元素）。有人可能希望实现一个禁止重复的列表，当用户尝试插入它们时抛出运行时异常，但我们预计这种用法很少见。

List 接口对 iterator、add、remove、equals 和 hashCode 方法的契约提供了额外的规定，超出了 Collection 接口中指定的规定。其他继承方法的声明也包括在这里以方便起见。

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

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

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

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

注意: 虽然列表允许包含自身作为元素，但极度谨慎是明智的：在这种列表上，equals 和 hashCode 方法不再定义良好。

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

不可修改的列表

List.of 和 List.copyOf 静态工厂方法提供了一种方便的方式来创建不可修改的列表。这些方法创建的 List 实例具有以下特征:

• 它们是 不可修改的。元素不能被添加、移除或替换。在列表上调用任何修改器方法将始终导致抛出 UnsupportedOperationException。但是，如果包含的元素本身是可变的，则这可能导致列表的内容似乎发生更改。
• 它们不允许 null 元素。尝试使用 null 元素创建它们将导致 NullPointerException。
• 如果所有元素都是可序列化的，则它们是可序列化的。
• 列表中元素的顺序与提供的参数的顺序或提供的数组中元素的顺序相同。
• 列表及其 subList 视图实现了 RandomAccess 接口。
• 它们是 基于值 的。程序员应将相等的实例视为可互换的，并且不应将它们用于同步，否则可能会发生不可预测的行为。例如，在将来的版本中，同步可能会失败。调用者不应对返回的实例的身份做任何假设。工厂可以自由创建新实例或重用现有实例。
• 它们按照 序列化形式 页面上指定的方式进行序列化。

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

自 JDK 版本:

1.2

参见:

• Collection
• Set
• ArrayList
• LinkedList
• Vector
• Arrays.asList(Object[])
• Collections.nCopies(int, Object)
• Collections.EMPTY_LIST
• AbstractList
• AbstractSequentialList

Method Summary

Modifier and Type	Method	Description
void	add(int index, E element)	在列表中的指定位置插入指定的元素（可选操作）。
boolean	add(E e)	将指定的元素追加到此列表的末尾（可选操作）。
boolean	addAll(int index, Collection<? extends E> c)	将指定集合中的所有元素插入到列表的指定位置（可选操作）。
boolean	addAll(Collection<? extends E> c)	将指定集合中的所有元素追加到列表的末尾，顺序与指定集合的迭代器返回的顺序相同（可选操作）。
default void	addFirst(E e)	将一个元素作为此集合的第一个元素添加（可选操作）。
default void	addLast(E e)	将一个元素作为此集合的最后一个元素添加（可选操作）。
void	clear()	从列表中移除所有元素（可选操作）。
boolean	contains(Object o)	如果此列表包含指定的元素，则返回 true。
boolean	containsAll(Collection<?> c)	如果此列表包含指定集合的所有元素，则返回 true。
static <E> List<E>	copyOf(Collection<? extends E> coll)	返回包含给定集合的元素的 不可修改的列表，其迭代顺序与给定集合中的顺序相同。
boolean	equals(Object o)	将指定对象与此列表进行比较以检查相等性。
E	get(int index)	返回列表中指定位置的元素。
default E	getFirst()	获取此集合的第一个元素。
default E	getLast()	获取此集合的最后一个元素。
int	hashCode()	返回此列表的哈希码值。
int	indexOf(Object o)	返回此列表中指定元素的第一次出现的索引，如果此列表不包含该元素，则返回 -1。
boolean	isEmpty()	如果此列表不包含任何元素，则返回 true。
Iterator<E>	iterator()	返回此列表中元素的迭代器，按正确顺序。
int	lastIndexOf(Object o)	返回此列表中指定元素的最后一次出现的索引，如果此列表不包含该元素，则返回 -1。
ListIterator<E>	listIterator()	返回此列表中元素的列表迭代器（按正确顺序）。
ListIterator<E>	listIterator(int index)	返回从列表中指定位置开始的元素的列表迭代器（按正确顺序）。
static <E> List<E>	of()	返回一个包含零个元素的不可修改列表。
static <E> List<E>	of(E e1)	返回一个包含一个元素的不可修改列表。
static <E> List<E>	of(E... elements)	返回一个包含任意数量元素的不可修改列表。
static <E> List<E>	of(E e1, E e2)	返回一个包含两个元素的不可修改列表。
static <E> List<E>	of(E e1, E e2, E e3)	返回一个包含三个元素的不可修改列表。
static <E> List<E>	of(E e1, E e2, E e3, E e4)	返回一个包含四个元素的不可修改列表。
static <E> List<E>	of(E e1, E e2, E e3, E e4, E e5)	返回一个包含五个元素的不可修改列表。
static <E> List<E>	of(E e1, E e2, E e3, E e4, E e5, E e6)	返回一个包含六个元素的不可修改列表。
static <E> List<E>	of(E e1, E e2, E e3, E e4, E e5, E e6, E e7)	返回一个包含七个元素的不可修改列表。
static <E> List<E>	of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8)	返回一个包含八个元素的不可修改列表。
static <E> List<E>	of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9)	返回一个包含九个元素的不可修改列表。
static <E> List<E>	of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10)	返回一个包含十个元素的不可修改列表。
E	remove(int index)	移除列表中指定位置的元素（可选操作）。
boolean	remove(Object o)	从列表中移除指定元素的第一次出现（如果存在）（可选操作）。
boolean	removeAll(Collection<?> c)	从列表中删除包含在指定集合中的所有元素（可选操作）。
default E	removeFirst()	删除并返回此集合的第一个元素（可选操作）。
default E	removeLast()	删除并返回此集合的最后一个元素（可选操作）。
default void	replaceAll(UnaryOperator<E> operator)	用将运算符应用于该元素的结果替换此列表的每个元素。
boolean	retainAll(Collection<?> c)	仅保留此列表中包含在指定集合中的元素（可选操作）。
default List<E>	reversed()	返回此集合的逆序视图。
E	set(int index, E element)	用指定元素替换此列表中指定位置的元素（可选操作）。
int	size()	返回此列表中的元素数。
default void	sort(Comparator<? super E> c)	根据指定的Comparator引起的顺序对此列表进行排序。
default Spliterator<E>	spliterator()	在此列表中的元素上创建一个Spliterator。
List<E>	subList(int fromIndex, int toIndex)	返回此列表中从指定fromIndex（包括）到toIndex（不包括）的部分的视图。
Object[]	toArray()	返回一个包含此列表中所有元素的数组，按正确顺序排列（从第一个到最后一个元素）。
<T> T[]	toArray(T[] a)	返回一个包含此列表中所有元素的数组，按正确顺序排列（从第一个到最后一个元素）；返回的数组的运行时类型与指定数组的类型相同。

Methods declared in interface java.util.Collection

parallelStream, removeIf, stream, toArray

Methods declared in interface java.lang.Iterable

forEach

Method Details

size

             int size()
            

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

指定者：

size 在接口 Collection<E>

返回：

此列表中的元素数

isEmpty

             boolean isEmpty()
            

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

指定者：

isEmpty 在接口 Collection<E>

返回：

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

contains

             boolean contains(Object o)
            

如果此列表包含指定的元素，则返回true。更正式地说，如果且仅当此列表包含至少一个元素e，使得Objects.equals(o, e)时返回true。

指定者：

contains 在接口 Collection<E>

参数：

o - 要测试其是否存在于此列表中的元素

返回：

如果此列表包含指定的元素，则返回true

抛出：

ClassCastException - 如果指定元素的类型与此列表不兼容（可选）

NullPointerException - 如果指定元素为null且此列表不允许null元素（可选）

iterator

             Iterator<E> iterator()
            

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

指定者：

iterator 在接口 Collection<E>

指定者：

iterator 在接口 Iterable<E>

返回：

一个按正确顺序排列的此列表中元素的迭代器

toArray

             Object[] toArray()
            

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

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

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

指定者：

toArray 在接口 Collection<E>

返回：

一个包含此列表中所有元素的数组，按正确顺序排列

参见：

• Arrays.asList(Object[])

toArray

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

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

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

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

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

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

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

指定者：

toArray 在接口 Collection<E>

类型参数：

T - 包含集合的数组的组件类型

参数：

a - 要存储此列表的元素的数组，如果足够大；否则，将为此目的分配相同运行时类型的新数组。

返回：

包含此列表的元素的数组

抛出：

ArrayStoreException - 如果指定数组的运行时类型不是此列表中每个元素的运行时类型的超类型

NullPointerException - 如果指定数组为null

add

             boolean add(E e)
            

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

支持此操作的列表可能会对可以添加到此列表的元素施加限制。特别是，某些列表将拒绝添加null元素，而其他列表将对可以添加的元素类型施加限制。列表类应在其文档中清楚指定可以添加哪些元素的任何限制。

指定者：

add 在接口 Collection<E>

参数：

e - 要追加到此列表的元素

返回：

true（如Collection.add(E)所指定）

抛出：

UnsupportedOperationException - 如果此列表不支持add操作

ClassCastException - 如果指定元素的类阻止将其添加到此列表

NullPointerException - 如果指定元素为null且此列表不允许null元素

IllegalArgumentException - 如果此元素的某些属性阻止将其添加到此列表

remove

             boolean remove(Object o)
            

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

指定由：

remove 在接口 Collection<E>中

参数：

o - 如果存在，则从此列表中删除的元素

返回：

true 如果此列表包含指定的元素

抛出：

ClassCastException - 如果指定元素的类型与此列表不兼容（可选）

NullPointerException - 如果指定元素为null且此列表不允许null元素（可选）

UnsupportedOperationException - 如果此列表不支持remove操作

containsAll

             boolean containsAll(Collection<?> c)
            

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

指定由：

containsAll 在接口 Collection<E>中

参数：

c - 要在此列表中检查包含性的集合

返回：

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

抛出：

ClassCastException - 如果指定集合中一个或多个元素的类型与此列表不兼容（可选）

NullPointerException - 如果指定集合包含一个或多个null元素且此列表不允许null元素（可选），或者指定集合为null

参见：

• contains(Object)

addAll

             boolean addAll(Collection<? extends E> c)
            

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

指定由：

addAll 在接口 Collection<E>中

参数：

c - 包含要添加到此列表中的元素的集合

返回：

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

抛出：

UnsupportedOperationException - 如果此列表不支持addAll操作

ClassCastException - 如果指定集合的元素的类阻止将其添加到此列表中

NullPointerException - 如果指定集合包含一个或多个null元素且此列表不允许null元素，或者指定集合为null

IllegalArgumentException - 如果指定集合的元素的某些属性阻止将其添加到此列表中

参见：

• add(Object)

addAll

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

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

参数：

index - 要插入指定集合中第一个元素的索引

c - 包含要添加到此列表中的元素的集合

返回：

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

抛出：

UnsupportedOperationException - 如果此列表不支持addAll操作

ClassCastException - 如果指定集合的元素的类阻止将其添加到此列表中

NullPointerException - 如果指定集合包含一个或多个null元素且此列表不允许null元素，或者指定集合为null

IllegalArgumentException - 如果指定集合的元素的某些属性阻止将其添加到此列表中

IndexOutOfBoundsException - 如果索引超出范围（index < 0 || index > size()）

removeAll

             boolean removeAll(Collection<?> c)
            

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

指定由：

removeAll 在接口 Collection<E>中

参数：

c - 包含要从此列表中删除的元素的集合

返回：

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

抛出：

UnsupportedOperationException - 如果此列表不支持removeAll操作

ClassCastException - 如果此列表的一个元素的类与指定集合不兼容（可选）

NullPointerException - 如果此列表包含一个null元素且指定集合不允许null元素（可选），或者指定集合为null

参见：

• remove(Object)
• contains(Object)

retainAll

             boolean retainAll(Collection<?> c)
            

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

指定由：

retainAll 在接口 Collection<E>中

参数：

c - 包含要在此列表中保留的元素的集合

返回：

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

抛出：

UnsupportedOperationException - 如果此列表不支持retainAll操作

ClassCastException - 如果此列表的一个元素的类与指定集合不兼容（可选）

NullPointerException - 如果此列表包含一个null元素且指定集合不允许null元素（可选），或者指定集合为null

参见：

• remove(Object)
• contains(Object)

replaceAll

             default void replaceAll(UnaryOperator<E> operator)
            

将此列表的每个元素替换为将运算符应用于该元素的结果。运算符引发的错误或运行时异常将传递给调用者。

实现要求:

默认实现等同于，对于这个list：

     final ListIterator<E> li = list.listIterator();
     while (li.hasNext()) {
         li.set(operator.apply(li.next()));
     }
 

如果列表的列表迭代器不支持set操作，则在替换第一个元素时将抛出UnsupportedOperationException。

参数:

operator - 要应用于每个元素的操作符

抛出:

UnsupportedOperationException - 如果此列表是不可修改的。如果一个元素无法被替换，或者一般情况下不支持修改，实现可能会抛出此异常

NullPointerException - 如果指定的操作符为null，或者操作符的结果为null值，且此列表不允许null元素（可选）

自1.8版本起:

1.8

sort

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

根据指定的Comparator引起的顺序对此列表进行排序。排序是稳定的：此方法不得重新排序相等的元素。

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

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

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

实现要求:

默认实现获取包含此列表中所有元素的数组，对数组进行排序，并遍历此列表，将每个元素从数组中相应位置重置。（这避免了尝试原地对链表进行排序导致的n² log(n)性能问题。）

实现说明:

此实现是一个稳定的、自适应的、迭代的归并排序，当输入数组部分排序时，比n lg(n)少得多的比较次数，同时在输入数组随机排序时提供传统归并排序的性能。如果输入数组几乎排序完成，实现需要大约n次比较。临时存储需求从几乎排序的输入数组的小常数变化到随机排序的输入数组的n/2个对象引用。

该实现充分利用了输入数组中的升序和降序顺序，并且可以利用输入数组中不同部分的升序和降序顺序。它非常适合合并两个或多个排序数组：只需连接数组并对结果数组进行排序即可。

该实现是从Tim Peters的Python列表排序（ TimSort）中改编的。它使用了Peter McIlroy的“乐观排序和信息论复杂性”中的技术，发表于1993年1月第四届ACM-SIAM离散算法年会论文集，第467-474页。

参数:

c - 用于比较列表元素的Comparator。一个null值表示应使用元素的自然顺序

抛出:

ClassCastException - 如果列表包含使用指定比较器不相互比较的元素

UnsupportedOperationException - 如果列表的列表迭代器不支持set操作

IllegalArgumentException - （可选）如果发现比较器违反了Comparator合同

自1.8版本起:

1.8

clear

             void clear()
            

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

指定者:

clear 在接口 Collection<E>中

抛出:

UnsupportedOperationException - 如果此列表不支持clear操作

equals

             boolean equals(Object o)
            

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

指定者:

equals 在接口 Collection<E>中

覆盖:

equals 在类 Object中

参数:

o - 用于与此列表比较相等性的对象

返回:

如果指定对象等于此列表，则返回true

参见:

• Object.hashCode()
• HashMap

hashCode

             int hashCode()
            

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

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

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

指定者:

hashCode 在接口 Collection<E>中

覆盖:

hashCode 在类 Object中

返回:

此列表的哈希码值

参见:

• Object.equals(Object)
• equals(Object)

get

             E get(int index)
            

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

参数:

index - 要返回的元素的索引

返回:

此列表中指定位置的元素

抛出:

IndexOutOfBoundsException - 如果索引超出范围（index < 0 || index >= size()）

set

             E set(int index, E element)
            

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

参数:

index - 要替换的元素的索引

element - 要存储在指定位置的元素

返回:

先前在指定位置的元素

抛出:

UnsupportedOperationException - 如果此列表不支持set操作

ClassCastException - 如果指定元素的类阻止将其添加到此列表

NullPointerException - 如果指定元素为null且此列表不允许null元素

IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此列表

IndexOutOfBoundsException - 如果索引超出范围（index < 0 || index >= size()）

add

             void add(int index, E element)
            

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

参数:

index - 要插入指定元素的索引

element - 要插入的元素

抛出:

UnsupportedOperationException - 如果此列表不支持add操作

ClassCastException - 如果指定元素的类别阻止将其添加到此列表中

NullPointerException - 如果指定元素为null且此列表不允许null元素

IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此列表中

IndexOutOfBoundsException - 如果索引超出范围（index < 0 || index > size()）

remove

             E remove(int index)
            

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

参数:

index - 要移除的元素的索引

返回:

先前位于指定位置的元素

抛出:

UnsupportedOperationException - 如果此列表不支持remove操作

IndexOutOfBoundsException - 如果索引超出范围（index < 0 || index >= size()）

indexOf

             int indexOf(Object o)
            

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

参数:

o - 要搜索的元素

返回:

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

抛出:

ClassCastException - 如果指定元素的类型与此列表不兼容（可选）

NullPointerException - 如果指定元素为null且此列表不允许null元素（可选）

lastIndexOf

             int lastIndexOf(Object o)
            

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

参数:

o - 要搜索的元素

返回:

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

抛出:

ClassCastException - 如果指定元素的类型与此列表不兼容（可选）

NullPointerException - 如果指定元素为null且此列表不允许null元素（可选）

listIterator

             ListIterator<E> listIterator()
            

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

返回:

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

listIterator

             ListIterator<E> listIterator(int index)
            

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

参数:

index - 列表迭代器从中返回第一个元素的索引（通过调用next）

返回:

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

抛出:

IndexOutOfBoundsException - 如果索引超出范围（index < 0 || index > size()）

subList

             List<E> subList(int fromIndex, int toIndex)
            

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

此方法消除了对显式范围操作的需求（通常存在于数组中）。可以通过传递子列表视图而不是整个列表来将期望列表的任何操作用作范围操作。例如，以下习语从列表中删除一系列元素：

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

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

如果通过此方法返回的列表在任何方式上（即通过返回的列表以外的方式）对支持列表（即此列表）进行结构修改，则此方法返回的列表的语义将变得不确定。 （结构修改是那些改变此列表大小或以某种方式扰乱它的操作，以便正在进行的迭代可能产生不正确的结果。）

参数:

fromIndex - 子列表的低端点（包括）

toIndex - 子列表的高端点（不包括）

返回:

此列表中指定范围的视图

抛出:

IndexOutOfBoundsException - 对于非法的端点索引值（fromIndex < 0 || toIndex > size || fromIndex > toIndex）

spliterator

             default Spliterator<E> spliterator()
            

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

Spliterator报告Spliterator.SIZED和Spliterator.ORDERED。实现应记录其他特征值的报告。

指定者:

spliterator 在接口 Collection<E>

指定者:

spliterator 在接口 Iterable<E>

实现要求:

默认实现创建一个延迟绑定的Spliterator如下：

• 如果列表是RandomAccess的实例，则默认实现将创建一个通过调用方法get(int)遍历元素的Spliterator。如果这样的调用导致或将导致IndexOutOfBoundsException，则Spliterator将快速失败并抛出ConcurrentModificationException。如果列表还是AbstractList的实例，则Spliterator将使用列表的modCount字段提供额外的快速失败行为。
• 否则，默认实现将从列表的Iterator创建一个Spliterator。Spliterator继承列表的迭代器的快速失败。

实现说明:

创建的Spliterator另外报告Spliterator.SUBSIZED。

返回:

此列表中元素的Spliterator

自1.8起

1.8

addFirst

             default void addFirst(E e)
            

将一个元素作为此集合的第一个元素添加（可选操作）。此操作正常完成后，给定元素将成为此集合的成员，并且它将是遇到顺序中的第一个元素。

指定者:

addFirst 在接口 SequencedCollection<E>

实现要求:

此接口中的实现调用add(0, e)。

参数:

e - 要添加的元素

抛出:

NullPointerException - 如果指定元素为null且此集合不允许null元素

UnsupportedOperationException - 如果此集合实现不支持此操作

自21起

21

addLast

             default void addLast(E e)
            

将一个元素作为此集合的最后一个元素添加（可选操作）。此操作正常完成后，给定元素将成为此集合的成员，并且它将是遇到顺序中的最后一个元素。

指定由：

addLast 在接口 SequencedCollection<E>中

实现要求：

此接口中的实现调用add(e)。

参数：

e - 要添加的元素。

抛出：

NullPointerException - 如果指定的元素为null且此集合不允许null元素

UnsupportedOperationException - 如果此集合实现不支持此操作

自：

21

getFirst

             default E getFirst()
            

获取此集合的第一个元素。

指定由：

getFirst 在接口 SequencedCollection<E>中

实现要求：

如果此列表不为空，则此接口中的实现返回调用get(0)的结果。否则，它会抛出NoSuchElementException。

返回：

检索到的元素

抛出：

NoSuchElementException - 如果此集合为空

自：

21

getLast

             default E getLast()
            

获取此集合的最后一个元素。

指定由：

getLast 在接口 SequencedCollection<E>中

实现要求：

如果此列表不为空，则此接口中的实现返回调用get(size() - 1)的结果。否则，它会抛出NoSuchElementException。

返回：

检索到的元素

抛出：

NoSuchElementException - 如果此集合为空

自：

21

removeFirst

             default E removeFirst()
            

移除并返回此集合的第一个元素（可选操作）。

指定由：

removeFirst 在接口 SequencedCollection<E>中

实现要求：

如果此列表不为空，则此接口中的实现返回调用remove(0)的结果。否则，它会抛出NoSuchElementException。

返回：

移除的元素

抛出：

NoSuchElementException - 如果此集合为空

UnsupportedOperationException - 如果此集合实现不支持此操作

自：

21

removeLast

             default E removeLast()
            

移除并返回此集合的最后一个元素（可选操作）。

指定由：

removeLast 在接口 SequencedCollection<E>中

实现要求：

如果此列表不为空，则此接口中的实现返回调用remove(size() - 1)的结果。否则，它会抛出NoSuchElementException。

返回：

移除的元素

抛出：

NoSuchElementException - 如果此集合为空

UnsupportedOperationException - 如果此集合实现不支持此操作

自：

21

reversed

             default List<E> reversed()
            

返回此集合的逆序视图。返回视图中元素的遭遇顺序与此集合中元素的遭遇顺序相反。逆序排序会影响所有对顺序敏感的操作，包括对返回视图的视图集合的操作。如果集合实现允许修改此视图，则对视图的修改会“写入”到基础集合。对基础集合的更改可能会或可能不会在此逆序视图中可见，这取决于实现。

指定由：

reversed 在接口 SequencedCollection<E>中

实现要求：

此接口中的实现返回一个逆序的列表视图。视图的reversed()方法返回对此列表的引用。视图上的其他操作通过调用此列表上的公共方法实现。调用视图上的操作与调用此列表上的操作之间的确切关系未指定。但是，通常对顺序敏感的操作会委托给具有相反方向的适当方法。例如，在视图上调用getFirst会导致在此列表上调用getLast。

返回：

此集合的逆序视图，作为一个List

自：

21

of

             static <E> List<E> of()
            

返回包含零个元素的不可修改列表。有关详细信息，请参见不可修改列表。

类型参数：

E - List的元素类型

返回：

一个空的List

自：

9

of

             static <E> List<E> of(E e1)
            

返回包含一个元素的不可修改列表。有关详细信息，请参见不可修改列表。

类型参数：

E - List的元素类型

参数：

e1 - 单个元素

返回：

包含指定元素的List

抛出：

NullPointerException - 如果元素为null

自：

9

of

             static <E> List<E> of(E e1, E e2)
            

返回包含两个元素的不可修改列表。有关详细信息，请参见不可修改列表。

类型参数：

E - List的元素类型

参数：

e1 - 第一个元素

e2 - 第二个元素

返回：

包含指定元素的List

抛出：

NullPointerException - 如果有元素为null

自：

9

of

             static <E> List<E> of(E e1, E e2, E e3)
            

返回包含三个元素的不可修改列表。有关详细信息，请参见不可修改列表。

类型参数：

E - List的元素类型

参数：

e1 - 第一个元素

e2 - 第二个元素

e3 - 第三个元素

返回：

包含指定元素的List

抛出：

NullPointerException - 如果有元素为null

自：

9

of

             static <E> List<E> of(E e1, E e2, E e3, E e4)
            

返回包含四个元素的不可修改列表。有关详细信息，请参见不可修改列表。

类型参数：

E - List的元素类型

参数：

e1 - 第一个元素

e2 - 第二个元素

e3 - 第三个元素

e4 - 第四个元素

返回：

包含指定元素的List

抛出：

NullPointerException - 如果有元素为null

自：

9

of

             static <E> List<E> of(E e1, E e2, E e3, E e4, E e5)
            

返回包含五个元素的不可修改列表。有关详细信息，请参见不可修改列表。

类型参数：

E - List的元素类型

参数：

e1 - 第一个元素

e2 - 第二个元素

e3 - 第三个元素

e4 - 第四个元素

e5 - 第五个元素

返回：

包含指定元素的List

抛出：

NullPointerException - 如果有元素为null

自：

9

of

             static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6)
            

返回包含六个元素的不可修改列表。有关详细信息，请参见不可修改列表。

类型参数:

E - List的元素类型

参数:

e1 - 第一个元素

e2 - 第二个元素

e3 - 第三个元素

e4 - 第四个元素

e5 - 第五个元素

e6 - 第六个元素

返回:

包含指定元素的List

抛出:

NullPointerException - 如果元素为null

自版本:

9

of

             static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7)
            

返回一个包含七个元素的不可修改列表。详情请参见不可修改列表。

类型参数:

E - List的元素类型

参数:

e1 - 第一个元素

e2 - 第二个元素

e3 - 第三个元素

e4 - 第四个元素

e5 - 第五个元素

e6 - 第六个元素

e7 - 第七个元素

返回:

包含指定元素的List

抛出:

NullPointerException - 如果元素为null

自版本:

9

of

             static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8)
            

返回一个包含八个元素的不可修改列表。详情请参见不可修改列表。

类型参数:

E - List的元素类型

参数:

e1 - 第一个元素

e2 - 第二个元素

e3 - 第三个元素

e4 - 第四个元素

e5 - 第五个元素

e6 - 第六个元素

e7 - 第七个元素

e8 - 第八个元素

返回:

包含指定元素的List

抛出:

NullPointerException - 如果元素为null

自版本:

9

of

             static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9)
            

返回一个包含九个元素的不可修改列表。详情请参见不可修改列表。

类型参数:

E - List的元素类型

参数:

e1 - 第一个元素

e2 - 第二个元素

e3 - 第三个元素

e4 - 第四个元素

e5 - 第五个元素

e6 - 第六个元素

e7 - 第七个元素

e8 - 第八个元素

e9 - 第九个元素

返回:

包含指定元素的List

抛出:

NullPointerException - 如果元素为null

自版本:

9

of

             static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10)
            

返回一个包含十个元素的不可修改列表。详情请参见不可修改列表。

类型参数:

E - List的元素类型

参数:

e1 - 第一个元素

e2 - 第二个元素

e3 - 第三个元素

e4 - 第四个元素

e5 - 第五个元素

e6 - 第六个元素

e7 - 第七个元素

e8 - 第八个元素

e9 - 第九个元素

e10 - 第十个元素

返回:

包含指定元素的List

抛出:

NullPointerException - 如果元素为null

自版本:

9

of

             @SafeVarargs static <E> List<E> of(E... elements)
            

返回一个包含任意数量元素的不可修改列表。详情请参见不可修改列表。

API注释:

此方法还接受单个数组作为参数。结果列表的元素类型将是数组的组件类型，列表的大小将等于数组的长度。要创建一个包含单个元素的数组列表，请执行以下操作：

     String[] array = ... ;
     List<String[]> list = List.<String[]>of(array);
 

这将导致调用List.of(E)方法。

类型参数:

E - List的元素类型

参数:

elements - 要包含在列表中的元素

返回:

包含指定元素的List

抛出:

NullPointerException - 如果元素为null或数组为null

自版本:

9

copyOf

             static <E> List<E> copyOf(Collection<? extends E> coll)
            

返回一个包含给定集合元素的不可修改列表，顺序与其迭代顺序相同。给定集合不得为null，并且不得包含任何null元素。如果随后修改给定集合，则返回的列表将不反映这些修改。

实现注释:

如果给定的集合是一个不可修改列表，调用copyOf通常不会创建副本。

类型参数:

E - List的元素类型

参数:

coll - 从中提取元素的Collection，必须非null

返回:

包含给定Collection元素的List

抛出:

NullPointerException - 如果coll为null，或者它包含任何null值

自版本:

10