List 接口 | 易学教程

与 Collection 源码比较

List 接口继承自 Collection 接口，从源码来分析List 的定义和两者提供的方法有什么区别。
/**
 * 有序集合，也称为序列。平时就叫列表。
 * 该接口的用户可以精确控制列表中每个元素的插入位置。
 * 用户可以通过其整数索引（列表中的位置）访问元素，并在列表中搜索元素。
 */
public interface List<E> extends Collection<E> {
    // Query Operations

    /**
     * 返回此列表中的元素个数。
     * 如果大于 Integer.MAX_VALUE 就返回 Integer.MAX_VALUE 
     * 和 Collection 没区别
     */
    int size();

    /**
     * 如果此列表不包含任何元素就返回 true
     * 和 Collection 没区别
     */
    boolean isEmpty();

    /**
     * 如果此列表包含指定的元素就返回 true
     * 通常，当且仅当至少包含一个元素 e 满足 (o==null ? e==null: o.equals(e)) 返回 true
     * @throws ClassCastException 如果指定元素的类型与此列表不兼容就抛出此异常
     * @throws NullPointerException 如果指定的元素是 null且此列表不允许有 null 就抛出此异常
     * 和 Collection 没区别
     */
    boolean contains(Object o);

    /**
     * 以适当的顺序返回对该列表中的元素的迭代器。
     * 和 Collection 比较，列表有返回顺序的保证
     * 
     */
    Iterator<E> iterator();

    /**
     * 以适当的顺序（从第一个元素到最后一个元素）返回一个包含此列表中所有元素的数组。
     *
     * <p>The returned array will be "safe" in that no references to it are
     * maintained by this list.  (In other words, this method must
     * allocate a new array even if this list is backed by an array).
     * The caller is thus free to modify the returned array.//一句话，返回的数组可以自由修改
     * <p>此方法充当基于数组的API和基于集合的API之间的桥梁。
     * @see Arrays#asList(Object[])
     * 和 Collection 比较，遵循了和迭代器顺序一致的约定
     */
    Object[] toArray();

    /**
     * 以适当的顺序（从第一个元素到最后一个元素）返回包含此列表中所有元素的数组；返回数组的运行时类型是指定数组的运行时类型。
     * 如果列表适合指定的数组，则将其返回。否则，将使用指定数组的运行时类型和此列表的大小分配一个新数组。
     *
     * <p>如果列表适合指定的数组并有剩余空间，则紧跟列表末尾的数组中的元素设置为 null
     * 如果调用者知道列表不包含任何null元素，则这对于确定列表的长度很有用。
     *
     * <p>此方法充当基于数组的API和基于集合的API之间的桥梁。
     * 此外，此方法允许对输出数组的运行时类型进行精确控制，并且在某些情况下可以用于节省分配成本。
     *
     * <p>假设 x 是一个仅包含字符串的列表，以下代码可用于将列表转储到新分配的 String 数组中：
     * <pre>{@code
     *     String[] y = x.toArray(new String[0]);
     * }</pre>
     * 请注意，toArray(new Object [0])在功能上与 toArray() 相同。
     *
     * @param a 该列表的元素要存储到的数组（如果足够大）；否则，将为此分配一个具有相同运行时类型的新数组。
     * @return an array containing the elements of this list
     * @throws ArrayStoreException 如果指定数组的运行时类型不是此列表中每个元素的运行时类型的超类型
     * @throws NullPointerException 如果指定的数组为null，就抛出此异常
     * 和 Collection 比较，遵循了和迭代器顺序一致的约定
     */
    <T> T[] toArray(T[] a);


    // Modification Operations

    /**
     * 将指定的元素追加到此列表的末尾（可选操作）。
     *
     * <p>支持此操作的列表可能会限制可以添加到此列表的元素。
     * 特别是，某些列表将拒绝添加 null 元素，而另一些列表将对可能添加的元素类型施加限制。
     * 列表类应在其文档中明确指定对可以添加哪些元素的任何限制。
     *
     * @param e element to be appended to this list
     * @return <tt>true</tt> (as specified by {@link Collection#add})
     * @throws UnsupportedOperationException 如果此列表不支持该操作，就抛出此异常
     * @throws ClassCastException 如果指定元素的类阻止将其添加到此集列表中，就抛出此异常
     * @throws NullPointerException 如果指定的元素为null，并且此列表不允许使用null元素，就抛出此异常
     * @throws IllegalArgumentException 如果元素的某些属性阻止将其添加到此列表中，就抛出此异常
     * 和 Collection 比较，约定元素是在末尾追加，少了一个抛异常情况
     */
    boolean add(E e);

