java.util
類別 AbstractList<E>

java.lang.Object
  java.util.AbstractCollection<E>
      java.util.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（無參數）和 collection 建構子。

與其他抽象 collection 實作不同，程式人員不必 提供迭代器實作；迭代器和列表迭代器由此類別在以下「隨機存取」方法上實作：get(int)、set(int, E)、add(int, E) 和 remove(int)。

此類別中每個非抽象方法的文檔詳細描述了其實作。如果要實作的 collection 允許更有效的實作，則可以覆寫所有這些方法。

此類別是 Java Collections Framework 的成員。

從以下版本開始：

1.2

欄位摘要

protected int

modCount 已從結構上修改 此列表的次數。

建構子摘要

protected

AbstractList() 唯一的建構子。

方法摘要

boolean	add(E e) 將指定的元素添加到此列表的尾部（可選操作）。
void	add(int index, E element) 在列表的指定位置插入指定元素（可選操作）。
boolean	addAll(int index, Collection<? extends E> c) 將指定 collection 中的所有元素都插入到列表中的指定位置（可選操作）。
void	clear() 從此列表中移除所有元素（可選操作）。
boolean	equals(Object o) 將指定的物件與此列表進行相等性比較。
abstract E	get(int index) 返回列表中指定位置的元素。
int	hashCode() 返回此列表的雜湊碼值。
int	indexOf(Object o) 返回此列表中第一次出現的指定元素的索引；如果此列表不包含該元素，則返回 -1。
Iterator<E>	iterator() 返回以恰當順序在此列表的元素上進行迭代的迭代器。
int	lastIndexOf(Object o) 返回此列表中最後出現的指定元素的索引；如果列表不包含此元素，則返回 -1。
ListIterator<E>	listIterator() 返回此列表元素的列表迭代器（按適當順序）。
ListIterator<E>	listIterator(int index) 返回列表中元素的列表迭代器（按適當順序），從列表的指定位置開始。
E	remove(int index) 移除列表中指定位置的元素（可選操作）。
protected void	removeRange(int fromIndex, int toIndex) 從此列表中移除索引在 fromIndex（包括）和 toIndex（不包括）之間的所有元素。
E	set(int index, E element) 用指定元素替換列表中指定位置的元素（可選操作）。
List<E>	subList(int fromIndex, int toIndex) 返回列表中指定的 fromIndex（包括 ）和 toIndex（不包括）之間的部分視圖。

從類別 java.util.AbstractCollection 繼承的方法

addAll, contains, containsAll, isEmpty, remove, removeAll, retainAll, size, toArray, toArray, toString

從類別 java.lang.Object 繼承的方法

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

從介面 java.util.List 繼承的方法

addAll, contains, containsAll, isEmpty, remove, removeAll, retainAll, size, toArray, toArray

欄位詳細資訊

modCount

protected transient int modCount

已從結構上修改 此列表的次數。從結構上修改是指更改列表的大小，或者打亂列表，從而使正在進行的迭代產生錯誤的結果。

此欄位由 iterator 和 listIterator 方法返回的迭代器和列表迭代器實作使用。如果意外更改了此欄位中的值，則迭代器（或列表迭代器）將拋出 ConcurrentModificationException 來回應 next、remove、previous、set 或 add 操作。在迭代期間面臨共時修改時，它提供了快速失敗 行為，而不是非確定性行為。

子類別是否使用此欄位是可選的。如果子類別希望提供快速失敗迭代器（和列表迭代器），則它只需在其 add(int, E) 和 remove(int) 方法（以及它所覆寫的、導致列表結構上修改的任何其他方法）中增加此欄位。對 add(int, E) 或 remove(int) 的單個調用向此欄位添加的數量不得超過 1，否則迭代器（和列表迭代器）將拋出虛假的 ConcurrentModificationExceptions。如果某個實作不希望提供快速失敗迭代器，則可以忽略此欄位。

建構子詳細資訊

AbstractList

protected AbstractList()

唯一的建構子。（由子類別建構子調用，通常是隱式的。）

方法詳細資訊

add

public boolean add(E e)

將指定的元素添加到此列表的尾部（可選操作）。

支持此操作的列表可能對列表可以添加的元素做出一些限制。具體來說，某些列表將拒絕添加 null 元素，另一些列表將在可以添加的元素型別上施加限制。List 類別應該在它們的文檔中明確指定可以添加何種元素的所有限制。

此實作調用 add(size(), e)。

