选自 wocongdongfanglai 的 Blog
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 access 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
Method Summary | |
void | add(int index, Object element) Inserts the specified element at the specified position in this list (optional operation). 向列表指定位置插入指定元素(可选操作)。 |
boolean | add(Object o) Appends the specified element to the end of this list (optional operation). 向列表末尾添加指定元素(可选操作)。 |
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). 按指定集合的迭代其返回顺序,向列表末尾添加指定集合的所有元素(可选操作)。 |
boolean | addAll(int index, Collection c) Inserts all of the elements in the specified collection into this list at the specified position (optional operation). 向列表的指定位置插入指定集合的所有元素(可选操作)。 |
void | clear() Removes all of the elements from this list (optional operation). 从列表中删除所有元素(可选操作)。 |
boolean | contains(Object o) Returns true if this list contains the specified element. 如果列表包含指定元素,返回true。 |
boolean | containsAll(Collection c) Returns true if this list contains all of the elements of the specified collection. 如果列表包含指定集合的所有元素,返回true。 |
boolean | equals(Object o) Compares the specified object with this list for equality. 将指定对象和当前列表就相等性进行比较。 |
Object | get(int index) Returns the element at the specified position in this list. 返回列表指定位置的元素。 |
int | hashCode() Returns the hash code value for this list. 返回列表的哈希码值。 |
int | indexOf(Object o) Returns the index in this list of the first occurrence of the specified element, or -1 if this list does not contain this element. 返回指定元素在列表中第一次出现的位置下标,如果不含该元素,返回-1。 |
boolean | isEmpty() Returns true if this list contains no elements. 如果列表不含元素,返回true。 |
Iterator | iterator() Returns an iterator over the elements in this list in proper sequence. 以本来顺序返回列表元素的迭代器。 |
int | lastIndexOf(Object o) Returns the index in this list of the last occurrence of the specified element, or -1 if this list does not contain this element. 返回指定元素在列表中最后一次出现的位置下标,如果不含该元素,返回-1。 |
ListIterator | listIterator() Returns a list iterator of the elements in this list (in proper sequence). 以本来顺序返回列表元素的列表迭代器。 |
ListIterator | listIterator(int index) Returns a list iterator of the elements in this list (in proper sequence), starting at the specified position in this list. 从列表指定位置开始,以本来顺序返回列表元素的列表迭代器。 |
Object | remove(int index) Removes the element at the specified position in this list (optional operation). 删除列表指定位置的元素(可选操作)。 |
boolean | remove(Object o) Removes the first occurrence in this list of the specified element (optional operation). 从列表中删除第一次出现的指定元素(可选操作)。 |
boolean | removeAll(Collection c) Removes from this list all the elements that are contained in the specified collection (optional operation). 从列表中删除指定集合所含的所有元素(可选操作)。 |
boolean | retainAll(Collection c) Retains only the elements in this list that are contained in the specified collection (optional operation). 列表只保留指定集合所含的元素(可选操作)。 |
Object | set(int index, Object element) Replaces the element at the specified position in this list with the specified element (optional operation). 以指定元素替换列表指定位置的元素(可选操作)。 |
int | size() Returns the number of elements in this list. 返回列表元素的数目。 |
List | subList(int fromIndex, int toIndex) Returns a view of the portion of this list between the specified fromIndex, inclusive, and toIndex, exclusive. 返回从fromIndex(含)到toIndex(不含)的部分列表视图。 |
Object[] | toArray() Returns an array containing all of the elements in this list in proper sequence. 返回一个以本来顺序包含列表所有元素的数组。 |
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. 返回一个以本来顺序包含列表所有元素的数组,返回数组的返回时类型为指定数组类型。 |
Method Detail |
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 interfaceCollection
-
-
-
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 interfaceCollection
-
-
-
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 interfaceCollection
-
-
-
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 interfaceCollection
-
-
-
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 interfaceCollection
-
-
-
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 interfaceCollection
-
-
-
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 interfaceCollection
-
-
-
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 interfaceCollection
-
-
-
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 interfaceCollection
-
-
-
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 interfaceCollection
-
-
-
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 interfaceCollection
-
-
-
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 interfaceCollection
-
-
-
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 interfaceCollection
-
-
-
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 lists are defined to be equal if they contain the same elements in the same order. This definition ensures that the equals method works properly across different implementations of the List interface. 将指定对象和当前列表就相等性进行比较。只有指定对象也是一个列表, 两个列表有着相同大小,两个列表中所有对应元素都相等时返回true。 (如果(e1==null ? e2==null : e1.equals(e2)),那么两个元素e1和e2相等。) 换句话说,两个列表只有以相同顺序包含相同的元素,才被认为相等。 该定义可以 保证对于List接口的不同实现,equals方法都能正常工作。
-
-
Specified by:
-
equals
in interfaceCollection
Overrides:
-
equals
in classObject
-
-
-
Parameters:
-
o
- the object to be compared for equality with this list. 同当前列表比较相等性的对象。
Returns:
- true if the specified object is equal to this list. 如果指定的对象与当前列表相等,返回true。 See Also:
-
Object.hashCode()
,Hashtable
-
hashCode
public int hashCode()
-
Returns the hash code value for this list. The hash code of a list is defined to be the result of the following calculation: 返回列表的哈希码值。列表的哈希码被定义为以下计算式的结果:
hashCode = 1; Iterator i = list.iterator(); while (i.hasNext()) { Object obj = i.next(); hashCode = 31*hashCode + (obj==null ? 0 : obj.hashCode()); }
This ensures that list1.equals(list2) implies that list1.hashCode()==list2.hashCode() for any two lists, list1 and list2, as required by the general contract of Object.hashCode. 这将确保对于两个列表list11和list2,list1.equals(list2) 意味着list1.hashCode()==list2.hashCode(),遵循 Object.hashCode方法的一般约定。 -
-
Specified by:
-
hashCode
in interfaceCollection
Overrides:
-
hashCode
in classObject
-
-
-
Returns:
- the hash code value for this list. See Also:
-
Object.hashCode()
,Object.equals(Object)
,equals(Object)
get
public Object get(int index)
-
Returns the element at the specified position in this list. 返回列表指定位置的元素。
-
-
-
Parameters:
-
index
- index of element to return. 返回元素的下标。
Returns:
- the element at the specified position in this list. 列表指定位置的元素。 Throws:
-
IndexOutOfBoundsException
- if the index is out of range (index < 0 || index >= size()). 如果下标超出(index < 0 || index >= size())的范围时抛出。
-
set
public Object set(int index, Object element)
-
Replaces the element at the specified position in this list with the specified element (optional operation). 以指定元素替换列表指定位置的元素(可选操作)。
-
-
-
Parameters:
-
index
- index of element to replace. 要替换的元素下标。 -
element
- element to be stored at the specified position. 存储在指定位置的元素。
Returns:
- the element previously at the specified position. 指定位置的原元素。 Throws:
-
UnsupportedOperationException
- if the set method is not supported by this list. 如果列表不支持set方法时抛出。 -
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 the specified element prevents it from being added to this list. 如果指定元素的某些方面不允许它加入当前列表则抛出。 -
IndexOutOfBoundsException
- if the index is out of range (index < 0 || index >= size()). 如果下标超出(index < 0 || index >= size())的范围时抛出。
-
add
public void add(int index, Object element)
-
Inserts the specified element at the specified position in this list (optional operation). Shifts the element currently at that position (if any) and any subsequent elements to the right (adds one to their indices). 向列表指定位置插入指定元素(可选操作)。当前位置的元素(若有)和所有后续元素右移(下标加1)。
-
-
-
Parameters:
-
index
- index at which the specified element is to be inserted. 要插入指定元素的位置。 -
element
- element to be inserted. 要插入的元素。
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 the specified element prevents it from being added to this list. 如果指定元素的某些方面不允许它加入当前列表则抛出。 -
IndexOutOfBoundsException
- if the index is out of range (index < 0 || index > size()). 如果下标超出(index < 0 || index > size())的范围时抛出。
-
remove
public Object remove(int index)
-
Removes the element at the specified position in this list (optional operation). Shifts any subsequent elements to the left (subtracts one from their indices). Returns the element that was removed from the list. 删除列表指定位置的元素(可选操作)。所有后续元素左移(下标减1)。 返回从列表中删除的元素。
-
-
-
Parameters:
-
index
- the index of the element to removed. 要删除元素的下标。
Returns:
- the element previously at the specified position. 指定位置的原元素。 Throws:
-
UnsupportedOperationException
- if the remove method is not supported by this list. 如果列表不支持remove方法时抛出。 -
IndexOutOfBoundsException
- if the index is out of range (index < 0 || index >= size()). 如果下标超出(index < 0 || index >= size())的范围时抛出。
-
indexOf
public int indexOf(Object o)
-
Returns the index in this list of the first occurrence of the specified element, or -1 if this list does not contain this element. More formally, returns the lowest index i such that (o==null ? get(i)==null : o.equals(get(i))), or -1 if there is no such index. 返回指定元素在列表中第一次出现的位置下标,如果不含该元素,返回-1。 正式表述为,如果存在那样的元素,使得(o==null ? get(i)==null : o.equals(get(i))), 那么返回最小的下标i,如果没有返回-1。
-
-
-
Parameters:
-
o
- element to search for. 要查找的元素。
Returns:
- the index in this list of the first occurrence of the specified element, or -1 if this list does not contain this element. 指定元素在列表中第一次出现的位置下标,如果不含该元素,返回-1。 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元素时抛出(可选)。
-
lastIndexOf
public int lastIndexOf(Object o)
-
Returns the index in this list of the last occurrence of the specified element, or -1 if this list does not contain this element. More formally, returns the highest index i such that (o==null ? get(i)==null : o.equals(get(i))), or -1 if there is no such index. 返回指定元素在列表中最后一次出现的位置下标,如果不含该元素,返回-1。 正式表述为,如果存在那样的元素,使得(o==null ? get(i)==null : o.equals(get(i))), 那么返回最大的下标i,如果没有返回-1。
-
-
-
Parameters:
-
o
- element to search for. 要查找的元素。
Returns:
- the index in this list of the last occurrence of the specified element, or -1 if this list does not contain this element. 指定元素在列表中最后一次出现的位置下标,如果不含该元素,返回-1。 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元素时抛出(可选)。
-
listIterator
public ListIterator listIterator()
-
Returns a list iterator of the elements in this list (in proper sequence). 以本来顺序返回列表元素的列表迭代器。
-
-
-
Returns:
- a list iterator of the elements in this list (in proper sequence). 列表元素本来顺序的列表迭代器。
listIterator
public ListIterator listIterator(int index)
-
Returns a list iterator of the elements in this list (in proper sequence), starting at the specified position in this list. The specified index indicates the first element that would be returned by an initial call to the next method. An initial call to the previous method would return the element with the specified index minus one. 从列表指定位置开始,以本来顺序返回列表元素的列表迭代器。指定的下标 表示第一次调用next方法返回的第一个元素。第一次调用previous方法返回 下标为指定下标减1的元素。
-
-
-
Parameters:
-
index
- index of first element to be returned from the list iterator (by a call to the next method). 列表迭代器调用next方法返回的第一个元素下标。
Returns:
- a list iterator of the elements in this list (in proper sequence), starting at the specified position in this list. 列表元素本来顺序的列表迭代器,从列表指定位置开始。 Throws:
-
IndexOutOfBoundsException
- if the index is out of range (index < 0 || index > size()). 如果下标超出(index < 0 || index > size())的范围时抛出。
-
subList
public List subList(int fromIndex, int toIndex)
-
Returns a view of the portion of this list between the specified fromIndex, inclusive, and toIndex, exclusive. (If fromIndex and toIndex are equal, the returned list is empty.) The returned list is backed by this list, so non-structural changes in the returned list are reflected in this list, and vice-versa. The returned list supports all of the optional list operations supported by this list. 返回从fromIndex(含)到toIndex(不含)的部分列表视图。如果fromIndex和toIndex 相等,返回列表为空。返回列表由当前列表得出,因此返回列表的非结构性更改会影响到当前列表。 返回列表支持当前列表支持的所有可选操作。
This method eliminates the need for explicit range operations (of the sort that commonly exist for arrays). Any operation that expects a list can be used as a range operation by passing a subList view instead of a whole list. For example, the following idiom removes a range of elements from a list: 该方法克服了显式范围操作时需将列表转换成数组的弊端。 对于希望将列表用于范围操作的方法只需要传递给子列表视图代之整个列表。 例如,以下语法删除列表中某个范围的元素:
list.subList(from, to).clear();
Similar idioms may be constructed for indexOf and lastIndexOf, and all of the algorithms in the Collections class can be applied to a subList. 对于indexOf和lastIndexOf的用法相似,Collections类的所有算法 都可以在子列表中应用。The semantics of the list returned by this method become undefined if the backing list (i.e., this list) is structurally modified in any way other than via the returned list. (Structural modifications are those that change the size of this list, or otherwise perturb it in such a fashion that iterations in progress may yield incorrect results.) 如果返回列表通过某种方式使当前列表发生了结构性的改变,该方法返回的列表语义 将变得不能确定。(结构性的改变指改变列表的大小,或者在迭代过程中 以其它方式使得生成结果不正确。)
-
-
-
Parameters:
-
fromIndex
- low endpoint (inclusive) of the subList. 子列表的起始点(含)。 -
toIndex
- high endpoint (exclusive) of the subList. 子列表的终止点(不含)。
Returns:
- a view of the specified range within this list. 列表指定范围内的视图。 Throws:
-
IndexOutOfBoundsException
- for an illegal endpoint index value (fromIndex < 0 || toIndex > size || fromIndex > toIndex). 对于非法的端点下标值(fromIndex < 0 || toIndex > size || fromIndex > toIndex)抛出。
-