java.util
類別 AbstractCollection<E>

java.lang.Object
  java.util.AbstractCollection<E>

所有已實作的介面：

Iterable<E>, Collection<E>

直接已知子類別：

AbstractList, AbstractQueue, AbstractSet, ArrayDeque

public abstract class AbstractCollection<E>
extends Object
implements Collection<E>

此類別提供 Collection 介面的骨幹實作，以最大限度地減少了實作此介面所需的工作。

要實作一個不可修改的 collection，程式人員只需擴展此類別，並提供 iterator 和 size 方法的實作。（iterator 方法返回的迭代器必須實作 hasNext 和 next。）

要實作可修改的 collection，程式人員必須另外覆寫此類別的 add 方法（否則，會拋出 UnsupportedOperationException），iterator 方法返回的迭代器還必須另外實作其 remove 方法。

按照 Collection 介面規範中的建議，程式人員通常應提供一個 void （無參數）和 Collection 建構子。

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

此類別是 Java Collections Framework 的成員。

從以下版本開始：

1.2

另請參見：

Collection

建構子摘要

protected

AbstractCollection() 唯一的建構子。

方法摘要

boolean	add(E e) 確保此 collection 套件含指定的元素（可選操作）。
boolean	addAll(Collection<? extends E> c) 將指定 collection 中的所有元素都添加到此 collection 中（可選操作）。
void	clear() 移除此 collection 中的所有元素（可選操作）。
boolean	contains(Object o) 如果此 collection 套件含指定的元素，則返回 true。
boolean	containsAll(Collection<?> c) 如果此 collection 套件含指定 collection 中的所有元素，則返回 true。
boolean	isEmpty() 如果此 collection 不包含元素，則返回 true。
abstract Iterator<E>	iterator() 返回在此 collection 中的元素上進行迭代的迭代器。
boolean	remove(Object o) 從此 collection 中移除指定元素的單個實例，如果存在的話（可選操作）。
boolean	removeAll(Collection<?> c) 移除此 collection 中那些也包含在指定 collection 中的所有元素（可選操作）。
boolean	retainAll(Collection<?> c) 僅保留此 collection 中那些也包含在指定 collection 的元素（可選操作）。
abstract int	size() 返回此 collection 中的元素數。
Object[]	toArray() 返回包含此 collection 中所有元素的陣列。
<T> T[]	toArray(T[] a) 返回包含此 collection 中所有元素的陣列；返回陣列的運行時型別與指定陣列的運行時型別相同。
String	toString() 返回此 collection 的字元串表示形式。

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

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

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

equals, hashCode

建構子詳細資訊

AbstractCollection

protected AbstractCollection()

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

方法詳細資訊

iterator

public abstract Iterator<E> iterator()

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

指定者：

介面 Iterable<E> 中的 iterator

指定者：

介面 Collection<E> 中的 iterator

返回：

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

size

public abstract int size()

從介面 Collection 複製的描述

返回此 collection 中的元素數。如果此 collection 套件含的元素大於 Integer.MAX_VALUE，則返回 Integer.MAX_VALUE。

指定者：

介面 Collection<E> 中的 size

返回：

此 collection 中的元素數

isEmpty

public boolean isEmpty()

如果此 collection 不包含元素，則返回 true。

此實作返回 size() == 0。

指定者：

介面 Collection<E> 中的 isEmpty

返回：

如果此 collection 不包含元素，則返回 true

contains

public boolean contains(Object o)

如果此 collection 套件含指定的元素，則返回 true。更確切地講，當且僅當此 collection 至少包含一個滿足 (o==null ? e==null : o.equals(e)) 的元素 e 時，返回 true。

此實作在 collection 中的元素上進行迭代，並依次檢查每個元素以確定其是否與指定的元素相等。

指定者：

介面 Collection<E> 中的 contains

參數：

o - 測試在此 collection 中是否存在的元素。

返回：

如果此 collection 套件含指定的元素，則返回 true

拋出：

ClassCastException - 如果指定元素的型別與此 collection 不相容（可選）。

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

toArray

public Object[] toArray()

返回包含此 collection 中所有元素的陣列。如果 collection 對其迭代器返回的元素順序做出了某些保證，那麼此方法必須以相同的順序返回這些元素。

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

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

