java.util.List API解讀

list的API 以下：

下面是我對這段API的翻譯

An ordered collection (also known as a sequence).
一個有序的集合（也被稱爲序列）
The user of this interface has precise control over where in the list each element is inserted.
這個接口的 使用者對list中每一個元素的插入位置有着準確的控制。
The user can access elements by their integer index (position in the list), and search for elements in the list.
使用者能夠經過索引（Interger類型）來獲取元素，查找元素。

Unlike sets, lists typically allow duplicate elements.
和set不一樣，list容許重複元素。
More formally, lists typically allow pairs of elements e1 and e2 such that e1.equals(e2),
更正式的說法是，list容許e1.equals(e2),
and they typically allow multiple null elements if they allow null elements at all.
一樣，list中也容許存在null元素。 
It is not inconceivable that someone might wish to implement a list that prohibits duplicates, by throwing runtime exceptions when the user attempts to insert them, but we expect this usage to be rare.
固然，用戶能夠自定義list，使得這個list不接受null元素（元素是null就抱空指針錯誤或者作其餘處理）。

The List interface places additional stipulations,beyond those specified in the Collection interface, on the contracts of the iterator, add, remove, equals, and hashCode methods. 
Declarations for other inherited methods are also included here for convenience.
除了collection接口中明確須要繼承的方法（iterator,add,remove,equals,hashcode）以外，list接口還增長了其餘的接口，這些接口爲list的使用提供了便利。

The List interface provides four methods for positional (indexed) access to list elements.
list接口提供了四個方法來經過索引獲取元素。 
Lists (like Java arrays) are zero based.
list和java中的數組同樣是從零開始。
Note that these operations may execute in time proportional to the index value for some implementations (the LinkedList class, for example).
須要注意的是這些操做執行的時間可能跟index的值成比例（好比LinkedList ）
Thus, iterating over the elements in a list is typically preferable to indexing through it if the caller does not know the implementation.
所以，若是調用者不知道實現，則經過迭代列表中的元素一般優先於索引。
 

The List interface provides a special iterator, called a ListIterator,
list接口提供了一個特殊的迭代器，稱爲ListIterator. 
that allows element insertion and replacement, and bidirectional access in addition to the normal operations that the Iterator interface provides. 
這容許元素插入和替換，以及Iterator接口提供的常規操做以外的雙向訪問。
A method is provided to obtain a list iterator that starts at a specified position in the list.
從一個list中的特定位置開始的Iterator能夠經過list中提供的方法獲取。

The List interface provides two methods to search for a specified object.
list接口提供兩個方法來查找指定的對象。
From a performance standpoint, these methods should be used with caution.
爲了性能要求，這些方法必須使用警告。
In many implementations they will perform costly linear searches.
在不少實現中，他們都是很是耗時的線性查找。

The List interface provides two methods to efficiently insert and remove multiple elements at an arbitrary point in the list.
List接口提供了兩種方法，能夠在列表中的任意點高效地插入和刪除多個元素。

Note: While it is permissible for lists to contain themselves as elements, extreme caution is advised: the equals and hashCode methods are no longer well defined on such a list.
注意：儘管列表容許將其自身做爲元素，但建議您很是當心：equals和hashCode方法在這樣的列表中再也不被很好地定義。

Some list implementations have restrictions on the elements that they may contain.
有一些list的實如今它們可以包含的元素上有一些限制。
For example, some implementations prohibit null elements, and some have restrictions on the types of their elements.
好比，有些list不能有null元素，有些list的元素類型被限制。 
Attempting to add an ineligible element throws an unchecked exception, typically NullPointerException or ClassCastException.
嘗試將不符合要求的元素加入到list中會拋出異常，一般是空指針異常 或者 ClassCastException。
Attempting to query the presence of an ineligible element may throw an exception, or it may simply return false;
嘗試查詢一個不符合要求的元素
some implementations will exhibit the former behavior and some will exhibit the latter.
有些實現會禁止以前的行爲，有些則會禁止某些字母。
More generally, attempting an operation on an ineligible element whose completion would not result in the insertion of an ineligible element into the list may throw an exception or it may succeed, at the option of the implementation.
一般，嘗試操做不符合要求的元素將不會致使不符合要求的元素插入到隊列中，而是致使異常，固然也有可能成功，這取決於具體的實現。
Such exceptions are marked as "optional" in the specification for this interface.
在這個接口規範中這些異常被標註爲可選擇的。

This interface is a member of the Java Collections Framework.
這個接口是java集合框架中的一員。

總結一下，主要說了如下幾點：
一、list是一個有序的集合（也是被稱爲序列），和set不同，list中容許重複元素的存在。

二、list的使用者對元素的插入位置（索引）有着準確的控制，經過索引能夠獲取元素。

三、list提供了各類方法來方便咱們對其中的元素操做

四、list是java集合框架的一員

說得太籠統，具體仍是須要看API。

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

接口中定義的方法

    //返回list中的元素個數
    int size();        
    
    //判斷list中是否包含元素，若是不包含返回true
    boolean isEmpty();        
    
    //判斷list中是否包含某個特定的對象
    boolean contains(Object o);    
    
    //以正確的順序返回list中元素的迭代器    
    Iterator<E> iterator();
    
    //返回一個包含list中全部元素的數組，數組中元素的順序和list中的順序同樣
    //這個方法能夠當作array-based 和 collection-based API之間的橋樑
    Object[] toArray();        
    
    //返回一個包含list中全部元素的數組，數組中元素的順序和list中的順序同樣
    //array數組的類型是肯定的。若是指定的array大小不足，這個方法將會生成一個新的數組用於返回
    //新數組的類型和運行時的數組類型同樣
    <T> T[] toArray(T[] a);
    
    //在list的末尾插入元素（實現類能夠選擇插入的位置）
    boolean add(E e);
    
    //若是指定元素存在list中，移除list中第一次出現的指定元素（實現類能夠選擇具體的實現）
    boolean remove(Object o);
    
    //判斷list中是否包含某個集合
    boolean containsAll(Collection<?> c);
    
    //將指定集合中的全部元素加到list的末尾
    boolean addAll(Collection<? extends E> c);
    
    //在指定位置插入指定集合
    boolean addAll(int index, Collection<? extends E> c);
    
    //刪除list中包含的Collection中的全部元素
    boolean removeAll(Collection<?> c);
    
    //保留list中包含的Collection中的全部元素
    boolean retainAll(Collection<?> c);
    
    //將該列表的每一個元素替換爲將該運算符應用於該元素的結果。
    default void replaceAll(UnaryOperator<E> operator);
    
    //對list中的元素排列
    default void sort(Comparator<? super E> c);
    
    //刪除list中的全部元素
    void clear();
    
    boolean equals(Object o);
    
    int hashCode();
    
    //根據索引獲取list中的元素
    E get(int index);
    
    //用指定元素替換指定位置上的元素
    E set(int index, E element);
    
    //在指定位置上增長指定元素
    void add(int index, E element);
    
    //刪除指定索引上的元素
    E remove(int index);
    
    //獲取對象的第一個索引
    int indexOf(Object o);
    
    //獲取對象的最後一個索引
    int lastIndexOf(Object o);
    
    //返回list的list 迭代器
    ListIterator<E> listIterator();
    
    //從指定位置返回list的迭代器
    ListIterator<E> listIterator(int index);
    
    //返回list的子list
    List<E> subList(int fromIndex, int toIndex);
    
    //Creates a {@link Spliterator} over the elements in this list.
    default Spliterator<E> spliterator()