注意，除非覆寫 add(int, E)，否則此實作將拋出 UnsupportedOperationException。

指定者：

介面 Collection<E> 中的 add

指定者：

介面 List<E> 中的 add

覆寫：

類別 AbstractCollection<E> 中的 add

參數：

e - 將添加到此列表的元素

返回：

true（正如 Collection.add(E) 所指定的那樣）

拋出：

UnsupportedOperationException - 如果此列表不支持 add 操作

ClassCastException - 如果指定元素的類別不允許將該元素添加到此列表

NullPointerException - 如果指定元素為 null 並且此列表不允許使用 null 元素

IllegalArgumentException - 如果此元素的某些屬性不允許將該元素添加到此列表

get

public abstract E get(int index)

返回列表中指定位置的元素。

指定者：

介面 List<E> 中的 get

參數：

index - 要返回的元素的索引

返回：

列表中指定位置的元素

拋出：

IndexOutOfBoundsException - 如果索引超出範圍 (index < 0 || index >= size())

set

public E set(int index,
             E element)

用指定元素替換列表中指定位置的元素（可選操作）。

此實作始終拋出 UnsupportedOperationException。

指定者：

介面 List<E> 中的 set

參數：

index - 要替換的元素的索引

element - 要在指定位置存儲的元素

返回：

以前在指定位置的元素

拋出：

UnsupportedOperationException - 如果列表不支持 set 操作

ClassCastException - 如果指定元素的類別不允許它添加到此列表

NullPointerException - 如果指定的元素為 null，並且此列表不允許 null 元素

IllegalArgumentException - 如果指定元素的某些屬性不允許它添加到此列表

IndexOutOfBoundsException - 如果索引超出範圍 (index < 0 || index >= size())

add

public void add(int index,
                E element)

在列表的指定位置插入指定元素（可選操作）。將當前處於該位置的元素（如果有的話）和所有後續元素向右移動（在其索引中加 1）。

此實作始終拋出 UnsupportedOperationException。

指定者：

介面 List<E> 中的 add

參數：

index - 要在其中插入指定元素處的索引

element - 要插入的元素

拋出：

UnsupportedOperationException - 如果列表不支持 add 操作

ClassCastException - 如果指定元素的類別不允許它添加到此列表

NullPointerException - 如果指定的元素為 null，並且此列表不允許 null 元素

IllegalArgumentException - 如果指定元素的某些屬性不允許它添加到此列表

IndexOutOfBoundsException - 如果索引超出範圍 (index < 0 || index > size())

remove

public E remove(int index)

移除列表中指定位置的元素（可選操作）。將所有的後續元素向左移動（將其索引減 1）。返回從列表中移除的元素。

此實作始終拋出 UnsupportedOperationException。

指定者：

介面 List<E> 中的 remove

參數：

index - 要移除的元素的索引

返回：

以前在指定位置的元素

拋出：

UnsupportedOperationException - 如果列表不支持 remove 操作

IndexOutOfBoundsException - 如果索引超出範圍 (index < 0 || index >= size())

indexOf

public int indexOf(Object o)

返回此列表中第一次出現的指定元素的索引；如果此列表不包含該元素，則返回 -1。更確切地講，返回滿足 (o==null ? get(i)==null : o.equals(get(i))) 的最低索引 i；如果沒有這樣的索引，則返回 -1。

此實作首先獲取一個列表迭代器（使用 listIterator()）。然後它迭代列表，直至找到指定的元素，或者到達列表的末尾。

指定者：

介面 List<E> 中的 indexOf

參數：

o - 要搜尋的元素

返回：

此列表中第一次出現的指定元素的索引，如果列表不包含該元素，則返回 -1

拋出：

ClassCastException - 如果指定元素的型別和此列表不相容（可選）

NullPointerException - 如果指定的元素是 null，並且此列表不允許 null 元素（可選）

lastIndexOf

public int lastIndexOf(Object o)

返回此列表中最後出現的指定元素的索引；如果列表不包含此元素，則返回 -1。更確切地講，返回滿足 (o==null ? get(i)==null : o.equals(get(i))) 的最高索引 i；如果沒有這樣的索引，則返回 -1。

此實作首先獲取一個指向列表末尾的列表迭代器（使用 listIterator(size())）。然後它逆向迭代列表，直至找到指定的元素，或者到達列表的開頭。

指定者：

介面 List<E> 中的 lastIndexOf

參數：

o - 要搜尋的元素

返回：

