java.util.List翻译

java.util
Interface List

All Superinterfaces:

Collection

All Known Implementing Classes:

AbstractList, ArrayList, LinkedList, Vector

public interface List

extends Collection

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. The user can aclearcase/" target="_blank" >ccess elements by their integer index (position in the list), and search for elements in the list. 有序的集合（也被称为sequence）。该接口的用户可以精确控制列表元素插入的位置。 用户可以通过整数下标（列表中的位置）访问、查找列表中的元素。

Unlike sets, lists typically allow duplicate elements. More formally, lists typically allow pairs of elements e1 and e2 such that e1.equals(e2), and they typically allow multiple null elements if they allow null elements at all. 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. 和set不同，列表通常允许重复元素。也就是说，列表通常允许e1.equals(e2)这样的 元素对e1和e2，如果允许null元素的话，通常也允许重复的null元素。 如果有人希望实现list而当用户试图插入重复元素时抛出运行时异常来禁止重复，这是不可思议的， 我们希望这样的用法极少。

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. 对于iterator、add、remove、equals和hashCode方法，除了遵守Collection接口中指定的 以外，List接口还提供了额外的约定。按照惯例，还包括其他继承来的方法声明。

The List interface provides four methods for positional (indexed) access to list elements. Lists (like Java arrays) are zero based. Note that these operations may execute in time proportional to the index value for some implementations (the LinkedList class, for example). Thus, iterating over the elements in a list is typically preferable to indexing through it if the caller does not know the implementation. List接口提供了一些通过下标访问列表元素的四个可选方法。List和Java数组一样，是基于0的。 注意对于某些实现（比如LinkedList类）这些操作的执行时间和下标值成正比。 因此如果调用者不了解实现方式，通常应该遍历列表元素，这比指定下标位置更可取。

The List interface provides a special iterator, called a ListIterator, that allows element insertion and replacement, and bidirectional access in addition to the normal operations that the Iterator interface provides. A method is provided to obtain a list iterator that starts at a specified position in the list. List接口提供一个特殊的迭代器，叫做ListIterator，除了提供Iterator 接口的通常操作之外，还允许元素插入、替换和双向访问。提供了一个 获得从列表指定位置开始的列表迭代器。

The List interface provides two methods to search for a specified object. From a performance standpoint, these methods should be used with caution. In many implementations they will perform costly linear searches. List接口提供了两种方法来查找指定对象。从性能角度讲，这些方法应该谨慎使用。 在许多实现中，实行的是代价很高的线性查找。

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 a such a list. 注意：一旦列表允许以自身作为元素，那么equals和hashCode 方法在列表中的定义不再有效。

Some list implementations have restrictions on the elements that they may contain. For example, some implementations prohibit null elements, and some have restrictions on the types of their elements. Attempting to add an ineligible element throws an unchecked exception, typically NullPointerException or 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. 某些列表的实现可能对包含的元素有限制。例如，某些实现禁止null元素，某些对元素类型有限制。试图加入一个不适当的元素会抛出未检查异常，通常为NullPointerException 或ClassCastException。试图查询不适当的存在性也会抛出异常，或者简单返回false。某些实现禁止前者的行为，某些禁止后者。更一般地讲，试图操作一个不适当的元素，实现不会造成不适当元素插入列表而抛出异常或者成功，这取决于实现的选择。那样的异常在该接口规范中标记为“optional”。

This interface is a member of the Java Collections Framework. 该接口是Java集合框架成员之一。

Since:

1.2

See Also:

Collection, Set, ArrayList, LinkedList, Vector, Arrays.asList(Object[]), Collections.nCopies(int, Object), Collections.EMPTY_LIST, AbstractList, AbstractSequentialList

size

public int size()

Returns the number of elements in this list. If this list contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE. 返回列表元素的数目。如果列表所含元素数目大于Integer.MAX_VALUE，返回Integer.MAX_VALUE。

Specified by:

size in interface Collection

