java.util
接口 List<E>

所有超级接口：

Collection<E>, Iterable<E>

所有已知实现类：

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

public interface List<E>
extends Collection<E>

有序的 collection（也称为序列）。此接口的用户可以对列表中每个元素的插入位置进行精确地控制。用户可以根据元素的整数索引（在列表中的位置）访问元素，并搜索列表中的元素。

与 set 不同，列表通常允许重复的元素。更确切地讲，列表通常允许满足 e1.equals(e2) 的元素对 e1 和 e2，并且如果列表本身允许 null 元素的话，通常它们允许多个 null 元素。难免有人希望通过在用户尝试插入重复元素时抛出运行时异常的方法来禁止重复的列表，但我们希望这种用法越少越好。

List 接口在 iterator、add、remove、equals 和 hashCode 方法的协定上加了一些其他约定，超过了 Collection 接口中指定的约定。为方便起见，这里也包括了其他继承方法的声明。

List 接口提供了 4 种对列表元素进行定位（索引）访问方法。列表（像 Java 数组一样）是基于 0 的。注意，这些操作可能在和某些实现（例如 LinkedList 类）的索引值成比例的时间内执行。因此，如果调用者不知道实现，那么在列表元素上迭代通常优于用索引遍历列表。

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

List 接口提供了两种搜索指定对象的方法。从性能的观点来看，应该小心使用这些方法。在很多实现中，它们将执行高开销的线性搜索。

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

注意：尽管列表允许把自身作为元素包含在内，但建议要特别小心：在这样的列表上，equals 和 hashCode 方法不再是定义良好的。

某些列表实现对列表可能包含的元素有限制。例如，某些实现禁止 null 元素，而某些实现则对元素的类型有限制。试图添加不合格的元素会抛出未经检查的异常，通常是 NullPointerException 或 ClassCastException。试图查询不合格的元素是否存在可能会抛出异常，也可能简单地返回 false；某些实现会采用前一种行为，而某些则采用后者。概括地说，试图对不合格元素执行操作时，如果完成该操作后不会导致在列表中插入不合格的元素，则该操作可能抛出一个异常，也可能成功，这取决于实现的选择。此接口的规范中将这样的异常标记为“可选”。

此接口是 Java Collections Framework 的成员。

从以下版本开始：

1.2

另请参见：

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

方法摘要

boolean	add(E e) 向列表的尾部添加指定的元素（可选操作）。
void	add(int index, E element) 在列表的指定位置插入指定元素（可选操作）。
boolean	addAll(Collection<? extends E> c) 添加指定 collection 中的所有元素到此列表的结尾，顺序是指定 collection 的迭代器返回这些元素的顺序（可选操作）。
boolean	addAll(int index, Collection<? extends E> c) 将指定 collection 中的所有元素都插入到列表中的指定位置（可选操作）。
void	clear() 从列表中移除所有元素（可选操作）。
boolean	contains(Object o) 如果列表包含指定的元素，则返回 true。
boolean	containsAll(Collection<?> c) 如果列表包含指定 collection 的所有元素，则返回 true。
boolean	equals(Object o) 比较指定的对象与列表是否相等。
E	get(int index) 返回列表中指定位置的元素。
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) 返回列表中元素的列表迭代器（按适当顺序），从列表的指定位置开始。
E	remove(int index) 移除列表中指定位置的元素（可选操作）。
boolean	remove(Object o) 从此列表中移除第一次出现的指定元素（如果存在）（可选操作）。
boolean	removeAll(Collection<?> c) 从列表中移除指定 collection 中包含的其所有元素（可选操作）。
boolean	retainAll(Collection<?> c) 仅在列表中保留指定 collection 中所包含的元素（可选操作）。
E	set(int index, E element) 用指定元素替换列表中指定位置的元素（可选操作）。
int	size() 返回列表中的元素数。
List<E>	subList(int fromIndex, int toIndex) 返回列表中指定的 fromIndex（包括 ）和 toIndex（不包括）之间的部分视图。
Object[]	toArray() 返回按适当顺序包含列表中的所有元素的数组（从第一个元素到最后一个元素）。
<T> T[]	toArray(T[] a) 返回按适当顺序（从第一个元素到最后一个元素）包含列表中所有元素的数组；返回数组的运行时类型是指定数组的运行时类型。

方法详细信息

size

int size()

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

指定者：

接口 Collection<E> 中的 size

返回：

列表中的元素数

isEmpty

boolean isEmpty()

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

指定者：

接口 Collection<E> 中的 isEmpty

返回：

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

contains

boolean contains(Object o)

如果列表包含指定的元素，则返回 true。更确切地讲，当且仅当列表包含满足 (o==null ? e==null : o.equals(e)) 的元素 e 时才返回 true。

