Java源码 java.util.List接口学习记录

List接口继承自Collection接口
List的实现类有LinkedList、ArrayList、AbstractList、Vector

1、int size()
返回这个list的元素数量

2、boolean isEmpty()
如果这个list没有元素，返回true。
用于判断list是否为空

3、boolean contains(Object o)
如果这个list包含指定元素，返回true
如果这个list包含一个元素满足(o=null ? e==null : o.equals(e))时，也返回true
抛出异常：
ClassCastException ：如果这个指定元素的类型不兼容这个list
NullPointerException : 如果这个指定元素为null，而这个list不允许存在null元素

4、@Notnull Iterator iterator() :
以正确的顺序返回列表中元素的迭代器
不能为空，如果需要使用迭代器，最好先做一下list判空的操作

5、@Notnull Object[] toArray() :
返回一个包含这个list所有元素和元素排序一致的数组
返回的数组将是‘安全的’，因为没有对这个list的引用进行修改。调用者可以自由修改返回的数组。
这个方法充当基于数组和基于集合的桥梁
不能为空，如果需要使用迭代器，最好先做一下list判空的操作

6、@Notnull T[] toArray(@NotnullT[] a) :
返回一个数组，其中包含列表中的所有元素正确序列(从第一个元素到最后一个元素);的运行时类型返回的数组是指定数组的数组。
如果列表符合在指定的数组中，它将在其中返回。否则,一个新的使用指定数组和的运行时类型分配数组这个列表的大小。
与toArray()方法一样，这个方法充当了基于数组和基于集合的api之间的桥梁。此外，这种方法允许对输出数组的运行时类型进行精确控制，并且在某些情况下，可以使用这种方法来节省分配成本。
异常：
ArrayStoreException：如果指定数组的运行时类型不是此列表中每个元素的运行时类型的超类型
NullPointerException: 如果这个数组是null

7、boolean add(E e) :
在数组的末尾添加这个元素
支持此操作的列表可能会对可以添加到该列表的元素进行限制。特别是，一些列表将拒绝添加空元素，而其他列表将对可能添加的元素类型施加限制。List类应该在其文档中明确指定对添加元素的任何限制。
异常：UnsupportedOperationException: 如果添加操作不被list允许
ClassCastException：如果指定元素的类阻止将其添加到此列表中
NullPointerException: 如果这个元素为null，且这个list不允许null元素
IllegalArgumentException:如果这个元素的某些特性阻止它被添加到这个list中

