java.util
介面 List<E>

所有父級介面：

Collection<E>, Iterable<E>

所有已知實作類別：

AbstractList, AbstractSequentialList, ArrayList, AttributeList, CopyOnWriteArrayList, LinkedList, RoleList, RoleUnresolvedList, Stack, Vector

public interface List<E>
extends Collection<E>

有序的 collection（也稱為序列）。此介面的使用者可以對列表中每個元素的插入位置進行精確地控制。使用者可以根據元素的整數索引（在列表中的位置）存取元素，並搜尋列表中的元素。

與 set 不同，列表通常允許重複的元素。更確切地講，列表通常允許滿足 e1.equals(e2) 的元素對 e1 和 e2，並且如果列表本身允許 null 元素的話，通常它們允許多個 null 元素。難免有人希望通過在使用者嘗試插入重複元素時拋出運行時異常的方法來禁止重複的列表，但我們希望這種用法越少越好。

List 介面在 iterator、add、remove、equals 和 hashCode 方法的協定上加了一些其他約定，超過了 Collection 介面中指定的約定。為方便起見，這裡也包括了其他繼承方法的宣告。

List 介面提供了 4 種對列表元素進行定位（索引）存取方法。列表（像 Java 陣列一樣）是基於 0 的。注意，這些操作可能在和某些實作（例如 LinkedList 類別）的索引值成比例的時間內執行。因此，如果調用者不知道實作，那麼在列表元素上迭代通常優於用索引遍歷列表。

List 介面提供了特殊的迭代器，稱為 ListIterator，除了允許 Iterator 介面提供的正常操作外，該迭代器還允許元素插入和替換，以及雙向存取。還提供了一個方法來獲取從列表中指定位置開始的列表迭代器。

List 介面提供了兩種搜尋指定物件的方法。從性能的觀點來看，應該小心使用這些方法。在很多實作中，它們將執行高開銷的線性搜尋。

List 介面提供了兩種在列表的任意位置高效插入和移除多個元素的方法。

注意：儘管列表允許把自身作為元素包含在內，但建議要特別小心：在這樣的列表上，equals 和 hashCode 方法不再是定義良好的。

某些列表實作對列表可能包含的元素有限制。例如，某些實作禁止 null 元素，而某些實作則對元素的型別有限制。試圖添加不合格的元素會拋出未經檢查的異常，通常是 NullPointerException 或 ClassCastException。試圖查詢不合格的元素是否存在可能會拋出異常，也可能簡單地返回 false；某些實作會採用前一種行為，而某些則採用後者。概括地說，試圖對不合格元素執行操作時，如果完成該操作後不會導致在列表中插入不合格的元素，則該操作可能拋出一個異常，也可能成功，這取決於實作的選擇。此介面的規範中將這樣的異常標記為「可選」。

此介面是 Java Collections Framework 的成員。

從以下版本開始：

1.2

另請參見：

Collection, Set, ArrayList, LinkedList, Vector, Arrays.asList(Object[]), Collections.nCopies(int, Object), Collections.EMPTY_LIST, AbstractList, AbstractSequentialList

方法摘要

boolean	add(E e) 向列表的尾部添加指定的元素（可選操作）。
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() 從列表中移除所有元素（可選操作）。
boolean	contains(Object o) 如果列表包含指定的元素，則返回 true。
boolean	containsAll(Collection<?> c) 如果列表包含指定 collection 的所有元素，則返回 true。
boolean	equals(Object o) 比較指定的物件與列表是否相等。
E	get(int index) 返回列表中指定位置的元素。
int	hashCode() 返回列表的雜湊碼值。
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) 從列表中移除指定 collection 中包含的其所有元素（可選操作）。
boolean	retainAll(Collection<?> c) 僅在列表中保留指定 collection 中所包含的元素（可選操作）。
E	set(int index, E element) 用指定元素替換列表中指定位置的元素（可選操作）。
int	size() 返回列表中的元素數。
List<E>	subList(int fromIndex, int toIndex) 返回列表中指定的 fromIndex（包括 ）和 toIndex（不包括）之間的部分視圖。
Object[]	toArray() 返回按適當順序包含列表中的所有元素的陣列（從第一個元素到最後一個元素）。
<T> T[]	toArray(T[] a) 返回按適當順序（從第一個元素到最後一個元素）包含列表中所有元素的陣列；返回陣列的運行時型別是指定陣列的運行時型別。

方法詳細資訊

size

int size()

返回列表中的元素數。如果列表包含多於 Integer.MAX_VALUE 個元素，則返回 Integer.MAX_VALUE。

