java.util
介面 Set<E>

型別參數：

E - 此 set 所維護元素的型別

所有父級介面：

Collection<E>, Iterable<E>

所有已知子介面：

NavigableSet<E>, SortedSet<E>

所有已知實作類別：

AbstractSet, ConcurrentSkipListSet, CopyOnWriteArraySet, EnumSet, HashSet, JobStateReasons, LinkedHashSet, TreeSet

public interface Set<E>
extends Collection<E>

一個不包含重複元素的 collection。更確切地講，set 不包含滿足 e1.equals(e2) 的元素對 e1 和 e2，並且最多包含一個 null 元素。正如其名稱所暗示的，此介面模仿了數學上的 set 抽象。

在所有建構子以及 add、equals 和 hashCode 方法的協定上，Set 介面還加入了其他規定，這些規定超出了從 Collection 介面所繼承的內容。出於方便考慮，它還包括了其他繼承方法的宣告（這些宣告的規範已經專門針對 Set 介面進行了修改，但是沒有包含任何其他的規定）。

對這些建構子的其他規定是（不要奇怪），所有建構子必須創建一個不包含重複元素的 set（正如上面所定義的）。

註：如果將可變物件用作 set 元素，那麼必須極其小心。如果物件是 set 中某個元素，以一種影響 equals 比較的方式改變物件的值，那麼 set 的行為就是不確定的。此項禁止的一個特殊情況是不允許某個 set 套件含其自身作為元素。

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

此介面是 Java Collections Framework 的成員。

從以下版本開始：

1.2

另請參見：

Collection, List, SortedSet, HashSet, TreeSet, AbstractSet, Collections.singleton(java.lang.Object), Collections.EMPTY_SET

方法摘要

boolean	add(E e) 如果 set 中尚未存在指定的元素，則添加此元素（可選操作）。
boolean	addAll(Collection<? extends E> c) 如果 set 中沒有指定 collection 中的所有元素，則將其添加到此 set 中（可選操作）。
void	clear() 移除此 set 中的所有元素（可選操作）。
boolean	contains(Object o) 如果 set 套件含指定的元素，則返回 true。
boolean	containsAll(Collection<?> c) 如果此 set 套件含指定 collection 的所有元素，則返回 true。
boolean	equals(Object o) 比較指定對象與此 set 的相等性。
int	hashCode() 返回 set 的雜湊碼值。
boolean	isEmpty() 如果 set 不包含元素，則返回 true。
Iterator<E>	iterator() 返回在此 set 中的元素上進行迭代的迭代器。
boolean	remove(Object o) 如果 set 中存在指定的元素，則將其移除（可選操作）。
boolean	removeAll(Collection<?> c) 移除 set 中那些包含在指定 collection 中的元素（可選操作）。
boolean	retainAll(Collection<?> c) 僅保留 set 中那些包含在指定 collection 中的元素（可選操作）。
int	size() 返回 set 中的元素數（其容量）。
Object[]	toArray() 返回一個套件含 set 中所有元素的陣列。
<T> T[]	toArray(T[] a) 返回一個套件含此 set 中所有元素的陣列；返回陣列的運行時型別是指定陣列的型別。

方法詳細資訊

size

int size()

返回 set 中的元素數（其容量）。如果 set 套件含多個 Integer.MAX_VALUE 元素，則返回 Integer.MAX_VALUE。

指定者：

介面 Collection<E> 中的 size

返回：

此 set 中的元素數（其容量）

isEmpty

boolean isEmpty()

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

指定者：

介面 Collection<E> 中的 isEmpty

返回：

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

contains

boolean contains(Object o)

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

指定者：

介面 Collection<E> 中的 contains

參數：

o - 要測試此 set 中是否存在的元素

返回：

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

拋出：

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

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

iterator

Iterator<E> iterator()

返回在此 set 中的元素上進行迭代的迭代器。返回的元素沒有特定的順序（除非此 set 是某個提供順序保證的類別的實例）。

指定者：

介面 Collection<E> 中的 iterator

指定者：

介面 Iterable<E> 中的 iterator

返回：

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

toArray

Object[] toArray()

返回一個套件含 set 中所有元素的陣列。如果此 set 對其迭代器返回的元素的順序作出了某些保證，那麼此方法也必須按相同的順序返回這些元素。

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

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

指定者：

介面 Collection<E> 中的 toArray

返回：

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

toArray

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

返回一個套件含此 set 中所有元素的陣列；返回陣列的運行時型別是指定陣列的型別。如果指定的陣列能容納該 set，則它將在其中返回。否則，將分派一個具有指定陣列的運行時型別和此 set 大小的新陣列。

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

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

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

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

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

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

指定者：

介面 Collection<E> 中的 toArray

參數：

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

返回：

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

拋出：

ArrayStoreException - 如果指定陣列的運行時型別不是此 set 中所有元素的運行時型別的父級類別型