    /**
     * 如果存在，从此列表中删除第一次出现的指定元素（可选操作）
     * 如果此列表不包含该元素，则它保持不变。
     * 更正式的，如果元素存在，删除最小下标 i 对应的元素，i满足如下表达式
     * (o==null ? get(i)==null : o.equals(get(i))) 
     * 如果列表包含指定元素（或者方法调用导致列表改变），就返回 true
     *
     * @throws ClassCastException 如果指定元素的类型与此列表不兼容，抛出此异常
     * (<a href="Collection.html#optional-restrictions">optional</a>)
     * @throws NullPointerException 如果指定的元素为null，并且此列表不允许为null，抛出此异常
     * (<a href="Collection.html#optional-restrictions">optional</a>)
     * @throws UnsupportedOperationException 如果此列表不支持该操作，抛出此异常
     *  和 Collection 比较，约定删除第一次出现（最小下标）的元素
     */
    boolean remove(Object o);


    // Bulk Modification Operations

    /**
     * 如果此列表包含指定集合的所有元素，则返回 true。
     *
     * @param  c collection to be checked for containment in this list
     * @return <tt>true</tt> if this list contains all of the elements of the
     *         specified collection
     * @throws ClassCastException 如果指定集合中一个或多个元素的类型与此列表不兼容
     * (<a href="Collection.html#optional-restrictions">optional</a>)
     * @throws NullPointerException 如果指定的集合包含一个或多个null元素，并且此列表不允许null元素；
     *       或者指定的集合为null
     *    和 Collection 比较，没区别
     * @see #contains(Object)
     */
    boolean containsAll(Collection<?> c);

    /**
     * 将指定集合中的所有元素按指定集合的迭代器返回的顺序追加到此列表的末尾（可选操作）。
     * 如果在操作进行过程中修改了指定的集合，则此操作的行为是不确定的。
     * (请注意，如果指定的集合是此列表且非空，则会发生这种情况。)
     *
     * @param c collection containing elements to be added to this list
     * @return <tt>true</tt> 列表因调用而改变
     * @throws UnsupportedOperationException 如果此列表不支持该操作
     * @throws ClassCastException 如果指定集合的元素的类阻止将其添加到此列表中
     * @throws NullPointerException 如果指定的集合包含一个或多个null元素，
     *    并且此列表不允许使用null元素，或者指定的collection为null
     * @throws IllegalArgumentException 如果指定集合的元素的某些属性阻止将其添加到此列表中
     * 和 Collection 比较，元素追加到此列表的末尾，少一个异常：IllegalStateException
     * @see #add(Object)
     */
    boolean addAll(Collection<? extends E> c);

    /**
     * 将指定集合中的所有元素插入此列表中的指定位置（可选操作）。
     * 将当前位于该位置的元素（如果有）和任何后续元素右移（增加其索引）
     * 新元素将按照指定集合的迭代器返回的顺序显示在此列表中。
     * 如果在操作进行过程中修改了指定的集合，则此操作的行为是不确定的。
     *  （请注意，如果指定的集合是此列表，并且是非空的，则将发生这种情况。）
     *
     * @param index 从指定集合插入第一个元素的索引
     * @param c collection containing elements to be added to this list
     * @return 如果此列表因调用而改变
     * @throws UnsupportedOperationException 此列表不支持该操作时
     * @throws ClassCastException 如果指定集合的元素的类阻止将其添加到此列表中
     * @throws NullPointerException 如果指定的集合包含一个或多个null元素，
     *         并且此列表不允许使用null元素，或者指定的collection为null
     * @throws IllegalArgumentException 如果指定集合的元素的某些属性阻止将其添加到此列表中
     * @throws IndexOutOfBoundsException 如果索引超出范围
     *  和 Collection 比较，多了一种重载形式，可以指定插入的位置
     */
    boolean addAll(int index, Collection<? extends E> c);

    /**
     * 从此列表中删除指定集合中包含的所有其元素（可选操作）。
     * 和 Collection 比较，没区别
     * @param c collection containing elements to be removed from this list
     * @return <tt>true</tt> if this list changed as a result of the call
     * @throws UnsupportedOperationException if the <tt>removeAll</tt> operation
     *         is not supported by this list
     * @throws ClassCastException if the class of an element of this list
     *         is incompatible with the specified collection
     * (<a href="Collection.html#optional-restrictions">optional</a>)
     * @throws NullPointerException if this list contains a null element and the
     *         specified collection does not permit null elements
     *         (<a href="Collection.html#optional-restrictions">optional</a>),
     *         or if the specified collection is null
     * @see #remove(Object)
     * @see #contains(Object)
     */
    boolean removeAll(Collection<?> c);