指定者：

接口 Collection<E> 中的 contains

参数：

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

返回：

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

抛出：

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

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

iterator

Iterator<E> iterator()

返回按适当顺序在列表的元素上进行迭代的迭代器。

指定者：

接口 Collection<E> 中的 iterator

指定者：

接口 Iterable<E> 中的 iterator

返回：

按适当顺序在列表的元素上进行迭代的迭代器

toArray

Object[] toArray()

返回按适当顺序包含列表中的所有元素的数组（从第一个元素到最后一个元素）。

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

此方法充当基于数组的 API 与基于 collection 的 API 之间的桥梁。

指定者：

接口 Collection<E> 中的 toArray

返回：

按适当顺序包含该列表中所有元素的数组

另请参见：

Arrays.asList(Object[])

toArray

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

返回按适当顺序（从第一个元素到最后一个元素）包含列表中所有元素的数组；返回数组的运行时类型是指定数组的运行时类型。如果指定数组能容纳列表，则在其中返回该列表。否则，分配具有指定数组的运行时类型和此列表大小的新数组。

如果指定数组能容纳列表，并剩余空间（即数组的元素比列表的多），那么会将数组中紧随列表尾部的元素设置为 null。（只有 在调用者知道列表不包含任何 null 元素时此方法才能用于确定列表的长度）。

像 toArray() 方法一样，此方法充当基于数组的 API 与基于 collection 的 API 之间的桥梁。更进一步说，此方法允许对输出数组的运行时类型进行精确控制，在某些情况下，可以用来节省分配开销。

假定 x 是只包含字符串的一个已知列表。以下代码用来将该列表转储到一个新分配的 String 数组：

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

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

指定者：

接口 Collection<E> 中的 toArray

参数：

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

返回：

包含列表中元素的数组

抛出：

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

NullPointerException - 如果指定数组为 null

add

boolean add(E e)

向列表的尾部添加指定的元素（可选操作）。

支持该操作的列表可能对列表可以添加的元素有一些限制。特别是某些列表将拒绝添加 null 元素，其他列表将在可能添加的元素类型上施加限制。List 类应该在它们的文档中明确指定有关添加元素的所有限制。

指定者：

接口 Collection<E> 中的 add

参数：

e - 要添加到列表的元素

返回：

true（根据 Collection.add(E) 的规定）

抛出：

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

ClassCastException - 如果指定元素的类不允许它添加到此列表

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

IllegalArgumentException - 如果此元素的某些属性不允许它添加到此列表

remove

boolean remove(Object o)

从此列表中移除第一次出现的指定元素（如果存在）（可选操作）。如果列表不包含元素，则不更改列表。更确切地讲，移除满足 (o==null ? get(i)==null : o.equals(get(i))) 的最低索引 i 的元素（如果存在这样的元素）。如果此列表已包含指定元素（或者此列表由于调用而发生更改），则返回 true。

指定者：

接口 Collection<E> 中的 remove

参数：

o - 要从该列表中移除的元素，如果存在的话

返回：

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

抛出：

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

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

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

containsAll

boolean containsAll(Collection<?> c)

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

指定者：

接口 Collection<E> 中的 containsAll

参数：

c - 要在列表中检查其包含性的 collection

返回：

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

抛出：

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

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

另请参见：

contains(Object)

addAll

boolean addAll(Collection<? extends E> c)

添加指定 collection 中的所有元素到此列表的结尾，顺序是指定 collection 的迭代器返回这些元素的顺序（可选操作）。如果在操作正在进行中修改了指定的 collection，那么此操作的行为是不确定的（注意，如果指定的 collection 是此列表，并且它是非空的，则会发生这种情况。）

指定者：

接口 Collection<E> 中的 addAll

参数：

c - 包含要添加到此列表的元素的 collection

返回：

如果此列表由于调用而发生更改，则返回 true

抛出：

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

ClassCastException - 如果指定 collection 的元素的类不允许它添加到此列表

NullPointerException - 如果指定的 collection 包含一个或多个 null 元素，并且该列表不允许 null 元素，或者指定的 collection 为 null

IllegalArgumentException - 如果指定 collection 的元素的某些属性不允许它添加此列表

另请参见：

add(Object)

addAll

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

将指定 collection 中的所有元素都插入到列表中的指定位置（可选操作）。将当前处于该位置的元素（如果有的话）和所有后续元素向右移动（增加其索引）。新元素将按照它们通过指定 collection 的迭代器所返回的顺序出现在此列表中。如果在操作正在进行中修改了指定的 collection，那么该操作的行为是不确定的（注意，如果指定的 collection 是此列表，并且它是非空的，则会发生这种情况。）

