E
- 此列表中元素的类型
public interface List<E> extends Collection<E>
与集合不同,列表通常允许重复的元素。 更正式地,列表通常允许元素e1和e2成对使得e1.equals(e2) ,并且如果它们允许空元素,它们通常允许多个空元素。 有人可能希望实现一个禁止重复的列表,当用户尝试插入时会抛出运行时异常,但是我们预计这种使用是罕见的。
该List接口放置额外的约定,超过在Collection指定接口上的iterator,add,remove,equals和hashCode方法合同。 其他继承方法的声明也包括在这里以方便。
List接口提供四种位置(索引)访问列表元素的方法。 列表(如Java数组)为零。 请注意,这些操作可能与某些实现的索引值(例如LinkedList类)成时执行。 因此,如果调用者不知道实现,则通过迭代列表中的元素通常优先于索引。
所述List接口提供了一个特殊的迭代器,称为ListIterator,其允许元件插入和更换,并且除了该Iterator接口提供正常操作的双向访问。 提供了一种方法来获取从列表中的指定位置开始的列表迭代器。
List接口提供了两种方法来搜索指定的对象。 从性能角度来说,谨慎使用这些方法。 在许多实现中,它们将执行昂贵的线性搜索。
List接口提供了两种方法来有效地插入和删除列表中任意一点的多个元素。
注意:虽然列表允许将其自身作为元素,但建议您非常小心: equals和hashCode方法在这样的列表中不再被很好地定义。
某些列表实现对它们可能包含的元素有限制。 例如,一些实现禁止空元素,有些实现对元素的类型有限制。 尝试添加不合格元素会引发未经检查的异常,通常为NullPointerException或ClassCastException 。 尝试查询不合格元素的存在可能会引发异常,或者可能只是返回false; 一些实现将展现出前者的行为,一些实现将展现出后者。 更一般来说,对于不完成不会导致将不合格元素插入到列表中的不合格元素的操作,可能会在执行选项时抛出异常或成功。 此异常在此接口的规范中标记为“可选”。
此接口是成员Java Collections Framework 。
Collection
, Set
, ArrayList
, LinkedList
, Vector
, Arrays.asList(Object[])
, Collections.nCopies(int, Object)
, Collections.EMPTY_LIST
, AbstractList
, AbstractSequentialList
Modifier and Type | Method and Description |
---|---|
boolean |
add(E e)
将指定的元素追加到此列表的末尾(可选操作)。
|
void |
add(int index, E element)
将指定的元素插入此列表中的指定位置(可选操作)。
|
boolean |
addAll(Collection<? extends E> c)
按指定集合的迭代器(可选操作)返回的顺序将指定集合中的所有元素附加到此列表的末尾。
|
boolean |
addAll(int index, 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 。
|
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)
从此列表中删除包含在指定集合中的所有元素(可选操作)。
|
default void |
replaceAll(UnaryOperator<E> operator)
将该列表的每个元素替换为将该运算符应用于该元素的结果。
|
boolean |
retainAll(Collection<?> c)
仅保留此列表中包含在指定集合中的元素(可选操作)。
|
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)
以正确的顺序返回一个包含此列表中所有元素的数组(从第一个到最后一个元素);
返回的数组的运行时类型是指定数组的运行时类型。
|
parallelStream, removeIf, stream
int size()
size
在接口
Collection<E>
boolean isEmpty()
isEmpty
在接口
Collection<E>
boolean contains(Object o)
contains
在界面
Collection<E>
o
- 要在此列表中存在的元素将被测试
ClassCastException
- 如果指定元素的类型与此列表不兼容(
optional )
NullPointerException
- 如果指定的元素为空,并且该列表不允许空元素(
optional )
Object[] toArray()
返回的数组将是“安全的”,因为该列表不保留对它的引用。 (换句话说,即使这个列表被数组支持,这个方法也必须分配一个新的数组)。 因此,调用者可以自由地修改返回的数组。
此方法充当基于阵列和基于集合的API之间的桥梁。
toArray
在界面
Collection<E>
Arrays.asList(Object[])
<T> T[] toArray(T[] a)
如果列表适用于指定的数组,其余空间(即,该数组具有比该列表更多的元素),那么紧跟该列表结束后的数组中的元素将设置为null 。 (这仅在调用者知道列表不包含任何空元素的情况下才能确定列表的长度。)
像toArray()
方法一样,此方法充当基于阵列和基于集合的API之间的桥梁。 此外,该方法允许精确地控制输出阵列的运行时类型,并且在某些情况下可以用于节省分配成本。
假设x是一个已知只包含字符串的列表。 下面的代码可以被用来将该列表转储到的String一个新分配的阵列:
String[] y = x.toArray(new String[0]);
请注意, toArray(new Object[0])的功能与toArray()相同 。
toArray
在界面
Collection<E>
T
- 包含集合的数组的运行时类型
a
- 要存储此列表的元素的数组,如果它足够大;
否则,为此目的分配相同运行时类型的新数组。
ArrayStoreException
- 如果指定数组的运行时类型不是此列表中每个元素的运行时类型的超类型
NullPointerException
- 如果指定的数组为空
boolean add(E e)
支持此操作的列表可能会限制可能添加到此列表中的元素。 特别地,一些列表将拒绝添加null元素,而其他列表将对可能添加的元素的类型施加限制。 列表类应在其文档中明确指定可能添加哪些元素的限制。
add
在接口
Collection<E>
e
- 要附加到此列表的元素
Collection.add(E)
规定 )
UnsupportedOperationException
-如果
add操作不受此列表支持
ClassCastException
- 如果指定元素的类阻止将其添加到此列表中
NullPointerException
- 如果指定的元素为空,并且该列表不允许空元素
IllegalArgumentException
- 如果此元素的某些属性阻止将其添加到此列表
boolean remove(Object o)
remove
在接口
Collection<E>
o
- 要从此列表中删除的元素(如果存在)
ClassCastException
- 如果指定元素的类型与此列表不兼容(
optional )
NullPointerException
- 如果指定的元素为空,并且该列表不允许空元素(
optional )
UnsupportedOperationException
-如果
remove操作不受此列表支持
boolean containsAll(Collection<?> c)
containsAll
在接口
Collection<E>
c
- 要在此列表中检查遏制的集合
ClassCastException
- 如果指定集合中的一个或多个元素的类型与此列表不兼容(
optional )
NullPointerException
- 如果指定的集合包含一个或多个空元素,并且该列表不允许空元素(
optional ),或者如果指定的集合为空
contains(Object)
boolean addAll(Collection<? extends E> c)
addAll
在界面
Collection<E>
c
- 包含要添加到此列表的元素的集合
UnsupportedOperationException
-如果
addAll操作不受此列表支持
ClassCastException
- 如果指定集合的元素的类阻止将其添加到此列表
NullPointerException
- 如果指定的集合包含一个或多个空元素,并且该列表不允许空元素,或者如果指定的集合为空
IllegalArgumentException
- 如果指定集合的元素的某些属性阻止其添加到此列表
add(Object)
boolean addAll(int index, Collection<? extends E> c)
index
- 从指定集合插入第一个元素的索引
c
- 包含要添加到此列表的元素的集合
UnsupportedOperationException
-如果
addAll操作不受此列表支持
ClassCastException
- 如果指定集合的元素的类阻止将其添加到此列表
NullPointerException
- 如果指定的集合包含一个或多个空元素,并且该列表不允许空元素,或者如果指定的集合为空
IllegalArgumentException
- 如果指定集合的元素的某些属性阻止其添加到此列表中
IndexOutOfBoundsException
- 如果索引超出范围(
index < 0 || index > size() )
boolean removeAll(Collection<?> c)
removeAll
在接口
Collection<E>
c
- 包含要从此列表中删除的元素的集合
UnsupportedOperationException
-如果
removeAll操作不受此列表支持
ClassCastException
- 如果此列表的元素的类与指定的集合不兼容(
optional )
NullPointerException
- 如果此列表包含空元素,并且指定的集合不允许空元素(
optional ),或者如果指定的集合为空
remove(Object)
,
contains(Object)
boolean retainAll(Collection<?> c)
retainAll
在接口
Collection<E>
c
- 包含要保留在此列表中的元素的集合
UnsupportedOperationException
-如果
retainAll操作不受此列表支持
ClassCastException
- 如果此列表的元素的类与指定的集合不兼容(
optional )
NullPointerException
- 如果此列表包含空元素,并且指定的集合不允许空元素(
optional ),或者如果指定的集合为空
remove(Object)
,
contains(Object)
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
- 如果指定的运算符为空,或者运算符结果为空值,并且该列表不允许空元素(
optional )
default void sort(Comparator<? super E> c)
Comparator
排序此列表来比较元素。
list
:
Collections.sort(list, c)
c
- 用于比较列表元素的Comparator
。
null
值表示应使用元素' natural ordering '
ClassCastException
- 如果列表包含使用指定比较器不
相互比较的元素
UnsupportedOperationException
- 如果列表的list-iterator不支持
set
操作
IllegalArgumentException
- ( optional )如果比较方发现违反Comparator
合同
void clear()
clear
在接口
Collection<E>
UnsupportedOperationException
-如果
clear操作不受此列表支持
boolean equals(Object o)
equals
在界面
Collection<E>
equals
在
Object
o
- 要与此列表相等的对象进行比较
Object.hashCode()
, HashMap
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()
的一般合同的要求 。
hashCode
在接口
Collection<E>
hashCode
在
Object
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
- 如果指定的元素为空,并且该列表不允许空元素
IllegalArgumentException
- 如果指定元素的某些属性阻止将其添加到此列表中
IndexOutOfBoundsException
- 如果指数超出范围(
index < 0 || index >= size() )
void add(int index, E element)
index
- 要插入指定元素的索引
element
- 要插入的元素
UnsupportedOperationException
-如果
add操作不受此列表支持
ClassCastException
- 如果指定元素的类阻止将其添加到此列表中
NullPointerException
- 如果指定的元素为空,并且该列表不允许空元素
IllegalArgumentException
- 如果指定元素的某些属性阻止其添加到此列表中
IndexOutOfBoundsException
- 如果指数超出范围(
index < 0 || index > size() )
E remove(int index)
index
- 要删除的元素的索引
UnsupportedOperationException
-如果
remove操作不受此列表支持
IndexOutOfBoundsException
- 如果索引超出范围(
index < 0 || index >= size() )
int indexOf(Object o)
o
- 要搜索的元素
ClassCastException
- 如果指定元素的类型与此列表不兼容(
optional )
NullPointerException
- 如果指定的元素为空,并且此列表不允许空元素(
optional )
int lastIndexOf(Object o)
o
- 要搜索的元素
ClassCastException
- 如果指定元素的类型与此列表不兼容(
optional )
NullPointerException
- 如果指定的元素为空,并且该列表不允许空元素(
optional )
ListIterator<E> listIterator()
ListIterator<E> listIterator(int index)
index
- 要从列表迭代器返回的第一个元素的索引(通过调用
next
)
IndexOutOfBoundsException
- 如果索引超出范围(
index < 0 || index > size()
)
List<E> subList(int fromIndex, int toIndex)
该方法消除了对显式范围操作(对于数组通常存在的排序)的需要。 任何期望列表的操作都可以通过传递一个子列表视图而不是整个列表来用作范围操作。 例如,以下成语从列表中移除了一系列元素:
list.subList(from, to).clear();
可以为indexOf和lastIndexOf构造类似的成语,并且Collections类中的所有算法都可以应用于子列表 。
如果支持列表(即,此列表)以除了通过返回的列表之外的任何方式进行结构修改 ,则此方法返回的列表的语义将变得未定义。 (结构修改是那些改变此列表的大小,或以其他方式扰乱它,使得正在进行的迭代可能产生不正确的结果)。
fromIndex
-
fromIndex
低端点(含)
toIndex
-
toIndex
高端点(排他)
IndexOutOfBoundsException
- 对于非法端点索引值(
fromIndex < 0 || toIndex > size || fromIndex > toIndex )
default Spliterator<E> spliterator()
Spliterator
。
Spliterator
报告Spliterator.SIZED
和Spliterator.ORDERED
。 实施应记录其他特征值的报告。
spliterator
在界面
Collection<E>
spliterator
在接口
Iterable<E>
Iterator
创建一个late-binding拼接Iterator
。
分割器继承列表迭代器的故障快速属性。
Spliterator
另外报告
Spliterator.SUBSIZED
。
Spliterator
在这个列表中的元素