    /**
     * 仅保留此列表中指定集合中包含的元素（可选操作）
     * 换句话说，从该列表中删除所有未包含在指定集合中的元素。
     * 和 Collection 比较，没区别
     * @param c collection containing elements to be retained in this list
     * @return <tt>true</tt> if this list changed as a result of the call
     * @throws UnsupportedOperationException if the <tt>retainAll</tt> operation
     *         is not supported by this list
     * @throws ClassCastException if the class of an element of this list
     *         is incompatible with the specified collection
     * (<a href="Collection.html#optional-restrictions">optional</a>)
     * @throws NullPointerException if this list contains a null element and the
     *         specified collection does not permit null elements
     *         (<a href="Collection.html#optional-restrictions">optional</a>),
     *         or if the specified collection is null
     * @see #remove(Object)
     * @see #contains(Object)
     */
    boolean retainAll(Collection<?> c);


    /**
     * 从此列表中删除所有元素（可选操作）。 该调用返回后，该列表将为空。
     * 和 Collection 比较，没区别
     * @throws UnsupportedOperationException if the <tt>clear</tt> operation
     *         is not supported by this list
     */
    void clear();


    // Comparison and hashing

    /**
     * 比较指定对象与此列表是否相等。 
     * 当且仅当指定对象也是一个列表时，两个列表的大小相同，
     * 并且两个列表中所有对应的元素对都是 equal，返回 true
     * 换句话说，如果两个列表包含相同顺序的相同元素，则定义为相等。 
     * 此定义确保equals方法可在<tt> List </ tt>接口的不同实现中正常工作。
     * 和 Collection 比较，此处是按照约定指定比较对象必须是列表
     * @param o the object to be compared for equality with this list
     * @return <tt>true</tt> if the specified object is equal to this list
     */
    boolean equals(Object o);

    /**
     * 返回此列表的哈希码值。  
     * 列表的哈希码定义为以下计算的结果：
     * <pre>{@code
     *     int hashCode = 1;
     *     for (E e : list)
     *         hashCode = 31*hashCode + (e==null ? 0 : e.hashCode());
     * }</pre>
     * This ensures that <tt>list1.equals(list2)</tt> implies that
     * <tt>list1.hashCode()==list2.hashCode()</tt> for any two lists,
     * <tt>list1</tt> and <tt>list2</tt>, as required by the general
     * contract of {@link Object#hashCode}.
     * 保证实现了list1.hashCode()==list2.hashCode() 的任意两个列表list1 和 list2满足 list1.equals(list2)
     * @return the hash code value for this list
     * 和 Collection 比较，此处是按照约定哈希码值相等的两个列表 eauql
     * @see Object#equals(Object)
     * @see #equals(Object)
     */
    int hashCode();


    // Positional Access Operations  位置访问操作，Collection 接口没有

    /**
     * 返回此列表中指定位置的元素。
     *
     * @param index index of the element to return
     * @return the element at the specified position in this list
     * @throws IndexOutOfBoundsException 如果索引超出范围
     *         (<tt>index &lt; 0 || index &gt;= size()</tt>)
     */
    E get(int index);

    /**
     * 用指定的元素替换此列表中指定位置的元素（可选操作），返回之前的元素。
     *
     * @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 <tt>set</tt> 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
     *         (<tt>index &lt; 0 || index &gt;= size()</tt>)
     */
    E set(int index, E element);

    /**
     * 将指定的元素插入此列表中的指定位置（可选操作）。 
     * 将当前在该位置的元素（如果有）和任何后续元素右移（将其下标加 1）。
     * @param index index at which the specified element is to be inserted
     * @param element element to be inserted
     * @throws UnsupportedOperationException if the <tt>add</tt> 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
     *         (<tt>index &lt; 0 || index &gt; size()</tt>)
     */
    void add(int index, E element);

    /**
     * 删除此列表中指定位置的元素（可选操作）。 
     * 将所有后续元素向左移动（下标减 1）。 返回从列表中删除的元素。
     * @param index the index of the element to be removed
     * @return the element previously at the specified position
     * @throws UnsupportedOperationException if the <tt>remove</tt> operation
     *         is not supported by this list
     * @throws IndexOutOfBoundsException if the index is out of range
     *         (<tt>index &lt; 0 || index &gt;= size()</tt>)
     */
    E remove(int index);