指定者：

介面 Collection<E> 中的 size

返回：

列表中的元素數

isEmpty

boolean isEmpty()

如果列表不包含元素，則返回 true。

指定者：

介面 Collection<E> 中的 isEmpty

返回：

如果列表不包含元素，則返回 true

contains

boolean contains(Object o)

如果列表包含指定的元素，則返回 true。更確切地講，當且僅當列表包含滿足 (o==null ? e==null : o.equals(e)) 的元素 e 時才返回 true。

指定者：

介面 Collection<E> 中的 contains

參數：

o - 要測試列表中是否存在的元素

返回：

如果列表包含指定的元素，則返回 true

拋出：

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

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

iterator

Iterator<E> iterator()

返回按適當順序在列表的元素上進行迭代的迭代器。

指定者：

介面 Collection<E> 中的 iterator

指定者：

介面 Iterable<E> 中的 iterator

返回：

按適當順序在列表的元素上進行迭代的迭代器

toArray

Object[] toArray()

返回按適當順序包含列表中的所有元素的陣列（從第一個元素到最後一個元素）。

由於此列表不維護對返回陣列的任何參考，因而它將是「安全的」。（換句話說，即使陣列支持此列表，此方法也必須分派一個新陣列）。因此，調用者可以隨意修改返回的陣列。

此方法充當基於陣列的 API 與基於 collection 的 API 之間的橋樑。

指定者：

介面 Collection<E> 中的 toArray

返回：

按適當順序包含該列表中所有元素的陣列

另請參見：

Arrays.asList(Object[])

toArray

<T> T[] toArray(T[] a)

返回按適當順序（從第一個元素到最後一個元素）包含列表中所有元素的陣列；返回陣列的運行時型別是指定陣列的運行時型別。如果指定陣列能容納列表，則在其中返回該列表。否則，分派具有指定陣列的運行時型別和此列表大小的新陣列。

如果指定陣列能容納列表，並剩餘空間（即陣列的元素比列表的多），那麼會將陣列中緊隨列表尾部的元素設置為 null。（只有 在調用者知道列表不包含任何 null 元素時此方法才能用於確定列表的長度）。

像 toArray() 方法一樣，此方法充當基於陣列的 API 與基於 collection 的 API 之間的橋樑。更進一步說，此方法允許對輸出陣列的運行時型別進行精確控制，在某些情況下，可以用來節省分派開銷。

假定 x 是只包含字元串的一個已知列表。以下程式碼用來將該列表轉儲到一個新分派的 String 陣列：

     String[] y = x.toArray(new String[0]);

注意，toArray(new Object[0]) 和 toArray() 在功能上是相同的。

指定者：

介面 Collection<E> 中的 toArray

參數：

a - 要存儲列表中元素的陣列，如果它足夠大的話；否則為此目的分派一個運行時型別相同的新陣列。

返回：

包含列表中元素的陣列

拋出：

ArrayStoreException - 如果指定陣列的運行時型別不是此列表中每個元素的運行時型別的父級類別型

NullPointerException - 如果指定陣列為 null

add

boolean add(E e)

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

支持該操作的列表可能對列表可以添加的元素有一些限制。特別是某些列表將拒絕添加 null 元素，其他列表將在可能添加的元素型別上施加限制。List 類別應該在它們的文檔中明確指定有關添加元素的所有限制。

指定者：

介面 Collection<E> 中的 add

參數：

e - 要添加到列表的元素

返回：

true（根據 Collection.add(E) 的規定）

拋出：

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

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

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

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

remove

boolean remove(Object o)

從此列表中移除第一次出現的指定元素（如果存在）（可選操作）。如果列表不包含元素，則不更改列表。更確切地講，移除滿足 (o==null ? get(i)==null : o.equals(get(i))) 的最低索引 i 的元素（如果存在這樣的元素）。如果此列表已包含指定元素（或者此列表由於調用而發生更改），則返回 true。

指定者：

介面 Collection<E> 中的 remove

參數：

o - 要從該列表中移除的元素，如果存在的話

返回：

如果列表包含指定的元素，則返回 true

拋出：

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

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

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

containsAll

boolean containsAll(Collection<?> c)

如果列表包含指定 collection 的所有元素，則返回 true。

指定者：

介面 Collection<E> 中的 containsAll

參數：

c - 要在列表中檢查其包含性的 collection

返回：

如果列表包含指定 collection 的所有元素，則返回 true

拋出：

ClassCastException - 如果指定 collection 中的一個或多個元素的型別和此列表不相容（可選）

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