列表中最後出現的指定元素的索引；如果列表不包含此元素，則返回 -1

拋出：

ClassCastException - 如果指定元素的型別和此列表不相容（可選）

NullPointerException - 如果指定的元素是 null，並且此列表不允許 null 元素（可選）

clear

public void clear()

從此列表中移除所有元素（可選操作）。此調用返回後，列表將為空。

此實作調用 removeRange(0, size())。

注意，除非覆寫 remove(int index) 或 removeRange(int fromIndex, int toIndex)，否則此實作將拋出 UnsupportedOperationException。

指定者：

介面 Collection<E> 中的 clear

指定者：

介面 List<E> 中的 clear

覆寫：

類別 AbstractCollection<E> 中的 clear

拋出：

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

addAll

public boolean addAll(int index,
                      Collection<? extends E> c)

將指定 collection 中的所有元素都插入到列表中的指定位置（可選操作）。將當前處於該位置的元素（如果有的話）和所有後續元素向右移動（增加其索引）。新元素將按照它們通過指定 collection 的迭代器所返回的順序出現在此列表中。如果在操作正在進行中修改了指定的 collection，那麼該操作的行為是不確定的（注意，如果指定的 collection 是此列表，並且它是非空(null)的，則會發生這種情況。）

此實作獲取指定 collection 上的迭代器并迭代它，使用 add(int, E) 將迭代器獲取的元素插入此列表的適當位置，一次一個。為了提高效率，多數實作將覆寫此方法。

注意，除非覆寫 add(int, E)，否則此實作將拋出 UnsupportedOperationException。

指定者：

介面 List<E> 中的 addAll

參數：

index - 將指定 collection 的第一個元素所插入位置的索引

c - 套件含要添加到此列表的元素的 collection

返回：

如果此列表由於調用而發生更改，則返回 true

拋出：

UnsupportedOperationException - 如果列表不支持 addAll 操作

ClassCastException - 如果指定 collection 中某個元素的類別不允許它添加到此列表

NullPointerException - 如果指定的 collection 套件含一個或多個 null 元素，並且該列表不允許 null 元素，或者指定的 collection 為 null

IllegalArgumentException - 如果指定 collection 的元素的某些屬性不允許它添加到此列表

IndexOutOfBoundsException - 如果索引超出範圍 (index < 0 || index > size())

iterator

public Iterator<E> iterator()

返回以恰當順序在此列表的元素上進行迭代的迭代器。

此實作返回 iterator 介面的一個直接實作，具體取決於底層實作列表的 size()、get(int) 和 remove(int) 方法。

注意，除非覆寫列表的 remove(int) 方法，否則此方法返回的迭代器將拋出一個 UnsupportedOperationException 來回應其 remove 方法。

根據 (protected) modCount 欄位規範中的描述，在面臨共時修改時，可以使此實作拋出運行時異常。

指定者：

介面 Iterable<E> 中的 iterator

指定者：

介面 Collection<E> 中的 iterator

指定者：

介面 List<E> 中的 iterator

指定者：

類別 AbstractCollection<E> 中的 iterator

返回：

在此 collection 中的元素上進行迭代的迭代器。

另請參見：

modCount

listIterator

public ListIterator<E> listIterator()

返回此列表元素的列表迭代器（按適當順序）。

指定者：

介面 List<E> 中的 listIterator

返回：

此列表中的元素的迭代器（按適當順序）。

此實作返回 listIterator(0)。

另請參見：

listIterator(int)

listIterator

public ListIterator<E> listIterator(int index)

返回列表中元素的列表迭代器（按適當順序），從列表的指定位置開始。指定的索引表示 next 的初始調用所返回的第一個元素。previous 方法的初始調用將返回索引比指定索引少 1 的元素。

此實作返回 ListIterator 介面的直接實作，擴展了由 iterator() 方法返回的 Iterator 介面的實作。ListIterator 實作依賴於底層實作列表的 get(int)、set(int, E)、add(int, E) 和 remove(int) 方法。

注意，除非覆寫列表的 remove(int)、set(int, E) 和 add(int, E) 方法，否則此實作返回的列表迭代器將拋出 UnsupportedOperationException 來回應其 remove、set 和 add 方法。

根據 (protected) modCount 欄位規範中的描述，在面臨共時修改時，可以使此實作拋出運行時異常。

指定者：

介面 List<E> 中的 listIterator

參數：

index - 從列表迭代器返回的第一個元素的索引（通過調用 next 方法）