NullPointerException - 如果指定的陣列為 null

add

boolean add(E e)

如果 set 中尚未存在指定的元素，則添加此元素（可選操作）。更確切地講，如果此 set 沒有包含滿足 (e==null ? e2==null : e.equals(e2)) 的元素 e2，則向該 set 中添加指定的元素 e。如果此 set 已經包含該元素，則該調用不改變此 set 並返回 false。結合建構子上的限制，這就可以確保 set 永遠不包含重複的元素。

上述規定並未暗示 set 必須接受所有元素；set 可以拒絕添加任意特定的元素，包括 null，並拋出異常，這與 Collection.add 規範中所描述的一樣。每個 set 實作應該明確地記錄對其可能包含元素的所有限制。

指定者：

介面 Collection<E> 中的 add

參數：

e - 要添加到 set 中的元素

返回：

如果 set 尚未包含指定的元素，則返回 true

拋出：

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

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

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

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

remove

boolean remove(Object o)

如果 set 中存在指定的元素，則將其移除（可選操作）。更確切地講，如果此 set 中包含滿足 (o==null ? e==null : o.equals(e)) 的元素 e，則移除它。如果此 set 套件含指定的元素（或者此 set 由於調用而發生更改），則返回 true（一旦調用返回，則此 set 不再包含指定的元素）。

指定者：

介面 Collection<E> 中的 remove

參數：

o - 從 set 中移除的物件（如果存在）

返回：

如果此 set 套件含指定的物件，則返回 true

拋出：

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

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

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

containsAll

boolean containsAll(Collection<?> c)

如果此 set 套件含指定 collection 的所有元素，則返回 true。如果指定的 collection 也是一個 set，那麼當該 collection 是此 set 的子集 時返回 true。

指定者：

介面 Collection<E> 中的 containsAll

參數：

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

返回：

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

拋出：

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

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

另請參見：

contains(Object)

addAll

boolean addAll(Collection<? extends E> c)

如果 set 中沒有指定 collection 中的所有元素，則將其添加到此 set 中（可選操作）。如果指定的 collection 也是一個 set，則 addAll 操作會實際修改此 set，這樣其值是兩個 set 的一個並集。如果操作正在進行的同時修改了指定的 collection，則此操作的行為是不確定的。

指定者：

介面 Collection<E> 中的 addAll

參數：

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

返回：

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

拋出：

UnsupportedOperationException - 如果 set 不支持 addAll 操作

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

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

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

另請參見：

add(Object)

retainAll

boolean retainAll(Collection<?> c)

僅保留 set 中那些包含在指定 collection 中的元素（可選操作）。換句話說，移除此 set 中所有未包含在指定 collection 中的元素。如果指定的 collection 也是一個 set，則此操作會實際修改此 set，這樣其值是兩個 set 的一個交集。

指定者：

介面 Collection<E> 中的 retainAll

參數：

c - 套件含要保留到此 set 中的元素的 collection

返回：

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

拋出：

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

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

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

另請參見：

remove(Object)

removeAll

boolean removeAll(Collection<?> c)

移除 set 中那些包含在指定 collection 中的元素（可選操作）。如果指定的 collection 也是一個 set，則此操作會實際修改此 set，這樣其值是兩個 set 的一個不對稱差集。

指定者：

介面 Collection<E> 中的 removeAll

參數：

c - 套件含要從此 set 中移除的元素的 collection

返回：

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

拋出：

UnsupportedOperationException - 如果此 set 不支持 removeAll 操作

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

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

另請參見：

remove(Object), contains(Object)

clear

void clear()

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

指定者：

介面 Collection<E> 中的 clear

拋出：

UnsupportedOperationException - 如果此 set 不支持 clear 方法

equals

boolean equals(Object o)

比較指定對象與此 set 的相等性。如果指定的物件也是一個 set，兩個 set 的大小相同，並且指定 set 的所有成員都包含在此 set 中（或者，此 set 的所有成員都包含在指定的 set 中也一樣），則返回 true。此定義確保了 equals 方法可在不同的 set 介面實作間正常工作。

指定者：

介面 Collection<E> 中的 equals

覆寫：

類別 Object 中的 equals

參數：

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

返回：

如果指定的物件等於此 set，則返回 true

另請參見：

Object.hashCode(), Hashtable

hashCode

int hashCode()

返回 set 的雜湊碼值。一個 set 的雜湊碼定義為此 set 中所有元素的雜湊碼和，其中 null 元素的雜湊碼定義為零。這就確保對於任意兩個 set s1 和 s2 而言，s1.equals(s2) 就意味著 s1.hashCode()==s2.hashCode()，正如 Object.hashCode() 的常規協定所要求的那樣。

指定者：

介面 Collection<E> 中的 hashCode

覆寫：

類別 Object 中的 hashCode

返回：

此 set 的雜湊碼值

另請參見：

Object.equals(Object), equals(Object)