JavaTM 2 Platform
Standard Ed. 5.0

java.util
类 ArrayList<E>

java.lang.Object
  继承者 java.util.AbstractCollection<E>
      继承者 java.util.AbstractList<E>
          继承者 java.util.ArrayList<E>
所有已实现的接口:
Serializable, Cloneable, Iterable<E>, Collection<E>, List<E>, RandomAccess
直接已知子类:
AttributeList, RoleList, RoleUnresolvedList

public class ArrayList<E>
extends AbstractList<E>
implements List<E>, RandomAccess, Cloneable, Serializable

List 接口的大小可变数组的实现。实现了所有可选列表操作,并允许包括 null 在内的所有元素。除了实现 List 接口外,此类还提供一些方法来操作内部用来存储列表的数组的大小。(此类大致上等同于 Vector 类,除了此类是不同步的。)

sizeisEmptygetsetiteratorlistIterator 操作都以固定时间运行。add 操作以分摊的固定时间 运行,也就是说,添加 n 个元素需要 O(n) 时间。其他所有操作都以线性时间运行(大体上讲)。与用于 LinkedList 实现的常数因子相比,此实现的常数因子较低。

每个 ArrayList 实例都有一个容量。该容量是指用来存储列表元素的数组的大小。它总是至少等于列表的大小。随着向 ArrayList 中不断添加元素,其容量也自动增长。并未指定增长策略的细节,因为这不只是添加元素会带来分摊固定时间开销那样简单。

在添加大量元素前,应用程序可以使用 ensureCapacity 操作来增加 ArrayList 实例的容量。这可以减少递增式再分配的数量。

注意,此实现不是同步的。如果多个线程同时访问一个 ArrayList 实例,而其中至少一个线程从结构上修改了列表,那么它必须 保持外部同步。(结构上的修改是指任何添加或删除一个或多个元素的操作,或者显式调整底层数组的大小;仅仅设置元素的值不是结构上的修改。)这一般通过对自然封装该列表的对象进行同步操作来完成。如果不存在这样的对象,则应该使用 Collections.synchronizedList 方法将该列表“包装”起来。这最好在创建时完成,以防止意外对列表进行不同步的访问:

        List list = Collections.synchronizedList(new ArrayList(...));
 

此类的 iteratorlistIterator 方法返回的迭代器是快速失败的:在创建迭代器之后,除非通过迭代器自身的 remove 或 add 方法从结构上对列表进行修改,否则在任何时间以任何方式对列表进行修改,迭代器都会抛出 ConcurrentModificationException。因此,面对并发的修改,迭代器很快就会完全失败,而不是冒着在将来某个不确定时间发生任意不确定行为的风险。

注意,迭代器的快速失败行为无法得到保证,因为一般来说,不可能对是否出现不同步并发修改做出任何硬性保证。快速失败迭代器会尽最大努力抛出 ConcurrentModificationException。因此,为提高这类迭代器的正确性而编写一个依赖于此异常的程序是错误的做法:迭代器的快速失败行为应该仅用于检测 bug。

此类是 Java Collections Framework 的成员。

从以下版本开始:
1.2
另请参见:
Collection, List, LinkedList, Vector, Collections.synchronizedList(List), 序列化表格

字段摘要
 
从类 java.util.AbstractList 继承的字段
modCount
 
构造方法摘要
ArrayList()
          构造一个初始容量为 10 的空列表。
ArrayList(Collection<? extends E> c)
          构造一个包含指定 collection 的元素的列表,这些元素是按照该 collection 的迭代器返回它们的顺序排列的。
ArrayList(int initialCapacity)
          构造一个具有指定初始容量的空列表。
 
