Module  java.base
软件包  java.util

Class ArrayList<E>

  • 参数类型
    E - 此列表中元素的类型
    All Implemented Interfaces:
    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扔出ConcurrentModificationException 。 因此，编写依赖于此异常的程序的正确性将是错误的： 迭代器的故障快速行为应仅用于检测错误。

    这个类是Java Collections Framework的成员。

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

    • 构造方法摘要

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

    • 方法摘要

      所有方法  接口方法  具体的方法 
      Modifier and Type 方法 描述
      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实例的容量，以确保它至少能够容纳最小容量参数指定的元素数量。
      void forEach​(Consumer<? super E> action)
      对 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之间的元素。
      void replaceAll​(UnaryOperator<E> operator)
      将该列表的每个元素替换为将该运算符应用于该元素的结果。
      boolean retainAll​(Collection<?> c)
      仅保留此列表中包含在指定集合中的元素。
      E set​(int index, E element)
      用指定的元素替换此列表中指定位置的元素。
      int size​()
      返回此列表中的元素数。
      void sort​(Comparator<? super E> c)
      根据指定的Comparator引发的顺序排列此列表。
      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​()
        构造一个初始容量为十的空列表。

      • ArrayList

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

    • 方法详细信息

      • trimToSize

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

      • ensureCapacity

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

      • 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 - 如果指定的数组为空

      • 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在接口 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 - 如果指定的集合为空
        另请参见：
        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 - 如果指定的集合为空

      • 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相等，返回的列表为空。）返回的列表由此列表支持，因此返回列表中的非结构更改将反映在此列表中，反之亦然。 返回的列表支持所有可选列表操作。

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

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

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

        Specified by:
        subList在接口 List<E>
        重写：
        subList在 AbstractList<E>
        参数
        fromIndex - 子列表的低端点（含）
        toIndex - 子列表的高端点（排他性）
        结果
        该列表中指定范围的视图
        异常
        IndexOutOfBoundsException - 如果端点索引值超出范围 (fromIndex < 0 || toIndex > size)
        IllegalArgumentException - 如果端点索引不正确 (fromIndex > toIndex)

      • forEach

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

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

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

      • removeIf

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

      • replaceAll

        public void replaceAll​(UnaryOperator<E> operator)
        说明从界面List复制
        将该列表的每个元素替换为将该运算符应用于该元素的结果。 运营商抛出的错误或运行时异常被转发给呼叫者。
        Specified by:
        replaceAll在接口 List<E>
        参数
        operator - 操作员应用于每个元素

      • sort

        public void sort​(Comparator<? super E> c)
        说明从接口List复制
        根据指定的Comparator引发的顺序排列此列表。

        此列表中的所有元素必须使用指定的比较器相互比较（即， c.compare(e1, e2)不能为ClassCastException中的任何元素e1和e2抛出ClassCastException ）。

        如果指定的比较器是null则该列表中的所有元素都必须实现Comparable接口，并且应使用元素' natural ordering '。

        该列表必须是可修改的，但不能调整大小。

        Specified by:
        sort在接口 List<E>
        参数
        c - Comparator用于比较列表元素。 A null值表示应使用元素' natural ordering '