模块  java.base
软件包  java.util

Class AbstractList<E>

  • 实现的所有接口
    Iterable<E> ， Collection<E> ， List<E>
    已知直接子类：
    AbstractSequentialList ， ArrayList ， Vector 
    public abstract class AbstractList<E>extends AbstractCollection<E>implements List<E>
    此类提供List接口的骨干实现，以最大限度地减少实现由“随机访问”数据存储（例如数组）支持的此接口所需的工作量。 对于顺序访问数据（例如链接列表），应优先使用AbstractSequentialList 。

    要实现不可修改的列表，程序员只需要扩展此类并提供get(int)和size()方法的实现。

    要实现可修改的列表，程序员必须另外覆盖set(int, E)方法（否则会抛出UnsupportedOperationException ）。 如果列表是可变大小的，则程序员必须另外覆盖add(int, E)和remove(int)方法。

    程序员通常应根据Collection接口规范中的建议提供void（无参数）和集合构造函数。

    不像其他的抽象集合实现，程序员不必提供迭代器实现; 迭代器和列表迭代器由此类在“随机访问”方法之上 实现 ： get(int),set(int, E),add(int, E)和remove(int) 。

    此类中每个非抽象方法的文档详细描述了它的实现。 如果正在实施的集合允许更有效的实现，则可以覆盖这些方法中的每一个。

    此类是Java Collections Framework的成员。

    从以下版本开始：
    1.2

    • 字段详细信息

      • modCount

        protected transient int modCount
        此列表已被结构修改的次数 。 结构修改是那些改变列表大小或以其他方式扰乱它的方式，即正在进行的迭代可能产生不正确的结果。

        该字段由iterator和listIterator方法返回的迭代器和列表迭代器实现使用。 如果该字段的值意外更改，迭代器（或列表迭代器）将抛出ConcurrentModificationException响应next ， remove ， previous ， set或add操作。 这提供了快速失败的行为，而不是在迭代期间面对并发修改时的非确定性行为。

        子类对此字段的使用是可选的。 如果子类希望提供快速失败迭代器（和列表迭代器），那么它仅仅需要增加其在该领域add(int, E)种remove(int)方法（而且它会覆盖导致结构修改列表中的任何其他方法）。 单次调用add(int, E)或remove(int)必须向此字段添加不超过一个，否则迭代器（和列表迭代器）将抛出伪造ConcurrentModificationExceptions 。 如果实现不希望提供快速失败的迭代器，则可以忽略此字段。

    • 构造方法详细信息

      • AbstractList

        protected AbstractList()
        唯一的构造函数。 （对于子类构造函数的调用，通常是隐式的。）

    • 方法详细信息

      • add

        public boolean add​(E e)
        将指定的元素追加到此列表的末尾（可选操作）。

        支持此操作的列表可能会限制可能添加到此列表的元素。 特别是，某些列表将拒绝添加null元素，而其他列表将对可能添加的元素类型施加限制。 列表类应在其文档中明确指出可以添加哪些元素的任何限制。

        Specified by:
        add in interface Collection<E>
        Specified by:
        add ，接口 List<E>
        重写：
        add类 AbstractCollection<E>
        实现要求：
        此实现调用add(size(), e) 。

        注意，此实现抛出UnsupportedOperationException除非add(int, E)被覆盖。

        参数
        e - 要附加到此列表的元素
        结果
        true （由 Collection.add(E)指定）
        异常
        UnsupportedOperationException - 如果此列表不支持 add操作
        ClassCastException - 如果指定元素的类阻止将其添加到此列表中
        NullPointerException - 如果指定的元素为null且此列表不允许null元素
        IllegalArgumentException - 如果此元素的某些属性阻止将其添加到此列表中

      • get

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

      • set

        public E set​(int index,             E element)
        用指定的元素替换此列表中指定位置的元素（可选操作）。
        Specified by:
        set接口 List<E>
        实现要求：
        此实现总是抛出 UnsupportedOperationException 。
        参数
        index - 要替换的元素的索引
        element - 要存储在指定位置的元素
        结果
        先前在指定位置的元素
        异常
        UnsupportedOperationException - 如果此列表不支持 set操作
        ClassCastException - 如果指定元素的类阻止将其添加到此列表中
        NullPointerException - 如果指定的元素为null且此列表不允许null元素
        IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此列表中
        IndexOutOfBoundsException - 如果索引超出范围（ index < 0 || index >= size() ）

      • add

        public void add​(int index,                E element)
        将指定元素插入此列表中的指定位置（可选操作）。 将当前位置的元素（如果有）和任何后续元素向右移动（将其添加到索引中）。
        Specified by:
        add接口 List<E>
        实现要求：
        此实现总是抛出 UnsupportedOperationException 。
        参数
        index - 要插入指定元素的索引
        element - 要插入的元素
        异常
        UnsupportedOperationException - 如果此列表不支持 add
        ClassCastException - 如果指定元素的类阻止将其添加到此列表中
        NullPointerException - 如果指定的元素为null且此列表不允许null元素
        IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此列表中
        IndexOutOfBoundsException - 如果索引超出范围（ index < 0 || index > size() ）

      • remove

        public E remove​(int index)
        删除此列表中指定位置的元素（可选操作）。 将任何后续元素向左移位（从索引中减去一个元素）。 返回从列表中删除的元素。
        Specified by:
        remove接口 List<E>
        实现要求：
        此实现总是抛出 UnsupportedOperationException 。
        参数
        index - 要删除的元素的索引
        结果
        先前在指定位置的元素
        异常
        UnsupportedOperationException - 如果此列表不支持 remove操作
        IndexOutOfBoundsException - 如果索引超出范围（ index < 0 || index >= size() ）

      • indexOf

        public int indexOf​(Object o)
        返回此列表中第一次出现的指定元素的索引，如果此列表不包含该元素，则返回-1。 更正式地，返回最低索引i如Objects.equals(o, get(i)) ，如果没有这样的索引则返回-1。
        Specified by:
        indexOf在接口 List<E>
        实现要求：
        此实现首先获取列表迭代器（使用listIterator() ）。 然后，它遍历列表，直到找到指定的元素或到达列表的末尾。
        参数
        o - 要搜索的元素
        结果
        此列表中第一次出现的指定元素的索引，如果此列表不包含该元素，则返回-1
        异常
        ClassCastException - 如果指定元素的类型与此列表不兼容（ optional ）
        NullPointerException - 如果指定的元素为null且此列表不允许null元素（ optional ）

      • lastIndexOf

        public int lastIndexOf​(Object o)
        返回此列表中指定元素最后一次出现的索引，如果此列表不包含该元素，则返回-1。 更正式的是，返回最高指数i如Objects.equals(o, get(i)) ，如果没有这样的指数则为-1。
        Specified by:
        lastIndexOf在接口 List<E>
        实现要求：
        此实现首先获取指向列表末尾的列表迭代器（使用listIterator(size()) ）。 然后，它在列表上向后迭代，直到找到指定的元素，或者到达列表的开头。
        参数
        o - 要搜索的元素
        结果
        此列表中指定元素最后一次出现的索引，如果此列表不包含该元素，则返回-1
        异常
        ClassCastException - 如果指定元素的类型与此列表不兼容（ optional ）
        NullPointerException - 如果指定的元素为null且此列表不允许null元素（ optional ）

      • clear

        public void clear()
        从此列表中删除所有元素（可选操作）。 此调用返回后，列表将为空。
        Specified by:
        clear接口 Collection<E>
        Specified by:
        clear在界面 List<E>
        重写：
        clear在类 AbstractCollection<E>
        实现要求：
        此实现调用removeRange(0, size()) 。

        请注意，除非重写remove(int index)或removeRange(int fromIndex, int toIndex)否则此实现会抛出UnsupportedOperationException 。

        异常
        UnsupportedOperationException - 如果此列表不支持 clear操作

      • addAll

        public boolean addAll​(int index,                      Collection<? extends E> c)
        将指定集合中的所有元素插入到指定位置的此列表中（可选操作）。 将当前位置的元素（如果有）和任何后续元素向右移动（增加其索引）。 新元素将按照指定集合的迭代器返回的顺序出现在此列表中。 如果在操作正在进行时修改了指定的集合，则此操作的行为是不确定的。 （请注意，如果指定的集合是此列表，则会发生这种情况，并且它是非空的。）
        Specified by:
        addAll ，接口 List<E>
        实现要求：
        此实现获取指定集合上的迭代器并对其进行迭代，使用add(int, E)将从迭代器获取的元素一次一个地插入到此列表中的适当位置。 许多实现将覆盖此方法以提高效率。

        注意，此实现抛出UnsupportedOperationException除非add(int, E)被覆盖。

        参数
        index - 从指定集合插入第一个元素的索引
        c - 包含要添加到此列表的元素的集合
        结果
        true如果此列表因呼叫而更改
        异常
        UnsupportedOperationException - 如果此列表不支持 addAll
        ClassCastException - 如果指定集合的元素的类阻止将其添加到此列表中
        NullPointerException - 如果指定的集合包含一个或多个null元素，并且此列表不允许null元素，或者指定的集合为null
        IllegalArgumentException - 如果指定集合的某个元素的某些属性阻止将其添加到此列表中
        IndexOutOfBoundsException - 如果索引超出范围（ index < 0 || index > size() ）

      • iterator

        public Iterator<E> iterator()
        以适当的顺序返回此列表中元素的迭代器。
        Specified by:
        iterator在接口 Collection<E>
        Specified by:
        iterator in interface Iterable<E>
        Specified by:
        iterator在接口 List<E>
        Specified by:
        iterator在类 AbstractCollection<E>
        实现要求：
        此实现返回一个简单的实现Iterator接口，依托后台列表的size() ， get(int)和remove(int)方法。

        请注意，此方法返回的迭代器将抛出UnsupportedOperationException以响应其remove方法，除非重写列表的remove(int)方法。

        如同（受保护） modCount字段的规范中所述，可以使该实现在并发修改时抛出运行时异常。

        结果
        以适当的顺序在此列表中的元素上的迭代器

      • listIterator

        public ListIterator<E> listIterator()
        返回此列表中元素的列表迭代器（按适当顺序）。
        Specified by:
        listIterator ，接口 List<E>
        实现要求：
        此实现返回 listIterator(0) 。
        结果
        列表中的元素列表迭代器（按正确顺序）
        另请参见：
        listIterator(int)

      • listIterator

        public ListIterator<E> listIterator​(int index)
        从列表中的指定位置开始，返回列表中元素的列表迭代器（按正确顺序）。 指定的索引指示初始调用next将返回的第一个元素。 对previous的初始调用将返回指定索引减去1的元素。
        Specified by:
        listIterator在界面 List<E>
        实现要求：
        此实现返回ListIterator接口的简单实现，该接口扩展了iterator()方法返回的Iterator接口的实现。 该ListIterator实现依赖于后台列表的get(int) ， set(int, E) ， add(int, E)和remove(int)方法。

        请注意，此实现返回的列表迭代器将抛出一个UnsupportedOperationException响应其remove ， set和add方法，除非列表的remove(int) ， set(int, E)和add(int, E)方法被覆盖。

        可以使该实现在并发修改时抛出运行时异常，如（受保护的） modCount字段的规范中所述。

        参数
        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和lastIndexOf构造类似的习语，并且可以将Collections类中的所有算法应用于子列表。

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

        Specified by:
        subList在界面 List<E>
        实现要求：
        此实现返回一个子类AbstractList的列表。 子类在私有字段中存储subList的大小（可以在其生命周期内更改），以及支持列表的预期值modCount 。 子类有两种变体，其中一种实现RandomAccess 。 如果此列表实现RandomAccess则返回的列表将是实现RandomAccess的子类的实例。

        子类的set(int, E) ， get(int) ， add(int, E) ， remove(int) ， addAll(int, Collection)和removeRange(int, int)方法都委托给支持抽象列表上的相应方法，边界检查的指标和调整偏移后。 addAll(Collection c)方法仅返回addAll(size, c) 。

        listIterator(int)方法在支持列表上的列表迭代器上返回“包装器对象”，该列表迭代器是使用支持列表上的相应方法创建的。 iterator方法仅返回listIterator() ，而size方法仅返回子类的size字段。

        所有方法首先检查后备列表的实际modCount是否等于其预期值，如果不是，则抛出ConcurrentModificationException 。

        参数
        fromIndex - fromIndex低端点（包括）
        toIndex - toIndex高端点（不包括）
        结果
        此列表中指定范围的视图
        异常
        IndexOutOfBoundsException - 如果端点索引值超出范围 (fromIndex < 0 || toIndex > size)
        IllegalArgumentException - 如果端点索引无序 (fromIndex > toIndex)

      • equals

        public boolean equals​(Object o)
        将指定对象与此列表进行比较以获得相等性。 当且仅当指定的对象也是列表时，返回true ，两个列表具有相同的大小，并且两个列表中的所有对应元素对都相等 。 （两个元件e1和e2是如果相等 (e1==null ? e2==null : e1.equals(e2)) ）。换句话说，两个列表被定义为等于如果它们包含以相同的顺序相同的元件。
        Specified by:
        equals在接口 Collection<E>
        Specified by:
        equals ，接口 List<E>
        重写：
        equals在课程 Object
        实现要求：
        此实现首先检查指定的对象是否为此列表。 如果是，则返回true ; 如果不是，它检查指定的对象是否是列表。 如果没有，则返回false ; 如果是这样，它迭代两个列表，比较相应的元素对。 如果任何比较返回false ，则此方法返回false 。 如果其中一个迭代器在另一个之前耗尽了元素，则返回false （因为列表的长度不等）; 否则在迭代完成时返回true 。
        参数
        o - 要与此列表进行相等性比较的对象
        结果
        true如果指定的对象等于此列表
        另请参见：
        Object.hashCode() ， HashMap

      • removeRange

        protected void removeRange​(int fromIndex,                           int toIndex)
        从此列表中删除索引介于fromIndex （含）和toIndex （独占）之间的所有元素。 将任何后续元素向左移动（降低其索引）。 此调用通过(toIndex - fromIndex)元素缩短列表。 （如果是toIndex==fromIndex ，则此操作无效。）

        此列表及其子列表上的clear操作调用此方法。 重写此方法以利用列表实现的内部可以显着提高此列表及其子列表上的clear操作的性能。

        实现要求：
        此实现变得定位之前的列表迭代fromIndex ，并反复调用ListIterator.next其次是ListIterator.remove ，直到整个范围内已被删除。 注意：如果ListIterator.remove需要线性时间，则此实现需要二次时间。
        参数
        fromIndex - 要删除的第一个元素的索引
        toIndex - 要删除的最后一个元素之后的索引