方法摘要
 boolean add(E o)
          将指定的元素追加到此列表的尾部。
 void add(int index, E element)
          将指定的元素插入此列表中的指定位置。
 boolean addAll(Collection<? extends E> c)
          按照指定 Collection 的迭代器所返回的元素顺序,将该 Collection 中的所有元素追加到此列表的尾部。
 boolean addAll(int index, Collection<? extends E> c)
          从指定的位置开始,将指定 Collection 中的所有元素插入到此列表中。
 void clear()
          移除此列表中的所有元素。
 Object clone()
          返回此 ArrayList 实例的浅表复制。
 boolean contains(Object elem)
          如果此列表中包含指定的元素,则返回 true
 void ensureCapacity(int minCapacity)
          如有必要,增加此 ArrayList 实例的容量,以确保它至少能够容纳最小容量参数所指定的元素数。
 E get(int index)
          返回此列表中指定位置上的元素。
 int indexOf(Object elem)
          搜索给定参数第一次出现的位置,使用 equals 方法进行相等性测试。
 boolean isEmpty()
          测试此列表中是否没有元素。
 int lastIndexOf(Object elem)
          返回指定的对象在列表中最后一次出现的位置索引。
 E remove(int index)
          移除此列表中指定位置上的元素。
 boolean remove(Object o)
          从此列表中移除指定元素的单个实例(如果存在),此操作是可选的。
protected  void removeRange(int fromIndex, int toIndex)
          移除列表中索引在 fromIndex(包括)和 toIndex(不包括)之间的所有元素。
 E set(int index, E element)
          用指定的元素替代此列表中指定位置上的元素。
 int size()
          返回此列表中的元素数。
 Object[] toArray()
          返回一个按照正确的顺序包含此列表中所有元素的数组。
<T> T[]
toArray(T[] a)
          返回一个按照正确的顺序包含此列表中所有元素的数组;返回数组的运行时类型就是指定数组的运行时类型。
 void trimToSize()
          将此 ArrayList 实例的容量调整为列表的当前大小。
 
从类 java.util.AbstractList 继承的方法
equals, hashCode, iterator, listIterator, listIterator, subList
 
从类 java.util.AbstractCollection 继承的方法
containsAll, removeAll, retainAll, toString
 
从类 java.lang.Object 继承的方法
finalize, getClass, notify, notifyAll, wait, wait, wait
 
从接口 java.util.List 继承的方法
containsAll, equals, hashCode, iterator, listIterator, listIterator, removeAll, retainAll, subList
 

构造方法详细信息

ArrayList

public ArrayList(int initialCapacity)
构造一个具有指定初始容量的空列表。

参数:
initialCapacity - 列表的初始容量。
抛出:
IllegalArgumentException - 如果指定的初始容量为负

ArrayList

public ArrayList()
构造一个初始容量为 10 的空列表。


ArrayList

public ArrayList(Collection<? extends E> c)
构造一个包含指定 collection 的元素的列表,这些元素是按照该 collection 的迭代器返回它们的顺序排列的。ArrayList 实例的初始容量是指定 collection 大小的 110%。

参数:
c - 其元素将放置在此列表中的 collection 。
抛出:
NullPointerException - 如果指定的 collection 为 null。
方法详细信息

trimToSize

public void trimToSize()
将此 ArrayList 实例的容量调整为列表的当前大小。应用程序可以使用此操作来最小化 ArrayList 实例的存储量。


ensureCapacity

public void ensureCapacity(int minCapacity)
如有必要,增加此 ArrayList 实例的容量,以确保它至少能够容纳最小容量参数所指定的元素数。

参数:
minCapacity - 所需的最小容量。

size

public int size()
返回此列表中的元素数。

指定者:
接口 Collection<E> 中的 size
指定者:
接口 List<E> 中的 size
指定者:
AbstractCollection<E> 中的 size
返回:
此列表中的元素数。

isEmpty

public boolean isEmpty()
测试此列表中是否没有元素。

指定者:
接口 Collection<E> 中的 isEmpty
指定者:
接口 List<E> 中的 isEmpty
覆盖:
AbstractCollection<E> 中的 isEmpty
返回:
如果此列表中没有元素,则返回 true;否则返回 false

contains