8、boolean remove(Object o)：
如果o这个元素在list中存在，在list中移除第一次出现与0相同的元素。如果这个list中不包含o，则不会发生改变。
更正式的说法是，删除索引i最低的元素，这样(o==null ?get(i)==null: o.equals(get(i))(如果存在这样的元素)。如果列表中包含指定的元素(或等效地，如果列表因调用而改变)，则返回true。
返回true，如果这个list包含这个o元素
异常：ClassCastException:如果这个指定元素的类型与这个list相矛盾
NullPointerException: 如果这个元素为null，且这个list不允许null元素
UnsupportedOperationException:如果移除操作不被这个list允许

9、boolean containsAll(Collection<?> c)：
如果这个list包含所有指定c中的元素，返回true
异常：ClassCastException：如果这个指定c中一个或多个元素的类型与这个list相矛盾
NullPointerException： 如果这个指定c中一个或多个元素为null，而这个list不允许null元素。或者这个指定元素为null

10、boolean addAll(Collection<? extends E> c)：
按照指定集合的迭代器(可选操作)返回的顺序，将指定集合中的所有元素追加到列表的末尾。如果在操作进行中修改了指定的集合，则此操作的行为未定义。(注意，如果指定的集合是这个列表，并且它是非空的，就会出现这种情况。)
返回true，如果这个list发生变化
异常：UnsupportedOperationException: 这个addAll操作不被的这个list允许
ClassCastException: 如果指定集合中的一个元素的类阻止它被添加到这个list
NullPointerException：如果这个指定集合包含一个或多个null元素，且这个list不允许null元素。或者这个指定集合为null
IllegalArgumentException: 如果这个指定集合的一个元素的一些特性阻止它添加到这个list中

11、addAll
boolean addAll(int index,Collection<? extends E> c)：
将指定的集合中的所有元素，插入到这个list中的指定位置。
将当前位于该位置的元素(如果有的话)和随后的元素向右移动(增加它们的下标)。新元素将按照指定集合的迭代器返回的顺序出现在这个列表中。如果在操作进行中修改了指定的集合，则此操作的行为未定义。(注意，如果指定的集合是这个列表，并且它是非空的，就会出现这种情况。)
如果这个list发生改变，返回值为true
异常：
UnsupportedOperationException: 如果addAll这个操作不被这个list允许
ClassCastException: 如果这个指定集合的某个元素的类阻止它被添加到这个list
NullPointerException: 如果这个集合中包含一个或多个null元素，而这个list不允许存在null元素。或者这个指定集合为null。
IllegalArgumentException: 如果这个指定集合中某个元素的属性阻止它被添加到这个list中
IndexOutOfBoundsException: 如果索引超出范围。（比如index<0 或者 index>size()）

12、removeAll
boolean removeAll(Collection<?> c)：
从列表中删除指定集合中包含的所有元素
如果这个list发生改变，返回值为true
异常：
UnsupportedOperationException：如果removeAll操作不被这个list允许
ClassCastException：如果这个list中的某个元素的类与指定集合相矛盾
NullPointerException：如果这个集合包含一个nul元素，而这个指定集合不允许null元素。或者这个指定集合为null

13、retainAll
boolean retainAll(Collection<?> c)：
仅保留这个list中元素被包含在指定集合中的元素。换句话说，移除这个list中所有不被包含在这个指定集合中的元素。
返回true，如果这个list发生变化
异常：
UnsupportedOperationException: 如果retainAll 操作不被这个list支持
ClassCastException：如果这个list中的某个元素的类与指定集合相矛盾
NullPointerException：如果这个list中包含null元素，指定集合中不允许null元素。或者指定集合为null

14、replaceAll
default void replaceAll(UnaryOperator operator)：
将此列表中的每个元素替换为对该元素应用操作符的结果。操作符抛出的错误或运行时异常被转发给调用者。
代码示例：

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

异常：
UnsupportedOperationException：如果此列表不可修改。如果不能替换某个元素，或者通常不支持修改，则实现可能抛出此异常
NullPointerException: 如果指定的操作符为空，或者操作符结果为空值，并且该列表不允许空元素(可选)
开始于1.8版本

15、sort
default void sort(Comparator<? super E> c)：
根据指定的比较器导出的顺序对列表进行排序。
该列表中的所有元素必须使用指定的比较器相互比较(即c.compare(e1, e2)绝不能为列表中的任何元素e1和e2抛出ClassCastException)。
如果指定的比较器为null，那么这个列表中的所有元素都必须实现Comparable接口，并且应该使用元素的自然排序。
此列表必须是可修改的，但不需要调整大小。
异常：
ClassCastException: 如果这个list中包含的元素不能用这个指定的比较器进行相互的比较
UnsupportedOperationException：如果这个list的list迭代器不支持set操作
IllegalArgumentException: 如果这个比较器违反了比较器（Comparator）的约定

16、clear
void clear()：
从list中移除所有元素，调用这个方法后，list将为空。
异常：
UnsupportedOperationException：如果clear操作不被这个list支持

17、equals
boolean equals(Object o)：
比较指定对象与此列表是否相等。当且仅当指定的对象也是一个列表，且两个列表的大小相同，且两个列表中所有对应的元素对相等时返回true。if (e1==null ?e2 = = null: . equals (e2)))。换句话说，如果两个列表以相同的顺序包含相同的元素，那么它们就被定义为相等。这个定义确保equals方法在List接口的不同实现中正常工作。

18、hashCode
int hashCode()：
返回此列表的哈希码值。列表的哈希码被定义为以下计算的结果:

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

