|
|||||||||
| 摘要： 嵌套 | 字段 | 构造方法 | 方法 | 详细信息： 字段 | 构造方法 | 方法 | ||||||||
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 o) 向列表的尾部追加指定的元素（可选操作）。 |
|
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() 返回以正确顺序包含列表中的所有元素的数组。 |
|
|
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。更正式地说，当且仅当列表包含的元素 e 满足下列条件时才返回 true：(o==null ? e==null : o.equals(e))。
-
- 指定者：
-
接口
Collection<E>中的contains
-
- 参数：
-
o- 要测试列表中是否存在的元素。 - 返回：
- 如果列表包含指定的元素，则返回 true。
- 抛出：
-
ClassCastException- 如果指定元素的类型和此列表不兼容（可选）。 -
NullPointerException- 如果指定的元素为 null，并且此列表不支持 null 元素（可选）。
iterator
Iterator<E> iterator()
- 返回以正确顺序在列表的元素上进行迭代的迭代器。
-
- 返回：
- 以正确顺序在列表的元素上进行迭代的迭代器。
toArray
Object[] toArray()
- 返回以正确顺序包含列表中的所有元素的数组。遵守 Collection.toArray 方法的常规协定。
-
- 指定者：
-
接口
Collection<E>中的toArray
-
- 返回：
- 以正确顺序包含该列表中所有元素的数组。
- 另请参见：
-
Arrays.asList(Object[])
toArray
<T> T[] toArray(T[] a)
- 返回以正确顺序包含列表中所有元素的数组；返回数组的运行时类型是指定数组的运行时类型。遵守 Collection.toArray(Object[]) 方法的常规协定。
-
- 指定者：
-
接口
Collection<E>中的toArray
-
- 参数：
-
a- 要存储列表中元素的数组，如果它足够大的话；否则为此目的分配一个运行时类型相同的新数组。 - 返回：
- 包含列表中元素的数组。
- 抛出：
-
ArrayStoreException- 如果指定数组的运行时类型不是此列表中每个元素的运行时类型的超类型。 -
NullPointerException- 如果指定数组为 null。
add
boolean add(E o)
-
向列表的尾部追加指定的元素（可选操作）。
支持该操作的列表可能对列表可以添加的元素有一些限制。特别是某些列表将拒绝添加 null 元素，其他列表将在可能添加的元素类型上施加限制。List 类应该在它们的文档中明确指定有关添加元素的所有限制。
-
- 指定者：
-
接口
Collection<E>中的add
-
- 参数：
-
o- 要追加到列表的元素。 - 返回：
- true（根据 Collection.add 方法的常规协定）。
- 抛出：
-
UnsupportedOperationException- 如果列表不支持 add 方法。 -
ClassCastException- 如果指定元素的类不允许它添加到此列表。 -
NullPointerException- 如果指定的元素为 null，并且此列表不支持 null 元素。 -
IllegalArgumentException- 如果此元素的某个方面不允许它添加到此列表。