public boolean contains(Object elem)
如果此列表中包含指定的元素,则返回 true

指定者:
接口 Collection<E> 中的 contains
指定者:
接口 List<E> 中的 contains
覆盖:
AbstractCollection<E> 中的 contains
参数:
elem - 测试此列表中是否存在的元素。
返回:
如果指定的元素存在,则返回 true;否则返回 false

indexOf

public int indexOf(Object elem)
搜索给定参数第一次出现的位置,使用 equals 方法进行相等性测试。

指定者:
接口 List<E> 中的 indexOf
覆盖:
AbstractList<E> 中的 indexOf
参数:
elem - 一个对象。
返回:
此列表中第一次出现该参数的位置索引;如果没有找到该对象,则返回 -1
另请参见:
Object.equals(Object)

lastIndexOf

public int lastIndexOf(Object elem)
返回指定的对象在列表中最后一次出现的位置索引。

指定者:
接口 List<E> 中的 lastIndexOf
覆盖:
AbstractList<E> 中的 lastIndexOf
参数:
elem - 所需的元素。
返回:
指定的对象在列表中最后一次出现的位置索引 ;如果没有找到该对象,则返回 -1。

clone

public Object clone()
返回此 ArrayList 实例的浅表复制。(不复制这些元素本身。)

覆盖:
Object 中的 clone
返回:
ArrayList 实例的一个克隆。
另请参见:
Cloneable

toArray

public Object[] toArray()
返回一个按照正确的顺序包含此列表中所有元素的数组。

指定者:
接口 Collection<E> 中的 toArray
指定者:
接口 List<E> 中的 toArray
覆盖:
AbstractCollection<E> 中的 toArray
返回:
以正确的顺序包含此列表中所有元素的数组。
另请参见:
Arrays.asList(Object[])

toArray

public <T> T[] toArray(T[] a)
返回一个按照正确的顺序包含此列表中所有元素的数组;返回数组的运行时类型就是指定数组的运行时类型。如果列表能放入指定的数组,则返回放入此列表元素的数组。否则,将根据指定数组的运行时类型和此列表的大小分配一个新的数组。

如果指定的数组能容纳列表并有剩余空间(即数组的元素比列表的多),那么会将数组中紧跟在集合末尾的元素设置为 null。这对确定列表的长度很有用,但 在调用方知道列表中不包含任何 null 元素时才有用。

指定者:
接口 Collection<E> 中的 toArray
指定者:
接口 List<E> 中的 toArray
覆盖:
AbstractCollection<E> 中的 toArray
参数:
a - 要存储列表元素的数组,如果它足够大的话;否则,它是一个为存储列表元素而分配的、具有相同运行时类型的新数组。
返回:
包含列表元素的数组。
抛出:
ArrayStoreException - 如果 a 的运行时类型不是此列表中每个元素的运行时类型的超类型。

get

public E get(int index)
返回此列表中指定位置上的元素。

指定者:
接口 List<E> 中的 get
指定者:
AbstractList<E> 中的 get
参数:
index - 所返回元素的索引。
返回:
此列表中指定位置上的元素。
抛出:
IndexOutOfBoundsException - 如果索引超出范围 (index < 0 || index >= size())

set

public E set(int index,
             E element)
用指定的元素替代此列表中指定位置上的元素。

指定者:
接口 List<E> 中的 set
覆盖:
AbstractList<E> 中的 set
参数:
index - 要替代的元素的索引。
element - 存储在指定位置上的元素。
返回:
以前位于该指定位置上的元素。
抛出:
IndexOutOfBoundsException - 如果索引超出范围 (index < 0 || index >= size())

add

public boolean add(E o)
将指定的元素追加到此列表的尾部。

指定者:
接口 Collection<E> 中的 add
指定者:
接口 List<E> 中的 add
覆盖:
AbstractList<E> 中的 add
参数:
o - 要追加到此列表中的元素。
返回:
true(按照 Collection.add 的常规协定)。

add