    // Search Operations  搜索操作

    /**
     * 返回指定元素在此列表中首次出现的索引；如果此列表不包含该元素，则返回-1。
     * More formally, returns the lowest index <tt>i</tt> such that
     * <tt>(o==null&nbsp;?&nbsp;get(i)==null&nbsp;:&nbsp;o.equals(get(i)))</tt>,
     * or -1 if there is no such index.
     *
     * @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
     *         (<a href="Collection.html#optional-restrictions">optional</a>)
     * @throws NullPointerException if the specified element is null and this
     *         list does not permit null elements
     *         (<a href="Collection.html#optional-restrictions">optional</a>)
     */
    int indexOf(Object o);

    /**
     * 返回指定元素在此列表中最后一次出现的索引；如果此列表不包含该元素，则返回-1。
     * More formally, returns the highest index <tt>i</tt> such that
     * <tt>(o==null&nbsp;?&nbsp;get(i)==null&nbsp;:&nbsp;o.equals(get(i)))</tt>,
     * or -1 if there is no such index.
     *
     * @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
     *         (<a href="Collection.html#optional-restrictions">optional</a>)
     * @throws NullPointerException if the specified element is null and this
     *         list does not permit null elements
     *         (<a href="Collection.html#optional-restrictions">optional</a>)
     */
    int lastIndexOf(Object o);


    // List Iterators   列表迭代器

    /**
     * 返回此列表中的元素的列表迭代器（按适当顺序）。
     *
     * @return a list iterator over the elements in this list (in proper
     *         sequence)
     */
    ListIterator<E> listIterator();

    /**
     * 从列表中的指定位置开始，以适当的顺序返回在此列表中的元素的列表迭代器。
     * 指定的索引指示初始调用{@link ListIterator＃next next}将返回的第一个元素。
     * 初次调用{@link ListIterator＃previous previous}将返回具有指定索引减一的元素。
     *
     * @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<E> listIterator(int index);

    // View   视图

    /**
     * 返回此列表在指定的<tt> fromIndex </ tt>（包括）和<tt> toIndex </ tt>（不包括）之间的视图。 
     *（如果<tt> fromIndex </ tt>和<tt> toIndex </ tt>相等，则返回列表为空。）
     * 返回列表由该列表支持，因此返回列表中的非结构性更改将反映在此列表，反之亦然。 
     * 返回的列表支持此列表支持的所有可选列表操作。
     *
     * 此方法消除了对显式范围操作（数组通常存在的那种范围）的需要。
     * 通过传递subList视图而不是整个列表，可以将期望列表的任何操作用作范围操作。
     * 例如，以下语法从列表中删除了一系列元素：
     * <pre>{@code
     *      list.subList(from, to).clear();
     * }</pre>
     * 可以为<tt> indexOf </ tt>和<tt> lastIndexOf </ tt>构建类似的习惯用法，
     * 并且<tt> Collections </ tt>类中的所有算法都可以应用于子列表。<p>
     *
     * 如果后备列表（即此列表）以除通过返回列表以外的任何其他方式进行<i>结构修改</ i>，
     * 则此方法返回的列表的语义将变得不确定。
     * （结构修改是指更改此列表的大小的结构修改，或者以其他方式干扰此列表的方式，
     * 即正在进行的迭代可能会产生错误的结果。）
     * @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
     *         (<tt>fromIndex &lt; 0 || toIndex &gt; size ||
     *         fromIndex &gt; toIndex</tt>)
     */
    List<E> subList(int fromIndex, int toIndex);

}
List 的整体了解

1. 简介
从接口注释可知：List 是有序集合，也称为序列。平时就叫列表。使用者可以精确控制列表中每个元素的插入位置。用户可以通过其整数索引（列表中的位置）访问元素，并在列表中搜索元素。
2. 方法
查询操作：size()，isEmpty()，contains(Object o)，iterator()，toArray()；
修改操作：add(E e)，remove(Object o)，addAll(Collection<? extends E> c)，removeAll(Collection<?> c)，retainAll(Collection<?> c)，clear()；
比较和哈希：equals(Object o)，hashCode()；
位置访问：get(int index)，set(int index, E element)，add(int index, E element)，remove(int index)；
搜索操作：indexOf(Object o)，lastIndexOf(Object o)；
列表迭代器：listIterator()，listIterator(int index)；
视图操作：subList(int fromIndex, int toIndex)；
来源：oschina
链接：https://my.oschina.net/u/3488841/blog/4278287
标签
element
optional
Amp