模块  java.base
软件包  java.util

Class ArrayList<E>

  • 参数类型
    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 ，除了它是不同步的。）

    该size ， isEmpty ， get ， set ， iterator和listIterator操作在固定时间内运行。 add操作以分摊的常量时间运行，即添加n个元素需要O（n）时间。 所有其他操作都以线性时间运行（粗略地说）。 与LinkedList实施相比，常数因子较低。

    每个ArrayList实例都有一个容量 。 容量是用于存储列表中元素的数组的大小。 它始终至少与列表大小一样大。 随着元素添加到ArrayList，其容量会自动增加。 除了添加元素具有恒定的摊销时间成本这一事实之外，未指定增长策略的详细信息。

    在使用ensureCapacity操作添加大量元素之前，应用程序可以增加ArrayList实例的容量。 这可能会减少增量重新分配的数量。

    请注意，此实现不同步。 如果多个线程同时访问ArrayList实例，并且至少有一个线程在结构上修改了列表，则必须在外部进行同步。 （结构修改是添加或删除一个或多个元素的任何操作，或显式调整后备数组的大小;仅设置元素的值不是结构修改。）这通常通过同步一些自然封装的对象来实现。名单。 如果不存在此类对象，则应使用Collections.synchronizedList方法“包装”该列表。 这最好在创建时完成，以防止意外地不同步访问列表： 

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

    此类的iterator和listIterator方法返回的迭代器是快速失败的 ：如果在创建迭代器之后的任何时候对列表进行结构修改，除了通过迭代器自己的remove或add方法之外，迭代器将抛出ConcurrentModificationException 。 因此，在并发修改的情况下，迭代器快速而干净地失败，而不是在未来的未确定时间冒任意，非确定性行为的风险。

    请注意，迭代器的快速失败行为无法得到保证，因为一般来说，在存在不同步的并发修改时，不可能做出任何硬性保证。 失败快速迭代器以尽力而为的方式抛出ConcurrentModificationException 。 因此，编写依赖于此异常的程序以确保其正确性是错误的： 迭代器的快速失败行为应该仅用于检测错误。

    此课程是Java Collections Framework的成员。

    从以下版本开始：
    1.2
    另请参见：
    Collection ， List ， LinkedList ， Vector ， Serialized Form

    • 构造方法摘要

      构造方法  
      构造器 描述
      ArrayList()
      构造一个初始容量为10的空列表。
      ArrayList​(int initialCapacity)
      构造具有指定初始容量的空列表。
      ArrayList​(Collection<? extends E> c)
      按照集合的迭代器返回的顺序构造一个包含指定集合元素的列表。

    • 方法摘要

      所有方法  实例方法 具体的方法 
      变量和类型 方法 描述
      void add​(int index, E element)
      将指定元素插入此列表中的指定位置。
      boolean add​(E e)
      将指定的元素追加到此列表的末尾。
      boolean addAll​(int index, Collection<? extends E> c)
      从指定位置开始，将指定集合中的所有元素插入此列表。
      boolean addAll​(Collection<? extends E> c)
      将指定集合中的所有元素按指定集合的Iterator返回的顺序附加到此列表的末尾。
      void clear()
      从此列表中删除所有元素。
      Object clone()
      返回此 ArrayList实例的浅表副本。
      boolean contains​(Object o)
      如果此列表包含指定的元素，则返回 true 。
      void ensureCapacity​(int minCapacity)
      如有必要，增加此 ArrayList实例的容量，以确保它至少可以容纳由minimum capacity参数指定的元素数。
      void forEach​(Consumer<? super E> action)
      对 Iterable每个元素执行给定操作，直到处理 Iterable所有元素或操作引发异常。
      E get​(int index)
      返回此列表中指定位置的元素。
      int indexOf​(Object o)
      返回此列表中第一次出现的指定元素的索引，如果此列表不包含该元素，则返回-1。
      boolean isEmpty()
      如果此列表不包含任何元素，则返回 true 。
      Iterator<E> iterator()
      以适当的顺序返回此列表中元素的迭代器。
      int lastIndexOf​(Object o)
      返回此列表中指定元素最后一次出现的索引，如果此列表不包含该元素，则返回-1。
      ListIterator<E> listIterator()
      返回此列表中元素的列表迭代器（按适当顺序）。
      ListIterator<E> listIterator​(int index)
      从列表中的指定位置开始，返回列表中元素的列表迭代器（按正确顺序）。
      E remove​(int index)
      删除此列表中指定位置的元素。
      boolean remove​(Object o)
      从该列表中删除指定元素的第一个匹配项（如果存在）。
      boolean removeAll​(Collection<?> c)
      从此列表中删除指定集合中包含的所有元素。
      boolean removeIf​(Predicate<? super E> filter)
      删除此集合中满足给定谓词的所有元素。
      protected void removeRange​(int fromIndex, int toIndex)
      从此列表中删除索引介于 fromIndex （含）和 toIndex （独占）之间的所有元素。
      boolean retainAll​(Collection<?> c)
      仅保留此列表中包含在指定集合中的元素。
      E set​(int index, E element)
      用指定的元素替换此列表中指定位置的元素。
      int size()
      返回此列表中的元素数。
      Spliterator<E> spliterator()
      在此列表中的元素上创建late-binding和故障快速 Spliterator 。
      List<E> subList​(int fromIndex, int toIndex)
      返回指定的 fromIndex （包含）和 toIndex （不包括）之间的此列表部分的视图。
      Object[] toArray()
      以适当的顺序（从第一个元素到最后一个元素）返回包含此列表中所有元素的数组。
      <T> T[] toArray​(T[] a)
      以适当的顺序返回包含此列表中所有元素的数组（从第一个元素到最后一个元素）; 返回数组的运行时类型是指定数组的运行时类型。
      void trimToSize()
      将此 ArrayList实例的容量调整为列表的当前大小。

    • 构造方法详细信息

      • ArrayList

        public ArrayList​(int initialCapacity)
        构造具有指定初始容量的空列表。
        参数
        initialCapacity - 列表的初始容量
        异常
        IllegalArgumentException - 如果指定的初始容量为负数

      • ArrayList

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

      • ArrayList

        public ArrayList​(Collection<? extends E> c)
        按照集合的迭代器返回的顺序构造一个包含指定集合元素的列表。
        参数
        c - c其元素放入此列表的集合
        异常
        NullPointerException - 如果指定的集合为null

    • 方法详细信息

      • trimToSize

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

      • ensureCapacity

        public void ensureCapacity​(int minCapacity)
        如有必要，增加此 ArrayList实例的容量，以确保它至少可以容纳由minimum capacity参数指定的元素数。
        参数
        minCapacity - 所需的最小容量

      • size

        public int size()
        返回此列表中的元素数。
        Specified by:
        size ，界面 Collection<E>
        Specified by:
        size ，界面 List<E>
        结果
        此列表中的元素数量

      • contains

        public boolean contains​(Object o)
        如果此列表包含指定的元素，则返回true 。 更正式地，返回true当且仅当此列表包含至少一个元素e Objects.equals(o, e) 。
        Specified by:
        contains在界面 Collection<E>
        Specified by:
        contains在界面 List<E>
        重写：
        contains在课程 AbstractCollection<E>
        参数
        o - 要测试其在此列表中的存在的元素
        结果
        true如果此列表包含指定的元素

      • indexOf

        public int indexOf​(Object o)
        返回此列表中第一次出现的指定元素的索引，如果此列表不包含该元素，则返回-1。 更正式的是，返回最低指数i如Objects.equals(o, get(i)) ，如果没有这样的指数则返回-1。
        Specified by:
        indexOf在界面 List<E>
        重写：
        indexOf在课程 AbstractList<E>
        参数
        o - 要搜索的元素
        结果
        此列表中第一次出现的指定元素的索引，如果此列表不包含该元素，则返回-1

      • lastIndexOf

        public int lastIndexOf​(Object o)
        返回此列表中指定元素最后一次出现的索引，如果此列表不包含该元素，则返回-1。 更正式的是，返回最高指数i如Objects.equals(o, get(i)) ，如果没有这样的指数则返回-1。
        Specified by:
        lastIndexOf在界面 List<E>
        重写：
        lastIndexOf在课堂上 AbstractList<E>
        参数
        o - 要搜索的元素
        结果
        此列表中指定元素最后一次出现的索引，如果此列表不包含该元素，则返回-1

      • clone

        public Object clone()
        返回此ArrayList实例的浅表副本。 （元素本身不会被复制。）
        重写：
        clone在课程 Object
        结果
        此 ArrayList实例的克隆
        另请参见：
        Cloneable

      • toArray

        public Object[] toArray()
        以适当的顺序（从第一个元素到最后一个元素）返回包含此列表中所有元素的数组。

        返回的数组将是“安全的”，因为此列表不会保留对它的引用。 （换句话说，此方法必须分配一个新数组）。 因此调用者可以自由修改返回的数组。

        此方法充当基于阵列和基于集合的API之间的桥梁。

        Specified by:
        toArray ，界面 Collection<E>
        Specified by:
        toArray在界面 List<E>
        重写：
        toArray在课程 AbstractCollection<E>
        结果
        一个数组，以适当的顺序包含此列表中的所有元素
        另请参见：
        Arrays.asList(Object[])

      • toArray

        public <T> T[] toArray​(T[] a)
        以适当的顺序返回包含此列表中所有元素的数组（从第一个元素到最后一个元素）; 返回数组的运行时类型是指定数组的运行时类型。 如果列表适合指定的数组，则返回其中。 否则，将为新数组分配指定数组的运行时类型和此列表的大小。

        如果列表适合指定的数组，并且有空余空间（即，数组的元素多于列表），紧接集合结尾的数组中的元素将设置为null 。 （ 仅当调用者知道列表不包含任何null元素时，这在确定列表长度时很有用。）

        Specified by:
        toArray ，界面 Collection<E>
        Specified by:
        toArray ，界面 List<E>
        重写：
        toArray在课程 AbstractCollection<E>
        参数类型
        T - 要包含集合的数组的组件类型
        参数
        a - 要存储列表元素的数组，如果它足够大; 否则，为此目的分配相同运行时类型的新数组。
        结果
        包含列表元素的数组
        异常
        ArrayStoreException - 如果指定数组的运行时类型不是此列表中每个元素的运行时类型的超类型
        NullPointerException - 如果指定的数组为null

      • get

        public E get​(int index)
        返回此列表中指定位置的元素。
        Specified by:
        get ，界面 List<E>
        Specified by:
        get在课程 AbstractList<E>
        参数
        index - 要返回的元素的索引
        结果
        此列表中指定位置的元素
        异常
        IndexOutOfBoundsException - 如果指数超出范围（ index < 0 || index >= size() ）

      • set

        public E set​(int index,             E element)
        用指定的元素替换此列表中指定位置的元素。
        Specified by:
        set ，界面 List<E>
        重写：
        set在课程 AbstractList<E>
        参数
        index - 要替换的元素的索引
        element - 要存储在指定位置的元素
        结果
        先前在指定位置的元素
        异常
        IndexOutOfBoundsException - 如果指数超出范围（ index < 0 || index >= size() ）

      • add

        public boolean add​(E e)
        将指定的元素追加到此列表的末尾。
        Specified by:
        add ，界面 Collection<E>
        Specified by:
        add在界面 List<E>
        重写：
        add在课程 AbstractList<E>
        参数
        e - 要附加到此列表的元素
        结果
        true （由 Collection.add(E)指定）

      • add

        public void add​(int index,                E element)
        将指定元素插入此列表中的指定位置。 将当前位置的元素（如果有）和任何后续元素向右移动（将其添加到索引中）。
        Specified by:
        add in界面 List<E>
        重写：
        add在课程 AbstractList<E>
        参数
        index - 要插入指定元素的索引
        element - 要插入的元素
        异常
        IndexOutOfBoundsException - 如果指数超出范围（ index < 0 || index > size() ）

      • remove

        public E remove​(int index)
        删除此列表中指定位置的元素。 将任何后续元素向左移位（从索引中减去一个元素）。
        Specified by:
        remove在界面 List<E>
        重写：
        remove在课程 AbstractList<E>
        参数
        index - 要删除的元素的索引
        结果
        从列表中删除的元素
        异常
        IndexOutOfBoundsException - 如果指数超出范围（ index < 0 || index >= size() ）

      • remove

        public boolean remove​(Object o)
        从该列表中删除指定元素的第一个匹配项（如果存在）。 如果列表不包含该元素，则不会更改。 更正式地，删除具有最低索引i的元素，使得Objects.equals(o, get(i)) （如果存在这样的元素）。 如果此列表包含指定的元素，则返回true （或等效地，如果此列表因调用而更改）。
        Specified by:
        remove在界面 Collection<E>
        Specified by:
        remove在界面 List<E>
        重写：
        remove在课程 AbstractCollection<E>
        参数
        o - 要从此列表中删除的元素（如果存在）
        结果
        true如果此列表包含指定的元素

      • clear

        public void clear()
        从此列表中删除所有元素。 此调用返回后，列表将为空。
        Specified by:
        clear在界面 Collection<E>
        Specified by:
        clear在界面 List<E>
        重写：
        clear在课程 AbstractList<E>

      • addAll

        public boolean addAll​(Collection<? extends E> c)
        将指定集合中的所有元素按指定集合的Iterator返回的顺序附加到此列表的末尾。 如果在操作正在进行时修改了指定的集合，则此操作的行为是不确定的。 （这意味着如果指定的集合是此列表，则此调用的行为是未定义的，并且此列表是非空的。）
        Specified by:
        addAll ，界面 Collection<E>
        Specified by:
        addAll在界面 List<E>
        重写：
        addAll在课程 AbstractCollection<E>
        参数
        c - 包含要添加到此列表的元素的集合
        结果
        true如果此列表因呼叫而更改
        异常
        NullPointerException - 如果指定的集合为null
        另请参见：
        AbstractCollection.add(Object)

      • addAll

        public boolean addAll​(int index,                      Collection<? extends E> c)
        从指定位置开始，将指定集合中的所有元素插入此列表。 将当前位置的元素（如果有）和任何后续元素向右移动（增加其索引）。 新元素将按照指定集合的迭代器返回的顺序出现在列表中。
        Specified by:
        addAll在界面 List<E>
        重写：
        addAll在课程 AbstractList<E>
        参数
        index - 从指定集合中插入第一个元素的索引
        c - 包含要添加到此列表的元素的集合
        结果
        true如果此列表因呼叫而更改
        异常
        IndexOutOfBoundsException - 如果指数超出范围（ index < 0 || index > size() ）
        NullPointerException - 如果指定的集合为null

      • removeRange

        protected void removeRange​(int fromIndex,                           int toIndex)
        从此列表中删除索引介于fromIndex （含）和toIndex （独占）之间的所有元素。 将任何后续元素向左移动（降低其索引）。 此调用通过(toIndex - fromIndex)元素缩短列表。 （如果toIndex==fromIndex ，此操作无效。）
        重写：
        removeRange在课程 AbstractList<E>
        参数
        fromIndex - 要删除的第一个元素的索引
        toIndex - 要删除的最后一个元素之后的索引
        异常
        IndexOutOfBoundsException - 如果 fromIndex或 toIndex超出范围（ fromIndex < 0 || toIndex > size() || toIndex < fromIndex ）

      • listIterator

        public ListIterator<E> listIterator​(int index)
        从列表中的指定位置开始，返回列表中元素的列表迭代器（按正确顺序）。 指定的索引指示初始调用next将返回的第一个元素。 对previous的初始调用将返回指定索引减去1的元素。

        返回的列表迭代器是fail-fast 。

        Specified by:
        listIterator在界面 List<E>
        重写：
        listIterator在课程 AbstractList<E>
        参数
        index - 从列表迭代器返回的第一个元素的索引（通过调用 next ）
        结果
        列表中元素的列表迭代器（按正确顺序），从列表中的指定位置开始
        异常
        IndexOutOfBoundsException - 如果指数超出范围（ index < 0 || index > size() ）

      • subList

        public List<E> subList​(int fromIndex,                       int toIndex)
        返回指定的fromIndex （包含）和toIndex （独占）之间的此列表部分的视图。 （如果fromIndex和toIndex相等，则返回的列表为空。）返回的列表由此列表支持，因此返回列表中的非结构更改将反映在此列表中，反之亦然。 返回的列表支持所有可选的列表操作。

        此方法消除了对显式范围操作的需要（对于数组通常存在的排序）。 任何需要列表的操作都可以通过传递subList视图而不是整个列表来用作范围操作。 例如，以下习语从列表中删除了一系列元素： 

          list.subList(from, to).clear();
        可以为indexOf(Object)和lastIndexOf(Object)构造类似的习语，并且可以将Collections类中的所有算法应用于子列表。

        如果支持列表（即此列表）在结构上以除返回列表之外的任何方式进行变量 ，则此方法返回的列表的语义将变为未定义。 （结构修改是那些改变了这个列表的大小，或以其他方式扰乱它的方式，正在进行的迭代可能会产生不正确的结果。）

        Specified by:
        subList ，界面 List<E>
        重写：
        subList在课程 AbstractList<E>
        参数
        fromIndex - fromIndex低端点（包括）
        toIndex - toIndex高端点（不包括）
        结果
        此列表中指定范围的视图
        异常
        IndexOutOfBoundsException - 如果端点索引值超出范围 (fromIndex < 0 || toIndex > size)
        IllegalArgumentException - 如果端点索引无序 (fromIndex > toIndex)

      • forEach

        public void forEach​(Consumer<? super E> action)
        从界面复制的说明： Iterable
        对Iterable每个元素执行给定操作，直到处理Iterable所有元素或操作引发异常。 如果指定了该顺序，则按迭代顺序执行操作。 操作抛出的异常将转发给调用者。

        如果操作执行修改元素的基础源的副作用，则此方法的行为未指定，除非重写类已指定并发修改策略。

        Specified by:
        forEach在界面 Iterable<E>
        参数
        action - 要为每个元素执行的操作
        异常
        NullPointerException - 如果指定的操作为null

      • removeIf

        public boolean removeIf​(Predicate<? super E> filter)
        从界面复制的说明： Collection
        删除此集合中满足给定谓词的所有元素。 在迭代期间或通过谓词抛出的错误或运行时异常被中继到调用者。
        Specified by:
        removeIf ，接口 Collection<E>
        参数
        filter - 对于要删除的元素，返回 true的谓词
        结果
        true是否删除了任何元素
        异常
        NullPointerException - 如果指定的过滤器为null