这确保了list1.equals(list2)意味着list1. hashcode ()==list2. hashcode()，这是Object.hashCode()的通用契约所要求的。

19、get
E get(int index)：
返回这个list中指定位置的元素
异常：
IndexOutOfBoundsException:下标越界：（index<0 || index>size()）

20、set
E set(int index,E element)：
将list指定下标的元素替换为指定元素。
返回先前位于指定位置的元素
异常：
UnsupportedOperationException：如果set操作不被这个list支持
ClassCastException：如果指定元素的类阻止它被添加到这个list
NullPointerException：如果这个指定元素为null，并且这个list不允许null元素
IllegalArgumentException：如果这个指定元素的一些属性阻止它被添加到这个list中
IndexOutOfBoundsException: 下标越界：（index<0||index>size()）

21、add
void add(int index, E element):
在list的指定位置（index）出插入指定的元素。移动当前那个位置的元素，随后的元素也向右移动。
index：index是指指定元素被插入在哪个位置
element：被插入的元素
异常：
UnsupportedOperationException: 如果addAll这个操作不被这个list允许
ClassCastException: 如果这个元素的类阻止它被插入到这个list中
NullPointerException: 如果指定元素为null，这个list不允许null元素
IllegalArgumentException: 如果这个元素的某些特性阻止它被添加到这个list中
IndexOutOfBoundsException: 如果索引超出范围。（比如index<0||index>size())

22、remove
E remove(int index)：
移除list中指定位置（index）的元素，向左移动随后的所有元素，返回被移除的的元素
index：index是指 哪个位置上的元素被移除
异常：
UnsupportedOperationException: 如果移除操作不被这个list允许
IndexOutOfBoundsException: 如果index超过范围（index<0||index>size()）

23、indexOf
int indexOf(Object o):
返回指定元素在这个list中第一次被发现时的下标，如果这个list不包含这个元素返回-1。
O ：查询的那个元素
异常：
ClassCastException：如果这个指定元素的类型与这个list相矛盾
NullPointerException：如果这个指定元素为null，并且这个list不允许null元素

24、lasIndexOf
int lasIndexOf(Object o):
返回指定元素在这个list中最后被发现时的下标，如果这个list不包含这个元素返回-1。
O ：查询的那个元素
异常：
ClassCastException：如果这个指定元素的类型与这个list相矛盾
NullPointerException：如果这个指定元素为null，并且这个list不允许null元素

25、listIterator
ListIterator listIterator()：
返回列表中所有元素的列表迭代器

26、listIterator
ListIterator listIterator(int index)：
返回列表中所有元素的列表迭代器，起始位置为指定位置。指定的索引指示对next的初始调用将返回的第一个元素。对previous的初始调用将返回指定索引为 -1的元素。
异常：
IndexOutOfBoundsException:下标越界（index<0||index >size()）

27、sublist
List subList(int fromIndex, int toIndex)：
返回list的下标从formindex（包含）到toindex（不包含）之间的元素（如果formindex和toindex相同，返回的list为空）。
返回的list由该list支持，因此返回list中的非结构化更改反映在该list中，反之亦然。返回的list支持该list支持的所有可选list操作。
这个方法不需要显式的范围操作(数组通常存在的那种操作)。任何需要列表的操作都可以通过传递子列表视图而不是整个列表来作为范围操作。例如，下面的习惯用法从列表中删除一系列元素:
list.subList(from, to).clear();
异常：
IndexOutOfBoundsException:为非法端点索引值(fromIndex < 0 || toIndex > size || fromIndex > toIndex)

28、spliterator
default Spliterator spliterator()：
在列表中的元素上创建一个拆分器。
Spliterator报告Spliterator.size和Spliterator.ORDERED。实现应记录额外特征值的报告。
开始于1.8版本

以上为List接口中的所有方法的翻译和说明，有兴趣的可以翻看一下文章：
1、Java源码 java.util.List接口学习记录（一）
2、Java源码 java.util.List接口学习记录（二）
3、Java源码 java.util.List接口学习记录（三）