Returns:

the number of elements in this list. 列表元素的数目

isEmpty

public boolean isEmpty()

Returns true if this list contains no elements. 如果列表不含元素，返回true。

Specified by:

isEmpty in interface Collection

Returns:

true if this list contains no elements. 如果列表不含元素，返回true。

contains

public boolean contains(Object o)

Returns true if this list contains the specified element. More formally, returns true if and only if this list contains at least one element e such that (o==null ? e==null : o.equals(e)). 如果列表包含指定元素，返回true。正式表述为只有当列表包含至少一个元素e，使得(o==null ? e==null : o.equals(e))， 返回true。

Specified by:

contains in interface Collection

Parameters:

o - element whose presence in this list is to be tested. 测试列表中是否存在的元素。

Returns:

true if this list contains the specified element. 如果列表包含指定元素，返回true。

Throws:

ClassCastException - if the type of the specified element is incompatible with this list (optional). 如果指定元素的类型与列表不相容时抛出（可选）。

NullPointerException - if the specified element is null and this list does not support null elements (optional). 如果指定元素为null而列表不支持null元素时抛出（可选）。

iterator

public Iterator iterator()

Returns an iterator over the elements in this list in proper sequence. 以本来顺序返回列表元素的迭代器。

Specified by:

iterator in interface Collection

Returns:

an iterator over the elements in this list in proper sequence. 列表元素本来顺序的迭代器。

toArray

public Object[] toArray()

Returns an array containing all of the elements in this list in proper sequence. Obeys the general contract of the Collection.toArray method. 返回一个以本来顺序包含列表所有元素的数组。遵守Collection.toArray方法的一般约定。

Specified by:

toArray in interface Collection

Returns:

an array containing all of the elements in this list in proper sequence. 一个以本来顺序包含列表所有元素的数组。

See Also:

Arrays.asList(Object[])

toArray

public Object[] toArray(Object[] a)

Returns an array containing all of the elements in this list in proper sequence; the runtime type of the returned array is that of the specified array. Obeys the general contract of the Collection.toArray(Object[]) method. 返回一个以本来顺序包含列表所有元素的数组，返回数组的返回时类型为指定数组类型。 遵守Collection.toArray(Object[])方法的一般约定。

Specified by:

toArray in interface Collection

Parameters:

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. 存储列表元素的数组，如果它足够大的话；否则为此创建一个运行时类型相同的新数组。

Returns:

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. 如果a的运行时类型不是列表中每个元素运行时类型的父一级类型时抛出。

NullPointerException - if the specified array is null. 如果指定数组为null时抛出。

add

public boolean add(Object o)

Appends the specified element to the end of this list (optional operation). 向列表指定位置插入指定元素（可选操作）。

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. 支持该操作的列表可能对加入列表的元素有所限制。特别地，某些列表会拒绝加入 null元素，另一些会对加入元素的类型有所限制。List类应当在文档中明确指出什么样的元素添加会受限制。

Specified by:

add in interface Collection

Parameters:

o - element to be appended to this list. 假如列表的元素。

Returns:

true (as per the general contract of the Collection.add method). 根据Collection.add方法的一般约定返回true。

Throws:

UnsupportedOperationException - if the add method is not supported by this list. 列表不支持add方法时抛出。

ClassCastException - if the class of the specified element prevents it from being added to this list. 如果指定元素的类型阻止其加入列表时抛出。

NullPointerException - if the specified element is null and this list does not support null elements. 如果指定元素为null而列表不支持null元素时抛出。

IllegalArgumentException - if some aspect of this element prevents it from being added to this list. 如果指定元素的某些方面不允许它加入当前列表则抛出。

remove

public boolean remove(Object o)

Removes the first occurrence in this list of the specified element (optional operation). If this list does not contain the element, it is unchanged. More formally, removes the element with the lowest index i such that (o==null ? get(i)==null : o.equals(get(i))) (if such an element exists). 从列表中删除第一次出现的指定元素（可选操作）。如果列表不含该元素，不会对列表有影响。 正式表述为，如果存在那样的元素，使得(o==null ? get(i)==null : o.equals(get(i)))， 那么删除下标i最小的元素。