参数：

index - 将指定 collection 的第一个元素所插入位置的索引

c - 包含要添加到此列表的元素的 collection

返回：

如果此列表由于调用而发生更改，则返回 true

抛出：

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

ClassCastException - 如果指定 collection 中某个元素的类不允许它添加到此列表

NullPointerException - 如果指定的 collection 包含一个或多个 null 元素，并且该列表不允许 null 元素，或者指定的 collection 为 null

IllegalArgumentException - 如果指定 collection 的元素的某些属性不允许它添加到此列表

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

removeAll

boolean removeAll(Collection<?> c)

从列表中移除指定 collection 中包含的其所有元素（可选操作）。

指定者：

接口 Collection<E> 中的 removeAll

参数：

c - 包含从此列表中移除的元素的 collection

返回：

如果此列表由于调用而发生更改，则返回 true

抛出：

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

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

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

另请参见：

remove(Object), contains(Object)

retainAll

boolean retainAll(Collection<?> c)

仅在列表中保留指定 collection 中所包含的元素（可选操作）。换句话说，该方法从列表中移除未包含在指定 collection 中的所有元素。

指定者：

接口 Collection<E> 中的 retainAll

参数：

c - 包含将保留在此列表中的元素的 collection

返回：

如果此列表由于调用而发生更改，则返回 true

抛出：

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

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

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

另请参见：

remove(Object), contains(Object)

clear

void clear()

从列表中移除所有元素（可选操作）。此调用返回后该列表将是空的。

指定者：

接口 Collection<E> 中的 clear

抛出：

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

equals

boolean equals(Object o)

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

指定者：

接口 Collection<E> 中的 equals

覆盖：

类 Object 中的 equals

参数：

o - 要与此列表进行相等性比较的对象

返回：

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

另请参见：

Object.hashCode(), Hashtable

hashCode

int hashCode()

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

  int hashCode = 1;
  Iterator<E> i = list.iterator();
  while (i.hasNext()) {
      E obj = i.next();
      hashCode = 31*hashCode + (obj==null ? 0 : obj.hashCode());
  }
 

这确保了 list1.equals(list2) 意味着对于任何两个列表 list1 和 list2 而言，可实现 list1.hashCode()==list2.hashCode()，正如 Object.hashCode() 的常规协定所要求的。

指定者：

接口 Collection<E> 中的 hashCode

覆盖：

类 Object 中的 hashCode

返回：

此列表的哈希码值

另请参见：

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)

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

参数：

index - 要在其中插入指定元素处的索引

element - 要插入的元素

抛出：

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

ClassCastException - 如果指定元素的类不允许它添加到此列表

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

IllegalArgumentException - 如果指定元素的某些属性不允许它添加到此列表

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

remove

E remove(int index)

移除列表中指定位置的元素（可选操作）。将所有的后续元素向左移动（将其索引减 1）。返回从列表中移除的元素。

参数：

index - 要移除的元素的索引

返回：

以前在指定位置的元素

抛出：

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

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

indexOf

int indexOf(Object o)

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

参数：

o - 要搜索的元素

返回：

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

抛出：

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

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

lastIndexOf

int lastIndexOf(Object o)

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

参数：

o - 要搜索的元素

返回：

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

抛出：

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

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

listIterator

ListIterator<E> listIterator()

返回此列表元素的列表迭代器（按适当顺序）。

返回：

此列表元素的列表迭代器（按适当顺序）

listIterator

ListIterator<E> listIterator(int index)

返回列表中元素的列表迭代器（按适当顺序），从列表的指定位置开始。指定的索引表示 next 的初始调用所返回的第一个元素。previous 方法的初始调用将返回索引比指定索引少 1 的元素。

参数：

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

返回：

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

抛出：

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

subList

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

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

此方法省去了显式范围操作（此操作通常针对数组存在）。通过传递 subList 视图而非整个列表，期望列表的任何操作可用作范围操作。例如，下面的语句从列表中移除了元素的范围：

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

可以对 indexOf 和 lastIndexOf 构造类似的语句，而且 Collections 类中的所有算法都可以应用于 subList。

如果支持列表（即此列表）通过任何其他方式（而不是通过返回的列表）从结构上修改，则此方法返回的列表语义将变为未定义（从结构上修改是指更改列表的大小，或者以其他方式打乱列表，使正在进行的迭代产生错误的结果）。

参数：

fromIndex - subList 的低端（包括）

toIndex - subList 的高端（不包括）

返回：

列表中指定范围的视图

抛出：

IndexOutOfBoundsException - 非法的端点值 (fromIndex < 0 || toIndex > size || fromIndex > toIndex)