返回：

此列表中元素的列表迭代器（按適當順序），從列表中的指定位置開始

拋出：

IndexOutOfBoundsException - 如果索引超出範圍 (index < 0 || index > size())

另請參見：

modCount

subList

public List<E> subList(int fromIndex,
                       int toIndex)

返回列表中指定的 fromIndex（包括 ）和 toIndex（不包括）之間的部分視圖。（如果 fromIndex 和 toIndex 相等，則返回的列表為空）。返回的列表由此列表支持，因此返回列表中的非結構性更改將反映在此列表中，反之亦然。返回的列表支持此列表支持的所有可選列表操作。

此方法省去了顯式範圍操作（此操作通常針對陣列存在）。通過傳遞 subList 視圖而非整個列表，期望列表的任何操作可用作範圍操作。例如，下面的語句從列表中移除了元素的範圍：

            list.subList(from, to).clear();
 

可以對 indexOf 和 lastIndexOf 建構類似的語句，而且 Collections 類別中的所有演算法都可以應用於 subList。

如果支持列表（即此列表）通過任何其他方式（而不是通過返回的列表）從結構上修改，則此方法返回的列表語義將變為未定義（從結構上修改是指更改列表的大小，或者以其他方式打亂列表，使正在進行的迭代產生錯誤的結果）。

此實作返回一個子類別化 AbstractList 的列表。子類別在 private 欄位中存儲底層實作列表中 subList 的偏移量、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。

指定者：

介面 List<E> 中的 subList

參數：

fromIndex - subList 的低端（包括）

toIndex - subList 的高端（不包括）

返回：

列表中指定範圍的視圖

拋出：

IndexOutOfBoundsException - 端點索引值超出範圍 (fromIndex < 0 || toIndex > size)

IllegalArgumentException - 端點索引順序顛倒 (fromIndex > toIndex)

equals

public boolean equals(Object o)

將指定的物件與此列表進行相等性比較。當且僅當指定的物件也是一個列表，兩個列表具有相同的大小，而且兩個列表中所有相應的元素對都相等 時，才返回 true。（如果 (e1==null ? e2==null : e1.equals(e2))，則元素 e1 和 e2 相等。）換句話說，如果兩個列表包含相同的元素，且元素的順序也相同，才將它們定義為相等。

此實作首先檢查指定的物件是否為此列表。如果是，則返回 true；否則，它將檢查指定的物件是否為一個列表。如果不是，它將返回 false；如果是，它將迭代兩個列表，比較相應的元素對。如果有任何比較結果返回 false，則此方法將返回 false。如果某中某個迭代器在另一迭代器之前迭代完元素，則會返回 false（因為列表是不等長的）；否則，在迭代完成時將返回 true。

指定者：

介面 Collection<E> 中的 equals

指定者：

介面 List<E> 中的 equals

覆寫：

類別 Object 中的 equals

參數：

o - 與此列表進行相等性比較的物件。

返回：

如果指定對象與此列表相等，則返回 true。

另請參見：

Object.hashCode(), Hashtable

hashCode

public int hashCode()

返回此列表的雜湊碼值。

此實作使用在 List.hashCode() 方法的文檔中用於定義列表雜湊函數的程式碼。

指定者：

介面 Collection<E> 中的 hashCode

指定者：

介面 List<E> 中的 hashCode

覆寫：

類別 Object 中的 hashCode

返回：

此列表的雜湊碼值

另請參見：

Object.equals(java.lang.Object), Hashtable

removeRange

protected void removeRange(int fromIndex,
                           int toIndex)

從此列表中移除索引在 fromIndex（包括）和 toIndex（不包括）之間的所有元素。向左移動所有後續元素（減小其索引）。此調用縮短了 ArrayList，將其減少了 (toIndex - fromIndex) 個元素。（如果 toIndex==fromIndex，則此操作無效。）

此方法由此列表及其 subList 上的 clear 操作調用。覆寫此方法以利用內部列表實作可以極大地 改進此列表及其 subList 上 clear 操作的性能。

此實作獲取一個位於 fromIndex 之前的列表迭代器，並在移除該範圍內的元素前重複調用 ListIterator.next（後跟 ListIterator.remove）。註：如果 ListIterator.remove 需要的時間與元素數呈線性關係，那麼此實作需要的時間與元素數的平方呈線性關係。

參數：

fromIndex - 要移除的第一個元素的索引。

toIndex - 要移除的最後一個元素之後的索引。