Specified by:

remove in interface Collection

Parameters:

o - element to be removed from this list, if present. 如果有，从列表中删除的元素。

Returns:

true if this list contained the specified element. 如果列表包含指定元素，返回true。

Throws:

ClassCastException - if the type of the specified element is incompatible with this list (optional). 如果指定元素的类型与列表不相容时抛出（可选）。

NullPointerException - if the specified element is null and this list does not support null elements (optional). 如果指定元素为null而列表不支持null元素时抛出（可选）。

UnsupportedOperationException - if the remove method is not supported by this list. 如果列表不支持remove方法时抛出。

containsAll

public boolean containsAll(Collection c)

Returns true if this list contains all of the elements of the specified collection. 如果列表包含指定集合的所有元素，返回true。

Specified by:

containsAll in interface Collection

Parameters:

c - collection to be checked for containment in this list. 检查列表是否包含的集合。

Returns:

true if this list contains all of the elements of the specified collection. 如果列表包含指定集合的所有元素，返回true。

Throws:

ClassCastException - if the types of one or more elements in the specified collection are incompatible with this list (optional). 如果指定元素的类型与列表不相容时抛出（可选）。

NullPointerException - if the specified collection contains one or more null elements and this list does not support null elements (optional). 如果指定集合包含一个或多个null元素而列表不支持null元素时抛出（可选）。

NullPointerException - if the specified collection is null. 如果指定集合为null时抛出。

See Also:

contains(Object)

addAll

public boolean addAll(Collection c)

Appends all of the elements in the specified collection to the end of this list, in the order that they are returned by the specified collection's iterator (optional operation). The behavior of this operation is unspecified if the specified collection is modified while the operation is in progress. (Note that this will occur if the specified collection is this list, and it's nonempty.) 按指定集合的迭代其返回顺序，向列表末尾添加指定集合的所有元素（可选操作）。如果在该操作过程中指定集合 被修改，操作行为无法确定。（注意，这只有在指定集合为当前列表且非空的情况下才会发生。）

Specified by:

addAll in interface Collection

Parameters:

c - collection whose elements are to be added to this list. 被加入列表的元素集合。

Returns:

true if this list changed as a result of the call. 如果调用的结果改变了列表，返回true。

Throws:

UnsupportedOperationException - if the addAll method is not supported by this list. 如果列表不支持addAll方法时抛出。

ClassCastException - if the class of an element in the specified collection prevents it from being added to this list. 如果指定集合的元素类型阻止其加入列表时抛出。

NullPointerException - if the specified collection contains one or more null elements and this list does not support null elements, or if the specified collection is null. 如果指定集合包含一个或多个null元素而列表不支持null元素，或者指定集合为null时抛出。

IllegalArgumentException - if some aspect of an element in the specified collection prevents it from being added to this list. 如果指定集合的某个元素的某些方面不允许它加入当前列表则抛出。

See Also:

add(Object)

addAll

public boolean addAll(int index,
                      Collection c)

Inserts all of the elements in the specified collection into this list at the specified position (optional operation). Shifts the element currently at that position (if any) and any subsequent elements to the right (increases their indices). The new elements will appear in this list in the order that they are returned by the specified collection's iterator. The behavior of this operation is unspecified if the specified collection is modified while the operation is in progress. (Note that this will occur if the specified collection is this list, and it's nonempty.) 向列表的指定位置插入指定集合的所有元素（可选操作）。当前位置的元素（若有） 和所有后续元素右移（下标加1）。列表中新元素的出现顺序为指定集合迭代其返回的 顺序。如果在该操作过程中指定集合被修改，操作行为无法确定。 （注意，这只有在指定集合为当前列表且非空的情况下才会发生。）

