集合之List-API(源码注释中英文对照翻译解释)

来源：JDK 1.8 lib

public interface List<E> extends Collection<E> {
   
	/**
	* 
	* Returns the number of elements in this list.  If this list contains
     * more than <tt>Integer.MAX_VALUE</tt> elements, returns
     * <tt>Integer.MAX_VALUE</tt>.
     *
     * 返回该list的element数目。
     * 如果该list包含元素数<tt>Integer.MAX_VALUE</tt> ，那返回 <tt>Integer.MAX_VALUE</tt>
	*
	*/
    int size()；
    
     /**
     * Returns <tt>true</tt> if this list contains no elements.
     * 当list为空集合时，返回true
     *
     * @return <tt>true</tt> if this list contains no elements
     */
    boolean isEmpty();
    /**
     * Returns <tt>true</tt> if this list contains the specified element.
     * More formally, returns <tt>true</tt> if and only if this list contains
     * at least one element <tt>e</tt> such that
     * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>.
     * 当该list不为空（至少包含一个元素且不为null时，设为e）且包含o（或者o与e 相同）时，则返回true。
     *
     * @param o element whose presence in this list is to be tested
     * @return <tt>true</tt> if this list contains the specified 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>)
     */
    boolean contains(Object o);
     /**
     * Returns an iterator over the elements in this list in proper sequence.
     * 返回一个能够以合适顺序返回此队列元素的iterator（迭代器）
     * @return an iterator over the elements in this list in proper sequence
     */
    Iterator<E> iterator();
    /**
     * Returns an array containing all of the elements in this list in proper
     * sequence (from first to last element).
     *
     * <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>This method acts as bridge between array-based and collection-based
     * APIs.
     *
     
     * 以一个合适的方式返回一个包含本队列中所有元素的队列。（从第一个元素到最后一个）
     * 这个返回的 <tt>array</tt> 将会是"安全"的,因为它将会是一个全新的引用。也就是说调用者可以随意自由的修改返回的 <tt>array</tt>。
     * 本方法相当于是 <tt>array</tt> 和 <tt>collection</tt> 的桥梁
     
     * @return an array containing all of the elements in this list in proper
     *         sequence
     * @see Arrays#asList(Object[])
     */
    Object[] toArray();
    
     /**
     * Returns an array containing all of the elements in this list in
     * proper sequence (from first to last element); the runtime type of
     * the returned array is that of the specified array.  If the list fits
     * in the specified array, it is returned therein.  Otherwise, a new
     * array is allocated with the runtime type of the specified array and
     * the size of this list.
     *
     * 返回数组的运行时类型是指定数组的运行时类型。 如果列表适合指定的数组，则返回其中。 否则，将为新数组分配指定数组的运行时类型和此列表的大小。
     *
     * <p>If the list fits in the specified array with room to spare (i.e.,
     * the array has more elements than the list), the element in the array
     * immediately following the end of the list is set to <tt>null</tt>.
     
     * 如果列表适合指定的数组并且有空余空间（即，数组的元素多于列表），则紧跟在列表末尾之后的数组中的元素将设置为<tt> null </ tt>
     
     * (This is useful in determining the length of the list <i>only</i> if
     * the caller knows that the list does not contain any null elements.)
     *
     * <p>Like the {@link #toArray()} method, this method acts as bridge between
     * array-based and collection-based APIs.  Further, this method allows
     * precise control over the runtime type of the output array, and may,
     * under certain circumstances, be used to save allocation costs.
     *
     * 该方法不仅限于作为array和collection之间的桥梁。同时它还可以在运行时精确控制类型。并且在某些情况下节省分配成本。 
     *
     * <p>Suppose <tt>x</tt> is a list known to contain only strings.
     * The following code can be used to dump the list into a newly
     * allocated array of <tt>String</tt>:
     *
     * <pre>{@code
     *     String[] y = x.toArray(new String[0]);
     * }</pre>
     * 
     * 假使 x 是一个一直的只包含string 的list。 这段代码可以将该list载入一个全新的String[] 数组中。
     * 
     * Note that <tt>toArray(new Object[0])</tt> is identical in function to
     * <tt>toArray()</tt>.
     * 
     *
     * @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> T[] toArray(T[] a);
    
    /*-----------------------修改类型的方法--------------------*/
    
    /**
     * Appends the specified element to the end of this list (optional operation).
     * 将该元素(类型为E的e)保存到list中，且放在最后。
     * 
     * <p>Lists that support this operation may place limitations on what elements may be added to this list.  In particular, some
     * lists will refuse to add null elements, and others will impose restrictions on the type of elements that may be added.  List
     * classes should clearly specify in their documentation any restrictions on what elements may be added.
     *
     * 支持本方法的list实现类往往会对可add 的元素设限制。 有一个list拒绝add null，还有一些可能对add 的元素添加限制。列表类应在其文档中明确指出可以添加哪些元素的任何限制。
     *
     * @param e element to be appended to this list
     * @return <tt>true</tt> (as specified by {@link Collection#add})
     * @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 this element
     *         prevents it from being added to this list
     */<