另請參見：

contains(Object)

addAll

boolean addAll(Collection<? extends E> c)

添加指定 collection 中的所有元素到此列表的結尾，順序是指定 collection 的迭代器返回這些元素的順序（可選操作）。如果在操作正在進行中修改了指定的 collection，那麼此操作的行為是不確定的（注意，如果指定的 collection 是此列表，並且它是非空(null)的，則會發生這種情況。）

指定者：

介面 Collection<E> 中的 addAll

參數：

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

返回：

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

拋出：

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

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

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

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

另請參見：

add(Object)

addAll

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

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

參數：

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

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

返回：

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

拋出：

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

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

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

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

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

removeAll

boolean removeAll(Collection<?> c)

從列表中移除指定 collection 中包含的其所有元素（可選操作）。

指定者：

介面 Collection<E> 中的 removeAll

參數：

c - 套件含從此列表中移除的元素的 collection

返回：

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

拋出：

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

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

NullPointerException - 如果此列表包含一個 null 元素，並且指定的 collection 不允許 null 元素（可選），或者指定的 collection 為 null

另請參見：

remove(Object), contains(Object)

retainAll

boolean retainAll(Collection<?> c)

僅在列表中保留指定 collection 中所包含的元素（可選操作）。換句話說，該方法從列表中移除未包含在指定 collection 中的所有元素。

指定者：

介面 Collection<E> 中的 retainAll

參數：

c - 套件含將保留在此列表中的元素的 collection

返回：

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

拋出：

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

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

NullPointerException - 如果此列表包含一個 null 元素，並且指定的 collection 不允許 null 元素（可選），或者指定的 collection 為 null

另請參見：

remove(Object), contains(Object)

clear

void clear()

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

指定者：

介面 Collection<E> 中的 clear

拋出：

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

equals

boolean equals(Object o)

比較指定的物件與列表是否相等。當且僅當指定的物件也是一個列表、兩個列表有相同的大小，並且兩個列表中的所有相應的元素對相等 時才返回 true（ 如果 (e1==null ? e2==null :e1.equals(e2))，則兩個元素 e1 和 e2 是相等 的）。換句話說，如果所定義的兩個列表以相同的順序包含相同的元素，那麼它們是相等的。該定義確保了 equals 方法在 List 介面的不同實作間正常工作。

指定者：

介面 Collection<E> 中的 equals

覆寫：

類別 Object 中的 equals

參數：

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

返回：

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

另請參見：

Object.hashCode(), Hashtable

hashCode

int hashCode()

返回列表的雜湊碼值。列表的雜湊碼定義為以下計算的結果：

  int hashCode = 1;
  Iterator<E> i = list.iterator();
  while (i.hasNext()) {
      E obj = i.next();
      hashCode = 31*hashCode + (obj==null ? 0 : obj.hashCode());
  }
 

這確保了 list1.equals(list2) 意味著對於任何兩個列表 list1 和 list2 而言，可實作 list1.hashCode()==list2.hashCode()，正如 Object.hashCode() 的常規協定所要求的。

指定者：

介面 Collection<E> 中的 hashCode

覆寫：

類別 Object 中的 hashCode

返回：

此列表的雜湊碼值

另請參見：

Object.equals(Object), equals(Object)

get

E get(int index)

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

參數：

index - 要返回的元素的索引

返回：

列表中指定位置的元素

拋出：

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

set

E set(int index,
      E element)

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

參數：

index - 要替換的元素的索引

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

返回：

以前在指定位置的元素

拋出：

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

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

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

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

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

add

void add(int index,
         E element)

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

參數：

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

element - 要插入的元素

拋出：

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

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

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

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

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

remove

E remove(int index)

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

參數：

index - 要移除的元素的索引

返回：

以前在指定位置的元素

拋出：

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

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

indexOf

int indexOf(Object o)

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

參數：

o - 要搜尋的元素

返回：

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

拋出：

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

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

lastIndexOf

int lastIndexOf(Object o)

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

參數：

o - 要搜尋的元素

返回：

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

拋出：

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

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

listIterator

ListIterator<E> listIterator()

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

返回：

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

listIterator

ListIterator<E> listIterator(int index)

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

參數：

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

返回：

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

拋出：

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

subList

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

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

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

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

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

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

參數：

fromIndex - subList 的低端（包括）

toIndex - subList 的高端（不包括）

返回：

列表中指定範圍的視圖

拋出：

IndexOutOfBoundsException - 非法的端點值 (fromIndex < 0 || toIndex > size || fromIndex > toIndex)