此實作返回一個陣列，它包含此 collection 的迭代器返回的所有元素，這些元素的排列順序與陣列的連續元素存儲順序相同，都是從索引 0 開始。返回陣列的長度等於迭代器返回的元素數，即使此 collection 的大小發生更改也是如此，這種情況可能發生在 collection 允許在迭代期間進行共時修改時。size 方法只是作為一個優化提示被調用；即使迭代器返回不同的元素數，也會返回正確的結果。

此方法等效於：

 List<E> list = new ArrayList<E>(size());
 for (E e : this)
     list.add(e);
 return list.toArray();
 

指定者：

介面 Collection<E> 中的 toArray

返回：

包含此 collection 中所有元素的陣列

toArray

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

返回包含此 collection 中所有元素的陣列；返回陣列的運行時型別與指定陣列的運行時型別相同。如果指定的陣列能容納該 collection，則返回包含此 collection 元素的陣列。否則，將分派一個具有指定陣列的運行時型別和此 collection 大小的新陣列。

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

如果此 collection 對其迭代器返回的元素順序做出了某些保證，那麼此方法必須以相同的順序返回這些元素。

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

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

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

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

此實作返回一個陣列，它包含此 collection 的迭代器返回的所有元素，這些元素的排列順序與陣列的連續元素存儲順序相同，都是從索引 0 開始。如果迭代器返回的元素數太大，不適合指定陣列，則在新分派的陣列中返回這些元素，該陣列的長度等於迭代器返回的元素數，即使此 collection 的大小在進行迭代期間發生更改也是如此，這種情況可能發生在 collection 允許在迭代期間進行共時修改時。size 方法只是作為一個優化提示被調用；即使迭代器返回不同的元素數，也會返回正確的結果。

此方法等效於：

 List<E> list = new ArrayList<E>(size());
 for (E e : this)
     list.add(e);
 return list.toArray(a);
 

指定者：

介面 Collection<E> 中的 toArray

參數：

a - 存儲此 collection 元素的陣列（如果其足夠大）；否則，將為此分派一個具有相同運行時型別的新陣列。

返回：

包含此 collection 中所有元素的陣列

拋出：

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

NullPointerException - 如果指定的陣列為 null

add

public boolean add(E e)

確保此 collection 套件含指定的元素（可選操作）。如果此 collection 由於調用而發生更改，則返回 true。（如果此 collection 不允許有重複元素，並且已經包含了指定的元素，則返回 false。）

支持此操作的 collection 可以限制哪些元素能添加到此 collection 中來。需要特別指出的是，一些 collection 拒絕添加 null 元素，其他一些 collection 將對可以添加的元素型別強加限制。Collection 類別應該在其文檔中清楚地指定能添加哪些元素方面的所有限制。

如果 collection 由於某些原因（已經包含該元素的原因除外）拒絕添加特定的元素，那麼它必須 拋出一個異常（而不是返回 false）。這確保了在此調用返回後，collection 總是包含指定的元素。

此實作總是拋出一個 UnsupportedOperationException。

指定者：

介面 Collection<E> 中的 add

參數：

e - 確定此 collection 中是否存在的元素。

返回：

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

拋出：

UnsupportedOperationException - 如果此 collection 不支持 add 操作

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

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

IllegalArgumentException - 如果元素的某屬性不允許它添加到此 collection 中

IllegalStateException - 如果由於插入限制，元素不能在此時間添加

remove

public boolean remove(Object o)

從此 collection 中移除指定元素的單個實例，如果存在的話（可選操作）。更確切地講，如果此 collection 套件含一個或多個滿足 (o==null ? e==null : o.equals(e)) 的元素 e，則移除這樣的元素。如果此 collection 套件含指定的元素（或者此 collection 由於調用而發生更改），則返回 true 。

此實作在該 collection 上進行迭代，尋找指定的元素。如果找到該元素，那麼它會使用迭代器的 remove 方法從該 collection 中移除該元素。

注意，如果此 collection 的 iterator 方法所返回的迭代器無法實作 remove 方法，並且此 collection 套件含指定的物件，那麼此實作將拋出 UnsupportedOperationException。

指定者：

介面 Collection<E> 中的 remove

參數：

o - 要從此 collection 中移除的元素（如果存在）。

返回：

如果此調用將移除一個元素，則返回 true

拋出：

UnsupportedOperationException - 如果此 collection 不支持 remove 操作

ClassCastException - 如果指定元素的型別與此 collection 不相容（可選）

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