Parameters:

index - index at which to insert first element from the specified collection. 插入指定集合中的一个元素的下标。

c - elements to be inserted into this list. 被插入列表的元素。

Returns:

true if this list changed as a result of the call. 如果调用的结果改变了列表，返回true。

Throws:

UnsupportedOperationException - if the addAll method is not supported by this list. 如果列表不支持addAll方法时抛出。

ClassCastException - if the class of one of elements of the specified collection prevents it from being added to this list. 如果指定集合的元素类型阻止其加入列表时抛出。

NullPointerException - if the specified collection contains one or more null elements and this list does not support null elements, or if the specified collection is null. 如果指定集合包含一个或多个null元素而列表不支持null元素或者指定集合为null时抛出。

IllegalArgumentException - if some aspect of one of elements of the specified collection prevents it from being added to this list. 如果指定集合的某个元素的某些方面不允许它加入当前列表则抛出。

IndexOutOfBoundsException - if the index is out of range (index < 0 || index > size()). 如果下标超出(index < 0 || index > size())的范围时抛出。

removeAll

public boolean removeAll(Collection c)

Removes from this list all the elements that are contained in the specified collection (optional operation). 从列表中删除指定集合所含的所有元素（可选操作）。

Specified by:

removeAll in interface Collection

Parameters:

c - collection that defines which elements will be removed from this list. 集合，定义为将要从列表中删除的元素。

Returns:

true if this list changed as a result of the call. 如果调用的结果改变了列表，返回true。

Throws:

UnsupportedOperationException - if the removeAll method is not supported by this list. 如果列表不支持removeAll方法时抛出。

ClassCastException - if the types of one or more elements in this list are incompatible with the specified collection (optional). 如果列表中一个或多个元素的类型与集合不相容时抛出（可选）。

NullPointerException - if this list contains one or more null elements and the specified collection does not support null elements (optional). 如果列表包含一个或多个null元素而指定集合不支持null元素时抛出（可选）。

NullPointerException - if the specified collection is null. 如果指定集合为null时抛出。

See Also:

remove(Object), contains(Object)

retainAll

public boolean retainAll(Collection c)

Retains only the elements in this list that are contained in the specified collection (optional operation). In other words, removes from this list all the elements that are not contained in the specified collection. 列表只保留指定集合所含的元素（可选操作）。换句话说，从列表中删除指定集合中不含的所有元素。

Specified by:

retainAll in interface Collection

Parameters:

c - collection that defines which elements this set will retain. 定义为列表要保留的元素集合。

Returns:

true if this list changed as a result of the call. 如果调用的结果改变了列表，返回true。

Throws:

UnsupportedOperationException - if the retainAll method is not supported by this list. 如果列表不支持retainAll方法时抛出。

ClassCastException - if the types of one or more elements in this list are incompatible with the specified collection (optional). 如果列表中有一个或多个元素类型与指定集合不相容时抛出（可选）。

NullPointerException - if this list contains one or more null elements and the specified collection does not support null elements (optional). 如果列表包含一个或多个null元素而指定集合不支持null元素时抛出（可选）。

NullPointerException - if the specified collection is null. 如果指定集合为null时抛出。

See Also:

remove(Object), contains(Object)

clear

public void clear()

Removes all of the elements from this list (optional operation). This list will be empty after this call returns (unless it throws an exception). 从列表中删除所有元素（可选操作）。在调用返回后列表将为空（除非抛出异常）。

Specified by:

clear in interface Collection

Throws:

UnsupportedOperationException - if the clear method is not supported by this list. 如果列表不支持clear方法时抛出。

equals

public boolean equals(Object o)

Compares the specified object with this list for equality. Returns true if and only if the specified object is also a list, both lists have the same size, and all corresponding pairs of elements in the two lists are equal. (Two elements e1 and e2 are equal if (e1==null ? e2==null : e1.equals(e2)).) In other words, two l

原文转自：http://www.ltesting.net