|
JavaTM 2 Platform Standard Ed. 5.0 |
|||||||||
上一个类 下一个类 | 框架 无框架 | |||||||||
摘要: 嵌套 | 字段 | 构造方法 | 方法 | 详细信息: 字段 | 构造方法 | 方法 |
public interface List<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 的成员。
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)
返回以正确顺序包含列表中所有元素的数组;返回数组的运行时类型是指定数组的运行时类型。 |
方法详细信息 |
---|
int size()
Collection<E>
中的 size
boolean isEmpty()
Collection<E>
中的 isEmpty
boolean contains(Object o)
Collection<E>
中的 contains
o
- 要测试列表中是否存在的元素。
ClassCastException
- 如果指定元素的类型和此列表不兼容(可选)。
NullPointerException
- 如果指定的元素为 null,并且此列表不支持 null 元素(可选)。Iterator<E> iterator()
Collection<E>
中的 iterator
Iterable<E>
中的 iterator
Object[] toArray()
Collection<E>
中的 toArray
Arrays.asList(Object[])
<T> T[] toArray(T[] a)
Collection<E>
中的 toArray
a
- 要存储列表中元素的数组,如果它足够大的话;否则为此目的分配一个运行时类型相同的新数组。
ArrayStoreException
- 如果指定数组的运行时类型不是此列表中每个元素的运行时类型的超类型。
NullPointerException
- 如果指定数组为 null。boolean add(E o)
支持该操作的列表可能对列表可以添加的元素有一些限制。特别是某些列表将拒绝添加 null 元素,其他列表将在可能添加的元素类型上施加限制。List 类应该在它们的文档中明确指定有关添加元素的所有限制。
Collection<E>
中的 add
o
- 要追加到列表的元素。
UnsupportedOperationException
- 如果列表不支持 add 方法。
ClassCastException
- 如果指定元素的类不允许它添加到此列表。
NullPointerException
- 如果指定的元素为 null,并且此列表不支持 null 元素。
IllegalArgumentException
- 如果此元素的某个方面不允许它添加到此列表。boolean remove(Object o)
Collection<E>
中的 remove
o
- 要从该列表中移除的元素,如果存在的话。
ClassCastException
- 如果指定元素的类型和此列表不兼容(可选)。
NullPointerException
- 如果指定的元素是 null,并且此列表不支持 null 元素(可选)。
UnsupportedOperationException
- 如果列表不支持 remove 方法。boolean containsAll(Collection<?> c)
Collection<E>
中的 containsAll
c
- 要在列表中检查其包含性的 collection。
ClassCastException
- 如果指定 collection 中的一个或多个元素的类型和此列表不兼容(可选)。
NullPointerException
- 如果指定的 collection 包含一个或多个 null 元素,并且此列表不支持 null 元素(可选)。
NullPointerException
- 如果指定的 collection 为 null。contains(Object)
boolean addAll(Collection<? extends E> c)
Collection<E>
中的 addAll
c
- 其元素要被添加到此列表的 collection。
UnsupportedOperationException
- 如果列表不支持 addAll 方法。
ClassCastException
- 如果指定 collection 中的元素的类不允许它添加到此列表。
NullPointerException
- 如果指定的 collection 包含一个或多个 null 元素,并且该列表不支持 null 元素,或者指定的 collection 为 null。
IllegalArgumentException
- 如果指定 collection 中的元素的某个方面不允许它添加此列表。add(Object)
boolean addAll(int index, Collection<? extends E> c)
index
- 将指定 collection 的第一个元素所插入位置的索引。c
- 要插入到列表中的元素。
UnsupportedOperationException
- 如果列表不支持 addAll 方法。
ClassCastException
- 如果指定 collection 中某个元素的类不允许它添加到此列表。
NullPointerException
- 如果指定的 collection 包含一个或多个 null 元素,并且该列表不支持 null 元素,或者指定的 collection 为 null。
IllegalArgumentException
- 如果指定 collection 中某个元素的某些方面不允许它添加到此列表。
IndexOutOfBoundsException
- 如果索引超出范围 (index < 0 || index > size())。boolean removeAll(Collection<?> c)
Collection<E>
中的 removeAll
c
- 定义将从此列表中移除哪些元素的 collection。
UnsupportedOperationException
- 如果列表不支持 removeAll 方法。
ClassCastException
- 如果此列表中的一个或多个元素和指定的 collection 不兼容(可选)。
NullPointerException
- 如果此列表包含一个或多个 null 元素,并且指定的 collection 不支持 null 元素(可选)。
NullPointerException
- 如果指定的 collection 为 null。remove(Object)
,
contains(Object)
boolean retainAll(Collection<?> c)
Collection<E>
中的 retainAll
c
- 定义此 set 将保留哪些元素的 collection。
UnsupportedOperationException
- 如果列表不支持 retainAll 方法。
ClassCastException
- 如果此列表中的一个或多个元素和指定的 collection 不兼容(可选)。
NullPointerException
- 如果此列表包含一个或多个 null 元素,并且指定的 collection 不支持 null 元素(可选)。
NullPointerException
- 如果指定的 collection 为 null。remove(Object)
,
contains(Object)
void clear()
Collection<E>
中的 clear
UnsupportedOperationException
- 如果列表不支持 clear 方法。boolean equals(Object o)
Collection<E>
中的 equals
Object
中的 equals
o
- 要与此列表进行相等性比较的对象。
Object.hashCode()
,
Hashtable
int hashCode()
hashCode = 1; Iterator i = list.iterator(); while (i.hasNext()) { Object 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.hashCode()
,
Object.equals(Object)
,
equals(Object)
E get(int index)
index
- 要返回的元素的索引。
IndexOutOfBoundsException
- 如果索引超出范围 (index < 0 || index >= size())。E set(int index, E element)
index
- 要替换的元素的索引。element
- 要在指定位置存储的元素。
UnsupportedOperationException
- 如果列表不支持 set 方法。
ClassCastException
- 如果指定元素的类不允许它添加到此列表。
NullPointerException
- 如果指定的元素为 null,并且此列表不支持 null 元素。
IllegalArgumentException
- 如果指定元素的某个方面不允许它添加到此列表。
IndexOutOfBoundsException
- 如果索引超出范围 (index < 0 || index >= size())。void add(int index, E element)
index
- 要在其中插入指定元素处的索引。element
- 要插入的元素。
UnsupportedOperationException
- 如果列表不支持 add 方法。
ClassCastException
- 如果指定元素的类不允许它添加到此列表。
NullPointerException
- 如果指定的元素为 null,并且此列表不支持 null 元素。
IllegalArgumentException
- 如果指定元素的某个方面不允许它添加到此列表。
IndexOutOfBoundsException
- 如果索引超出范围 (index < 0 || index > size())。E remove(int index)
index
- 要移除的元素的索引。
UnsupportedOperationException
- 如果列表不支持 remove 方法。
IndexOutOfBoundsException
- 如果索引超出范围 (index < 0 || index >= size())。int indexOf(Object o)
o
- 要搜索的元素。
ClassCastException
- 如果指定元素的类型和此列表不兼容(可选)。
NullPointerException
- 如果指定的元素是 null,并且此列表不支持 null 元素(可选)。int lastIndexOf(Object o)
o
- 要搜索的元素。
ClassCastException
- 如果指定元素的类型和此列表不兼容(可选)。
NullPointerException
- 如果指定的元素是 null,并且此列表不支持 null 元素(可选)。ListIterator<E> listIterator()
ListIterator<E> listIterator(int index)
index
- 从列表迭代器返回的首个元素的索引(通过调用 next 方法)。
IndexOutOfBoundsException
- 如果索引超出范围 (index < 0 || index > size())。List<E> subList(int fromIndex, int toIndex)
此方法省去了显式范围操作(此操作通常针对数组存在)。通过传递 subList 视图而非整个列表,期望列表的任何操作可用作范围操作。例如,下面的语句从列表中移除了元素的范围:
list.subList(from, to).clear();可以对 indexOf 和 lastIndexOf 构造类似的语句,而且 Collections 类中的所有算法都可以应用于 subList。
如果支持列表(即此列表)通过任何其他方式(而不是通过返回的列表)从结构上修改,则此方法返回的列表语义将变为未定义(从结构上修改是指更改列表的大小,或者以其他方式打乱列表,使正在进行的迭代产生错误的结果)。
fromIndex
- subList 的低端(包括)。toIndex
- subList 的高端(不包括)。
IndexOutOfBoundsException
- 非法的端点值 (fromIndex < 0 || toIndex > size || fromIndex > toIndex)。
|
JavaTM 2 Platform Standard Ed. 5.0 |
|||||||||
上一个类 下一个类 | 框架 无框架 | |||||||||
摘要: 嵌套 | 字段 | 构造方法 | 方法 | 详细信息: 字段 | 构造方法 | 方法 |
版权所有 2004 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。