java容器 接口List源码分析
目录
简介
查询操作- size,isEmpty,contains,iterator,toArray
修改操作-add,remove
批量修改操作-containsAll,addAll,removeAll,retainAll,replaceAll,sort,clear
比较和哈希-equals,hashCode
位置访问操作-get,set,add,remove
查询操作-indexOf,lastIndexOf
ListIterator-两个重载方法
查看-subList,spliterator
简介
/**
* 一个有序的列表（能用index访问到元素）（也是一个序列）。
* 使用这个接口的用户，能够精确控制列表中每个元素插入的位置。
* 用户能够用int的下标（列表中的位置）访问到元素，并且查找列表中的元素
*
*
不像set，list通常允许重复的元素。更正式地说，列表通常允许成对的元素e1和e2，
* e1.equals(e2),并且他们通常允许多个null元素，如果它们允许null元素。
* 如果有人希望实现一个禁止重复的列表是可能的，但是我们认为这种用法很少。
*
*
列表接口有着额外的规定，超越了collection接口，
* 在iterator，add，remove，equals，hashcode方法的约定上。
* 对其他继承的声明任然在这里，为了方便。
*
*
list接口为基于位置（index）的访问列表元素提供了4个方法。
* List（像java的数组）是基于0的。
* 注意：这些操作可能执行的时间可能与index的值成正比，对于某些实现而言（例如LinkedList类）
* 因此，如果调用者不知道实现，遍历列表的元素通常比根据index遍历更好些。
*
*
list接口提供了一个特殊的iterator，称为ListIterator，
* 它允许元素插入，替代，和反向访问，还有Iterator接口提供的常规操作。
* 提供了一个方法来获取一个从特定位置开始的ListIterator
*
*
List接口为查找一个指定对象，提供了两个方法。
* 从性能的角度看，这种方法应该谨慎使用。
* 许多实现中，它们将执行价格高昂的线性搜索。
*
*
List接口提供了两种方法来有效地在列表的任意地方插入和删除多个元素。
*
*
注意：虽然允许列表包含它们自身作为元素，一定要注意：
* equals和hashCode方法在这样的list中定义的不是很好。
*
*
一些List的实现对可以包含的元素有限制。
* 例如，一些实现禁止null元素，一些对它们的类型有限制。
* 试图添加不符合条件的元素会抛出一个未检查异常，通常是NullPointerException或ClassCastException。
* 试图查询一个不符合条件的元素可能抛出一个异常，或通常返回false。
* 一些实现显示前一个行为，一些显示后面的。
* 更一般地说，尝试对不符合条件的元素执行操作，如果该元素的完成不会导致将不符合条件的元素插入到列表中，
* 则可能会引发异常，也可能会成功，这取决于实现的选项。
* 在这个接口的规范中，这些异常被标记为“可选”。
*
*
* @param the type of elements in this list
*
* @author Josh Bloch
* @author Neal Gafter
* @see Collection
* @see Set
* @see ArrayList
* @see LinkedList
* @see Vector
* @see Arrays#asList(Object[])
* @see Collections#nCopies(int, Object)
* @see Collections#EMPTY_LIST
* @see AbstractList
* @see AbstractSequentialList
* @since 1.2
*/
public interface List extends Collection
查询操作- size,isEmpty,contains,iterator,toArray
方法与collection中的相同
/**
* 返回列表中元素的数量。如果列表包含超过Integer.MAX_VALUE的元素，返回Integer.MAX_VALUE
*
* @return the number of elements in this list
*/
int size();
/**
* 如果列表不包含任何元素，返回true
*
* @return true if this list contains no elements
*/
boolean isEmpty();
/**
* 如果列表包含指定元素，返回true。
* 更正式地，当且仅当列表至少有一个这样的元素时，返回true。
* (o==null ? e==null : o.equals(e)).
*
* @param o element whose presence in this list is to be tested
* @return true if this list contains the specified element
* @throws ClassCastException if the type of the specified element
* is incompatible with this list
* (optional)
* @throws NullPointerException if the specified element is null and this
* list does not permit null elements
* (optional)
*/
boolean contains(Object o);
/**
* 返回一个覆盖这个列表所有元素的iterator(以适当的顺序）。
*
* @return an iterator over the elements in this list in proper sequence
*/
Iterator iterator();
/**
* 返回一个包含这个列表所有元素的数组。（从第一个到最后一个元素）
*
* 返回的数组是安全的，因为列表没有维持对它的引用
* （换言而之，这个方法必须分配一个新的数组，即使列表内部已经有一个数组了）。
* 因此调用者修改返回的数组是安全的。
*
*
这个方法是基于数组和基于列表的API之间的桥梁。
*
* @return an array containing all of the elements in this list in proper
* sequence
* @see Arrays#asList(Object[])
*/
Object[] toArray();
/**
*
*
返回一个包含这个列表所有元素的数组。（从第一个到最后一个元素）
* 返回的数组的运行时类型是指定数组的类型。
* 如果列表适合这个指定的数组的大小，她就在里面返回。
* 否则，创建一个新数组，类型为指定数组的运行时类型，大小为这个列表的大小。
*
*
如果该列表适应指定的数组，有着剩余的空间（数组比列表有更多的元素），
* 数组中的元素在列表的末尾的，被设置为null。
* （如果调用者知道列表确实没有任何null元素，这才有助于决定列表的长度）
*
*
像toArray()方法，这个方法作为基于数组和基于列表的API之间的桥梁。
* 此外，这个方法允许对输出的数组的运行时类型做出精确的控制。
* 在某些情况下，可能有助于减少分配的成本。
*
*
假设x是一个只能包含string的列表。
* 下面的代码能用于将列表放入一个新分配的string数组。
*
*
* String[] y = x.toArray(new String[0]);
*
* 注意：toArray(new Object[0])等价于toArray()的功能
*
* @param a the array into which the elements of this list are to
* be stored, if it is big enough; otherwise, a new array of the
* same runtime type is allocated for this purpose.
* @return an array containing the elements of this list
* @throws ArrayStoreException if the runtime type of the specified array
* is not a supertype of the runtime type of every element in
* this list
* @throws NullPointerException if the specified array is null
*/
T[] toArray(T[] a); 修改操作-add,remove
与collection的相同
/**
* 在列表的最后加入一个指定元素（可选操作）
*
*
支持此操作的列表可能会限制加入到列表的元素。
* 尤其是，一些列表拒绝添加null元素，一些对元素的类型做限制。
* 列表类应该明确地在他们的文档中，指定对可以添加的元素，做出哪些限制。
*
*
* @param e element to be appended to this list
* @return true (as specified by {@link Collection#add})
* @throws UnsupportedOperationException if the add operation
* is not supported by this list
* @throws ClassCastException if the class of the specified element
* prevents it from being added to this list
* @throws NullPointerException if the specified element is null and this
* list does not permit null elements
* @throws IllegalArgumentException if some property of this element
* prevents it from being added to this list
*/
boolean add(E e);
/**
* 如果指定元素存在，从列表中移除指定元素（可选的操作）。
* 更正式地说，移除一个index最小的这样的元素（如果这样的元素存在） ，
* (o==null ? get(i)==null : o.equals(get(i)))
* 如果列表包含指定元素，返回true。（如果列表因为调用而改变，返回true）
*
* @param o element to be removed from this list, if present
* @return true if this list contained the specified element
* @throws ClassCastException if the type of the specified element
* is incompatible with this list
* (optional)
* @throws NullPointerException if the specified element is null and this
* list does not permit null elements
* (optional)
* @throws UnsupportedOperationException if the remove operation
* is not supported by this list
*/
boolean remove(Object o);
批量修改操作-containsAll,addAll,removeAll,retainAll,replaceAll,sort,clear
增加了一个addAll的重载方法，增加了replaceAll和sort两个默认方法
/**
* 如果列表包含指定列表中所有的元素，返回true
*
* @param c collection to be checked for containment in this list
* @return true if this list contains all of the elements of the
* specified collection
* @throws ClassCastException if the types of one or more elements
* in the specified collection are incompatible with this
* list
* (optional)
* @throws NullPointerException if the specified collection contains one
* or more null elements and this list does not permit null
* elements
* (optional),
* or if the specified collection is null
* @see #contains(Object)
*/
boolean containsAll(Collection c);
/**
* 将指定列表的所有元素加入到这个列表的最后，顺序为指定列表的迭代器的返回顺序（可选操作）。
* 当执行操作时，如果修改指定列表，操作的结果未知。
* （这意味着，如果如果指定列表是这个列表，而且列表是非空的，调用的结果未知）
*
* @param c collection containing elements to be added to this list
* @return true if this list changed as a result of the call
* @throws UnsupportedOperationException if the addAll operation
* is not supported by this list
* @throws ClassCastException if the class of an element of the specified
* collection prevents it from being added to this list
* @throws NullPointerException if the specified collection contains one
* or more null elements and this list does not permit null
* elements, or if the specified collection is null
* @throws IllegalArgumentException if some property of an element of the
* specified collection prevents it from being added to this list
* @see #add(Object)
*/
boolean addAll(Collection c);
/**
* 将指定列表的所有元素加入到这个列表的指定位置，（可选操作）。
* 在这个位置的元素（如果有）和任何这个元素右边的元素，被移动到右边（增加它们的index）
* 新的元素出现的顺序为指定列表的迭代器的返回顺序。
* 当执行操作时，如果修改指定列表，操作的结果未知。
* （这意味着，如果如果指定列表是这个列表，而且列表是非空的，调用的结果未知）
*
* @param index index at which to insert the first element from the
* specified collection
* @param c collection containing elements to be added to this list
* @return true if this list changed as a result of the call
* @throws UnsupportedOperationException if the addAll operation
* is not supported by this list
* @throws ClassCastException if the class of an element of the specified
* collection prevents it from being added to this list
* @throws NullPointerException if the specified collection contains one
* or more null elements and this list does not permit null
* elements, or if the specified collection is null
* @throws IllegalArgumentException if some property of an element of the
* specified collection prevents it from being added to this list
* @throws IndexOutOfBoundsException if the index is out of range
* (index < 0 || index > size())
*/
boolean addAll(int index, Collection c);
/**
* 删除这个列表中，所有已经包含在指定列表的元素（可选操作）。
*
* @param c collection containing elements to be removed from this list
* @return true if this list changed as a result of the call
* @throws UnsupportedOperationException if the removeAll operation
* is not supported by this list
* @throws ClassCastException if the class of an element of this list
* is incompatible with the specified collection
* (optional)
* @throws NullPointerException if this list contains a null element and the
* specified collection does not permit null elements
* (optional),
* or if the specified collection is null
* @see #remove(Object)
* @see #contains(Object)
*/
boolean removeAll(Collection c);
/**
* 列表中只保留指定列表包含的元素。（可选操作）。
* 换言而之，列表中移除所有不被指定列表包含的元素。
*
* @param c collection containing elements to be retained in this list
* @return true if this list changed as a result of the call
* @throws UnsupportedOperationException if the retainAll operation
* is not supported by this list
* @throws ClassCastException if the class of an element of this list
* is incompatible with the specified collection
* (optional)
* @throws NullPointerException if this list contains a null element and the
* specified collection does not permit null elements
* (optional),
* or if the specified collection is null
* @see #remove(Object)
* @see #contains(Object)
*/
boolean retainAll(Collection c);
/**
* 用operator的返回的结果替代列表中的每个元素=.
* operator抛出的异常或者运行时异常会传递给调用者。
*
* 默认实现与下面相同：
* {@code
* final ListIterator li = list.listIterator();
* while (li.hasNext()) {
* li.set(operator.apply(li.next()));
* }
* }
*
* 如果list的ListIterator不支持set操作，当替代第一个元素时，会抛出UnsupportedOperationException
*
* @param operator the operator to apply to each element
* @throws UnsupportedOperationException if this list is unmodifiable.
* Implementations may throw this exception if an element
* cannot be replaced or if, in general, modification is not
* supported
* @throws NullPointerException if the specified operator is null or
* if the operator result is a null value and this list does
* not permit null elements
* (optional)
* @since 1.8
*/
default void replaceAll(UnaryOperator operator) {
Objects.requireNonNull(operator);
//用ListIterator
final ListIterator li = this.listIterator();
while (li.hasNext()) {
//逐个set，operator返回的结果，operator以next的结果为参数
li.set(operator.apply(li.next()));
}
}
/**
* 以指定的comparator产生的排序，排序列表。
*
*
列表中所有的元素必须是能使用指定comparator相互比较，
* 即c.compare(e1, e2)必须不能抛出ClassCastException，对于任何列表中的e1和e2
*
*
如果指定的comparator是null，而且列表中所有的元素实现comparable接口，
* 应该使用元素的自然排序
*
*
列表必须是可修改的，不一定需要时可变大小的。
*
*
默认实现获取一个包含列表中所有元素的数组，排序数组，
* 遍历列表，根据数组的对应位置重新设置每个元素。
* （这避免了对链表进行排序的(n ^ 2) * log(n)的性能
*
*
这个实现是一个稳定的，自适应性的，迭代性的合并排序，
* 当输入数组被部分排序时，需要比n lg(n)很少的比较次数。
* 当输入数组是随机排序时，提供了传统合并排序的性能。
* 如果数组数组近乎排序完成，实现需要将近n次比较。
* 临时存储的需求从一个小的常量（对于近乎排序完成的数组）到n/2的对象引用（对于随机排序的数组）
*
*
实现对输入数组的递增排序和递减排序有相同的优势，
* 并且可以对一个输入数组的不同部分进行升序和降序排序。
* 它非常适用于合并两个或者多个排序过的数组：只需要将数组连接起来，然后排序结果数组。
*
*
该实现改编自Tim Peters的Python列表排序(TimSort)。
* 它使用了来自Peter McIlroy的“乐观排序和信息理论复杂性”的技术，
* 在第四届ACM-SIAM离散算法研讨会论文集中，467-474页，1993年1月。
*
*
* @param c the {@code Comparator} used to compare list elements.
* A {@code null} value indicates that the elements'
* {@linkplain Comparable natural ordering} should be used
* @throws ClassCastException if the list contains elements that are not
* mutually comparable using the specified comparator
* @throws UnsupportedOperationException if the list's list-iterator does
* not support the {@code set} operation
* @throws IllegalArgumentException
* (optional)
* if the comparator is found to violate the {@link Comparator}
* contract
* @since 1.8
*/
@SuppressWarnings({"unchecked", "rawtypes"})
default void sort(Comparator c) {
//自己变成一个数组
Object[] a = this.toArray();
//对数组排序
Arrays.sort(a, (Comparator) c);
ListIterator i = this.listIterator();
for (Object e : a) {
//ListIterator的每个位置set数组中的元素
i.next();
i.set((E) e);
}
}
/**
* 移除列表中所有的元素（可选操作）。这个方法返回后，列表为空。
*
* @throws UnsupportedOperationException if the clear operation
* is not supported by this list
*/
void clear();
比较和哈希-equals,hashCode
与Collection相同
/**
* 将指定对象与这个列表进行相等性的比较。
* 返回true，当且仅当指定对象也是一个list，两个list有相同的大小，
* 列表中所有对应对的元素都相同。（两个元素e1和e2是相等的，如果(e1==null ? e2==null :e1.equals(e2))。
* 换言而之，两个列表被定义为相等的，如果它们包含有相同顺序的相同元素。
* 这个定义保证equals方法在比较两个List接口的不同实现时，工作正常。
*
*
*
* @param o the object to be compared for equality with this list
* @return true if the specified object is equal to this list
*/
boolean equals(Object o);
/**
* 返回列表的hashcode。列表的hashcode根据下面计算方式得到
*
{@code
* int hashCode = 1;
* for (E e : list)
* //类似于字符串的方式，根据列表中每个元素的hashcode得到最终结果
* hashCode = 31*hashCode + (e==null ? 0 : e.hashCode());
* }
*
* 这保证list1.equals(list2)隐含着对于两个列表list1和list2，
* list1.hashCode()==list2.hashCode()
* 符合通常hashcode方法的约定。
*
* @return the hash code value for this list
* @see Object#equals(Object)
* @see #equals(Object)
*/
int hashCode();位置访问操作-get,set,add,remove
增加了get和set方法，增加了add和remove的重载方法
/**
* 返回列表中指定位置的元素。
* index范围[0,size()-1]
*
* @param index index of the element to return
* @return the element at the specified position in this list
* @throws IndexOutOfBoundsException 如果index超过范围 (index < 0 || index >= size())
*/
E get(int index);
/**
* Replaces the element at the specified position in this list with the
* specified element (optional operation).
*
* 用指定元素替代列表中指定位置的元素（可选操作）
*
* @param index index of the element to replace
* @param element element to be stored at the specified position
* @return the element previously at the specified position
* @throws UnsupportedOperationException if the set operation
* is not supported by this list
* @throws ClassCastException if the class of the specified element
* prevents it from being added to this list
* @throws NullPointerException if the specified element is null and
* this list does not permit null elements
* @throws IllegalArgumentException if some property of the specified
* element prevents it from being added to this list
* @throws IndexOutOfBoundsException if the index is out of range
* (index < 0 || index >= size())
*/
E set(int index, E element);
/**
* 插入指定元素到列表的指定位置。）可选操作）
* 在这个位置的元素（如果有）和任何后边的元素被移动到右边（将它们的index+1）
*
* @param index index at which the specified element is to be inserted
* @param element element to be inserted
* @throws UnsupportedOperationException if the add operation
* is not supported by this list
* @throws ClassCastException if the class of the specified element
* prevents it from being added to this list
* @throws NullPointerException if the specified element is null and
* this list does not permit null elements
* @throws IllegalArgumentException if some property of the specified
* element prevents it from being added to this list
* @throws IndexOutOfBoundsException if the index is out of range
* (index < 0 || index > size())
*/
void add(int index, E element);
/**
* 删除列表中指定位置的元素（可选操作）
* 移动后面的元素到左边（index-1）。
* 返回被移除的元素。
*
* @param index the index of the element to be removed
* @return the element previously at the specified position
* @throws UnsupportedOperationException if the remove operation
* is not supported by this list
* @throws IndexOutOfBoundsException if the index is out of range
* (index < 0 || index >= size())
*/
E remove(int index);查询操作-indexOf,lastIndexOf
两个操作都是新增的
/**
* 返回列表中第一次出现指定元素的位置，或者如果列表中不包含这个元素，返回-1。
* 更正式地，返回最小的index i，
* (o==null ? get(i)==null : o.equals(get(i))),
* 或者如果没有这样的index，返回-1
*
* @param o element to search for
* @return the index of the first occurrence of the specified element in
* this list, or -1 if this list does not contain the element
* @throws ClassCastException if the type of the specified element
* is incompatible with this list
* (optional)
* @throws NullPointerException if the specified element is null and this
* list does not permit null elements
* (optional)
*/
int indexOf(Object o);
/**
* 返回列表中最后一次出现指定元素的位置，或者如果列表中不包含这个元素，返回-1。
* 更正式地，返回最大的index i，
* (o==null ? get(i)==null : o.equals(get(i))),
* 或者如果没有这样的index，返回-1
*
* @param o element to search for
* @return the index of the last occurrence of the specified element in
* this list, or -1 if this list does not contain the element
* @throws ClassCastException if the type of the specified element
* is incompatible with this list
* (optional)
* @throws NullPointerException if the specified element is null and this
* list does not permit null elements
* (optional)
*/
int lastIndexOf(Object o);ListIterator-两个重载方法
两个方法都是新增的
/**
* 返回一个覆盖列表中元素的ListIterator（以适当的顺序）
*
* @return a list iterator over the elements in this list (in proper
* sequence)
*/
ListIterator listIterator();
/**
* 返回一个覆盖列表中元素的ListIterator（以适当的顺序），
* 以列表中指定位置开始。
* 指定位置的元素是第一次调用ListIterator的next方法返回的元素。
* 一次调用ListIterator的previous方法返回的元素是指定index-1对应的元素。
*
* @param index index of the first element to be returned from the
* list iterator (by a call to {@link ListIterator#next next})
* @return a list iterator over the elements in this list (in proper
* sequence), starting at the specified position in the list
* @throws IndexOutOfBoundsException if the index is out of range
* ({@code index < 0 || index > size()})
*/
ListIterator listIterator(int index); 查看-subList,spliterator
新增subList方法，spliterator重新被default默认方法覆盖了
/**
* 返回list一部分的视图，从指定的fromIndex（包含）到toIndex（不包含）。
* （如果fromIndex和toIndex相等，返回的list为空）
* 返回的列表有该列表支持，所以返回的列表的非结构性的改变会反映在这个列表中，反之亦然。
* 返回的列表支持所有由这个列表支持的可选list操作。
*
*
这个方法不需要显示的范围操作（数组中常见的那种）。
* 任何需要列表用作范围操作的操作，都可以传入一个subList视图，而不是一整个列表。
* 例如：从列表中删除一个范围的元素：
*
*
{@code
* list.subList(from, to).clear();
* }
*
*
* 可以用indexOf和lastIndexOf来构造类似的习语，
* 所有Collections的语法能适用于一个subList
*
*
如果支持的列表被结构性的改变了，而不是通过返回的列表改变，返回的列表的语义未知。
* （结构性的改变是改变这个列表的大小或者以一种正则进行的迭代的方式扰乱列表）
*
* @param fromIndex low endpoint (inclusive) of the subList
* @param toIndex high endpoint (exclusive) of the subList
* @return a view of the specified range within this list
* @throws IndexOutOfBoundsException for an illegal endpoint index value
* (fromIndex < 0 || toIndex > size ||
* fromIndex > toIndex)
*/
List subList(int fromIndex, int toIndex);
/**
* 创建一个覆盖列表元素的spliterator
*
* spliterator是SIZED和ORDERED的。实现应该报告额外的特质。
*
* 默认实现创建了一个迟绑定的spliterator，根据列表的Iterator。
* spliterator继承了列表的Iterator的快速失败属性。
*
* 默认实现的spliterator额外报告了SUBSIZED
*
* @return a {@code Spliterator} over the elements in this list
* @since 1.8
*/
@Override
default Spliterator spliterator() {
return Spliterators.spliterator(this, Spliterator.ORDERED);
}