containsAll

public boolean containsAll(Collection<?> c)

如果此 collection 套件含指定 collection 中的所有元素，則返回 true。

此實作在指定的 collection 上進行迭代，依次檢查該迭代器返回的每個元素，查看其是否包含在此 collection 中。如果是，則返回 true；否則返回 false。

指定者：

介面 Collection<E> 中的 containsAll

參數：

c - 將檢查是否包含在此 collection 中的 collection

返回：

如果此 collection 套件含指定 collection 中的所有元素，則返回 true

拋出：

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

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

另請參見：

contains(Object)

addAll

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

將指定 collection 中的所有元素都添加到此 collection 中（可選操作）。如果在進行此操作的同時修改指定的 collection，那麼此操作行為是不確定的。（這意味著如果指定的 collection 是此 collection，並且此 collection 為非空(null)，那麼此調用的行為是不確定的。）

此實作在指定的 collection 上進行迭代，並依次將迭代器返回的每個物件添加到此 collection 中。

注意，除非覆寫 add，否則此實作將拋出 UnsupportedOperationException（假定指定的 collection 非空(null)）。

指定者：

介面 Collection<E> 中的 addAll

參數：

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

返回：

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

拋出：

UnsupportedOperationException - 如果此 collection 不支持 addAll 方法

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

NullPointerException - 如果指定 collection 套件含 null 元素，並且此 collection 不支持 null 元素，或者指定的 collection 為 null

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

IllegalStateException - 如果由於插入限制，不是所有的元素都能在此時間添加

另請參見：

add(Object)

removeAll

public boolean removeAll(Collection<?> c)

移除此 collection 中那些也包含在指定 collection 中的所有元素（可選操作）。此調用返回後，collection 中將不包含任何與指定 collection 相同的元素。

此實作在此 collection 上進行迭代，依次檢查該迭代器返回的每個元素，以查看其是否包含在指定的 collection 中。如果是，則使用迭代器的 remove 方法將其從此 collection 中移除。

注意，如果 iterator 方法返回的迭代器無法實作 remove 方法，並且此 collection 套件含一個或多個與指定 collection 共有的元素，那麼此實作將拋出 UnsupportedOperationException。

指定者：

介面 Collection<E> 中的 removeAll

參數：

c - 辦好要從此 collection 移除的元素的 collection

返回：

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

拋出：

UnsupportedOperationException - 如果此 collection 不支持 removeAll 方法

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

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

另請參見：

remove(Object), contains(Object)

retainAll

public boolean retainAll(Collection<?> c)

僅保留此 collection 中那些也包含在指定 collection 的元素（可選操作）。換句話說，移除此 collection 中未包含在指定 collection 中的所有元素。

此實作在此 collection 上進行迭代，依次檢查該迭代器返回的每個元素，以查看其是否包含在指定的 collection 中。如果不是，則使用迭代器的 remove 方法將其從此 collection 中移除。

注意，如果 iterator 方法返回的迭代器無法實作 remove 方法，並且此 collection 套件含一個或多個在指定 collection 中不存在的元素，那麼此實作將拋出 UnsupportedOperationException。

指定者：

介面 Collection<E> 中的 retainAll

參數：

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

返回：

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

拋出：

UnsupportedOperationException - 如果此 collection 不支持 retainAll 操作

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

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

另請參見：

remove(Object), contains(Object)

clear

public void clear()

移除此 collection 中的所有元素（可選操作）。此方法返回後，除非拋出一個異常。

此實作在此 collection 上進行迭代，並使用 Iterator.remove 操作移除每個元素。為了提高效率，多數實作可能會選擇覆寫此方法。

注意，如果此 collection 的 iterator 方法所返回的迭代器無法實作 remove 方法，並且此 collection 非空(null)，那麼此實作將拋出 UnsupportedOperationException。

指定者：

介面 Collection<E> 中的 clear

拋出：

UnsupportedOperationException - 如果此 collection 不支持 clear 操作

toString

public String toString()

返回此 collection 的字元串表示形式。該字元串表示形式由 collection 元素的列表組成，這些元素按其迭代器返回的順序排列，並用方括號 ("[]") 括起來。相鄰元素由字元 ", "（逗號加空格）分隔。通過 String.valueOf(Object) 可以將元素轉換成字元串。

覆寫：

類別 Object 中的 toString

返回：

此 collection 的字元串表示形式