public void add(int index,
                E element)
将指定的元素插入此列表中的指定位置。向右移动当前位于该位置的元素(如果有)以及所有后续元素(将其索引加 1)。

指定者:
接口 List<E> 中的 add
覆盖:
AbstractList<E> 中的 add
参数:
index - 指定元素所插入位置的索引。
element - 要插入的元素。
抛出:
IndexOutOfBoundsException - 如果索引超出范围 (index < 0 || index > size())

remove

public E remove(int index)
移除此列表中指定位置上的元素。向左移动所有后续元素(将其索引减 1)。

指定者:
接口 List<E> 中的 remove
覆盖:
AbstractList<E> 中的 remove
参数:
index - 要移除的元素的索引。
返回:
从列表中移除的元素。
抛出:
IndexOutOfBoundsException - 如果索引超出范围 (index < 0 || index >= size())

remove

public boolean remove(Object o)
从此列表中移除指定元素的单个实例(如果存在),此操作是可选的。更正式地说,如果列表包含一个或多个满足 (o==null ? e==null : o.equals(e)) 的元素 e,则移除该元素。如果列表中包含指定的元素,则返回 true(或者等同于这种情况:如果列表随调用的结果而发生改变,则返回 true)。

指定者:
接口 Collection<E> 中的 remove
指定者:
接口 List<E> 中的 remove
覆盖:
AbstractCollection<E> 中的 remove
参数:
o - 要从此列表中移除的元素(如果存在)。
返回:
如果此列表包含指定的元素,则返回 true

clear

public void clear()
移除此列表中的所有元素。此调用返回后,列表将为空。

指定者:
接口 Collection<E> 中的 clear
指定者:
接口 List<E> 中的 clear
覆盖:
AbstractList<E> 中的 clear

addAll

public boolean addAll(Collection<? extends E> c)
按照指定 Collection 的迭代器所返回的元素顺序,将该 Collection 中的所有元素追加到此列表的尾部。如果正在进行此操作时修改指定的 Collection,那么此操作的行为是不明确的。(这意味着如果指定的 Collection 是此列表且此列表是非空的,那么此调用的行为是不明确的。)

指定者:
接口 Collection<E> 中的 addAll
指定者:
接口 List<E> 中的 addAll
覆盖:
AbstractCollection<E> 中的 addAll
参数:
c - 要插入到此列表中的元素。
返回:
如果此列表随调用的结果而发生改变,则返回 true
抛出:
NullPointerException - 如果指定的 collection 为 null。
另请参见:
AbstractCollection.add(Object)

addAll

public boolean addAll(int index,
                      Collection<? extends E> c)
从指定的位置开始,将指定 Collection 中的所有元素插入到此列表中。向右移动当前位于该位置的元素(如果有)以及所有后续元素(增加其索引)。新元素将按照指定 Collection 的迭代器所返回的元素顺序出现在列表中。

指定者:
接口 List<E> 中的 addAll
覆盖:
AbstractList<E> 中的 addAll
参数:
index - 插入指定 collection 中的首个元素的位置索引。
c - 要插入此列表中的元素。
返回:
如果此列表随调用的结果而发生改变,则返回 true
抛出:
IndexOutOfBoundsException - 如果索引超出范围 (index < 0 || index > size())
NullPointerException - 如果指定的 Collection 为 null。

removeRange

protected void removeRange(int fromIndex,
                           int toIndex)
移除列表中索引在 fromIndex(包括)和 toIndex(不包括)之间的所有元素。向左移动所有后续元素(减小其索引)。此调用将列表缩短了 (toIndex - fromIndex) 个元素。(如果 toIndex==fromIndex,则此操作无效。)

覆盖:
AbstractList<E> 中的 removeRange
参数:
fromIndex - 要移除的首个元素的索引。
toIndex - 最后一个要移除的元素后面那个元素的索引。

JavaTM 2 Platform
Standard Ed. 5.0

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java 2 SDK SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2004 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策