鴻蒙OS Set

Set

public interface Set<E>
extends Collection<E>

不包含重復(fù)元素的集合。 更正式地說，集合不包含一對(duì)元素 e1 和 e2 使得 e1.equals(e2)，并且最多包含一個(gè)空元素。 正如它的名字所暗示的，這個(gè)接口模擬了數(shù)學(xué)集合抽象。

除了從 Collection 接口繼承的那些之外，Set 接口對(duì)所有構(gòu)造函數(shù)的合約以及 add、equals 和 hashCode 方法的合約進(jìn)行了額外的規(guī)定。 為方便起見，此處還包括其他繼承方法的聲明。 （這些聲明隨附的規(guī)范已針對(duì) Set 接口進(jìn)行了定制，但它們不包含任何附加規(guī)定。）

毫不奇怪，對(duì)構(gòu)造函數(shù)的附加規(guī)定是，所有構(gòu)造函數(shù)都必須創(chuàng)建一個(gè)不包含重復(fù)元素的集合（如上所述）。

注意：如果將可變對(duì)象用作集合元素，則必須非常小心。如果對(duì)象的值以影響等于比較的方式更改，而對(duì)象是集合中的一個(gè)元素，則不指定集合的行為。此禁令的一個(gè)特殊情況是不允許集合包含自身作為元素。

一些集合實(shí)現(xiàn)對(duì)它們可能包含的元素有限制。例如，一些實(shí)現(xiàn)禁止空元素，而一些實(shí)現(xiàn)對(duì)其元素的類型有限制。嘗試添加不合格的元素會(huì)引發(fā)未經(jīng)檢查的異常，通常是 NullPointerException 或 ClassCastException。嘗試查詢不合格元素的存在可能會(huì)引發(fā)異常，或者它可能只是返回 false；一些實(shí)現(xiàn)會(huì)表現(xiàn)出前一種行為，而另一些會(huì)表現(xiàn)出后者。更一般地，嘗試對(duì)不合格元素執(zhí)行操作，該不合格元素的完成不會(huì)導(dǎo)致將不合格元素插入集合中，這可能會(huì)引發(fā)異常，也可能會(huì)成功，這取決于實(shí)現(xiàn)的選擇。此類異常在此接口的規(guī)范中被標(biāo)記為“可選”。

此接口是 Java 集合框架的成員。

方法總結(jié)

修飾符和類型	方法	描述
boolean	add(E e)	如果指定元素尚不存在，則將其添加到此集合中（可選操作）。
boolean	addAll(Collection<? extends E> c)	如果指定集合中的所有元素尚不存在，則將它們添加到此集合中（可選操作）。
void	clear()	從此集合中移除所有元素（可選操作）。
boolean	contains(Object o)	如果此集合包含指定的元素，則返回 true。
boolean	containsAll(Collection<?> c)	如果此集合包含指定集合的所有元素，則返回 true。
boolean	equals(Object o)	比較指定對(duì)象與此集合是否相等。
int	hashCode()	返回此集合的哈希碼值。
boolean	isEmpty()	如果此集合不包含任何元素，則返回 true。
IteratorE	iterator()	返回此集合中元素的迭代器。
boolean	remove(Object o)	如果存在，則從此集合中刪除指定的元素（可選操作）。
boolean	removeAll(Collection<?> c)	從此集合中刪除指定集合中包含的所有元素（可選操作）。
boolean	retainAll(Collection<?> c)	僅保留此集合中包含在指定集合中的元素（可選操作）。
int	size()	返回此集合中的元素?cái)?shù)（其基數(shù)）。
default SpliteratorE	spliterator()	在此集合中的元素上創(chuàng)建一個(gè) Spliterator。
Object[]	toArray()	返回一個(gè)包含此集合中所有元素的數(shù)組。
<T> T[]	toArray(T[] a)	返回一個(gè)包含該集合中所有元素的數(shù)組； 返回?cái)?shù)組的運(yùn)行時(shí)類型是指定數(shù)組的運(yùn)行時(shí)類型。

從接口 java.util.Collection 繼承的方法
parallelStream, removeIf, stream

從接口 java.lang.Iterable 繼承的方法
forEach

方法詳情

size

int size()

返回此集合中的元素?cái)?shù)（其基數(shù)）。 如果此集合包含多個(gè) Integer.MAX_VALUE 元素，則返回 Integer.MAX_VALUE。

指定者：

接口 CollectionE 中的大小

返回:

該集合中的元素?cái)?shù)量（其基數(shù)）

isEmpty

boolean isEmpty()

如果此集合不包含任何元素，則返回 true。

指定者：

接口 CollectionE 中的 isEmpty

返回:

如果此集合不包含任何元素，則為 true

contains

boolean contains(Object o)

如果此集合包含指定的元素，則返回 true。 更正式地說，當(dāng)且僅當(dāng)此集合包含滿足 (o==null ? e==null : o.equals(e)) 的元素 e 時(shí)才返回 true。

指定者：

包含在接口 CollectionE 中

參數(shù)：

參數(shù)名稱	參數(shù)描述
o	要測(cè)試其在該集合中的存在的元素

返回:

如果此集合包含指定元素，則為 true

Throws:

Throw名稱	Throw描述
ClassCastException	如果指定元素的類型與此集合不兼容（可選）
NullPointerException	如果指定元素為空且此集合不允許空元素（可選）

iterator

IteratorE iterator()

返回此集合中元素的迭代器。 返回的元素沒有特定的順序（除非這個(gè)集合是某個(gè)提供保證的類的實(shí)例）。

指定者：

接口 CollectionE 中的迭代器

指定者：

接口 IterableE 中的迭代器

返回:

此集合中元素的迭代器

toArray

Object[] toArray()

返回一個(gè)包含此集合中所有元素的數(shù)組。 如果此集合對(duì)其迭代器返回其元素的順序做出任何保證，則此方法必須以相同的順序返回元素。

返回的數(shù)組將是“安全的”，因?yàn)樵摷喜痪S護(hù)對(duì)它的引用。 （換句話說，即使這個(gè)集合是由一個(gè)數(shù)組支持的，這個(gè)方法也必須分配一個(gè)新數(shù)組）。 因此，調(diào)用者可以自由修改返回的數(shù)組。

此方法充當(dāng)基于數(shù)組和基于集合的 API 之間的橋梁。

指定者：

接口 CollectionE 中的 toArray

返回:

包含此集合中所有元素的數(shù)組

toArray

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

返回一個(gè)包含該集合中所有元素的數(shù)組；返回?cái)?shù)組的運(yùn)行時(shí)類型是指定數(shù)組的運(yùn)行時(shí)類型。如果集合適合指定的數(shù)組，則在其中返回。否則，將使用指定數(shù)組的運(yùn)行時(shí)類型和該集合的大小分配一個(gè)新數(shù)組。

如果此集合適合指定的數(shù)組并有剩余空間（即，數(shù)組的元素比此集合多），則數(shù)組中緊跟集合末尾的元素設(shè)置為 null。 （只有當(dāng)調(diào)用者知道這個(gè)集合不包含任何空元素時(shí)，這在確定這個(gè)集合的長(zhǎng)度時(shí)才有用。）

如果此集合對(duì)其迭代器返回其元素的順序做出任何保證，則此方法必須以相同的順序返回元素。

與 toArray() 方法一樣，此方法充當(dāng)基于數(shù)組的 API 和基于集合的 API 之間的橋梁。此外，此方法允許對(duì)輸出數(shù)組的運(yùn)行時(shí)類型進(jìn)行精確控制，并且在某些情況下可用于節(jié)省分配成本。

假設(shè) x 是一個(gè)已知只包含字符串的集合。以下代碼可用于將集合轉(zhuǎn)儲(chǔ)到新分配的字符串?dāng)?shù)組中：

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

請(qǐng)注意，toArray(new Object[0]) 在功能上與 toArray() 相同。

指定者：

接口 CollectionE 中的 toArray

類型參數(shù)：

類型參數(shù)名稱	類型參數(shù)描述
T	包含集合的數(shù)組的運(yùn)行時(shí)類型

參數(shù):

參數(shù)名稱	參數(shù)描述
a	這個(gè)集合的元素要存儲(chǔ)到的數(shù)組，如果它足夠大的話； 否則，將為此目的分配相同運(yùn)行時(shí)類型的新數(shù)組。

返回:

包含此集合中所有元素的數(shù)組

Throws:

Throw名稱	Throw描述
ArrayStoreException	如果指定數(shù)組的運(yùn)行時(shí)類型不是此集合中每個(gè)元素的運(yùn)行時(shí)類型的超類型
NullPointerException	如果指定的數(shù)組為空

add

boolean add(E e)

如果指定元素尚不存在，則將其添加到此集合中（可選操作）。 更正式地說，如果集合不包含元素 e2，則將指定的元素 e 添加到此集合中，使得 (e==null ? e2==null : e.equals(e2))。 如果該集合已包含該元素，則調(diào)用將保持該集合不變并返回 false。 結(jié)合對(duì)構(gòu)造函數(shù)的限制，這確保了集合永遠(yuǎn)不會(huì)包含重復(fù)的元素。

上述規(guī)定并不意味著集合必須接受所有元素； 集合可以拒絕添加任何特定元素，包括 null，并拋出異常，如 Collection#add 規(guī)范中所述。 單獨(dú)的集合實(shí)現(xiàn)應(yīng)該清楚地記錄對(duì)它們可能包含的元素的任何限制。

指定者：

添加接口CollectionE

參數(shù)：

參數(shù)名稱	參數(shù)描述
e	要添加到此集合的元素

返回:

如果此集合尚未包含指定元素，則為 true

Throws:

Throw名稱	Throw描述
UnsupportedOperationException	如果此集合不支持添加操作
ClassCastException	如果指定元素的類阻止它被添加到這個(gè)集合中
NullPointerException	如果指定元素為空且此集合不允許空元素
IllegalArgumentException	如果指定元素的某些屬性阻止它被添加到此集合中

remove

boolean remove(Object o)

如果存在，則從此集合中刪除指定的元素（可選操作）。 更正式地說，如果這個(gè)集合包含這樣一個(gè)元素，則刪除一個(gè)元素 e 使得 (o==null ? e==null : o.equals(e))。 如果此 set 包含該元素（或等效地，如果此 set 由于調(diào)用而更改），則返回 true。 （一旦調(diào)用返回，該集合將不包含該元素。）

指定者：

在接口 CollectionE 中刪除

參數(shù)：

參數(shù)名稱	參數(shù)描述
o	要從此集合中刪除的對(duì)象（如果存在）

返回:

如果此集合包含指定的元素，則為 true

Throws:

Throw名稱	Throw描述
ClassCastException	如果指定元素的類型與此集合不兼容（可選）
NullPointerException	如果指定元素為空且此集合不允許空元素（可選）
UnsupportedOperationException	如果此 set 不支持刪除操作

containsAll

boolean containsAll(Collection<?> c)

如果此集合包含指定集合的所有元素，則返回 true。 如果指定的集合也是一個(gè)集合，如果它是這個(gè)集合的子集，則此方法返回 true。

指定者：

接口 CollectionE 中的 containsAll

參數(shù)：

參數(shù)名稱	參數(shù)描述
c	要檢查此集合中包含的集合

返回:

如果此集合包含指定集合的所有元素，則為 true

Throws:

Throw名稱	Throw描述
ClassCastException	如果指定集合中的一個(gè)或多個(gè)元素的類型與該集合不兼容（可選）
NullPointerException	如果指定的集合包含一個(gè)或多個(gè)空元素并且此集合不允許空元素（可選），或者指定的集合為空

addAll

boolean addAll(Collection<? extends E> c)

如果指定集合中的所有元素尚不存在，則將它們添加到此集合中（可選操作）。 如果指定的集合也是一個(gè)集合，那么 addAll 操作會(huì)有效地修改這個(gè)集合，使其值是兩個(gè)集合的并集。 如果在操作正在進(jìn)行時(shí)修改了指定的集合，則此操作的行為是未定義的。

指定者：

接口 CollectionE 中的 addAll

參數(shù)：

參數(shù)名稱	參數(shù)描述
c	包含要添加到此集合的元素的集合

返回:

如果此集合因調(diào)用而更改，則為 true

Throws:

Throw名稱	Throw描述
UnsupportedOperationException	如果此 set 不支持 addAll 操作
ClassCastException	如果指定集合的元素的類阻止將其添加到此集合中
NullPointerException	如果指定的集合包含一個(gè)或多個(gè)空元素并且此集合不允許空元素，或者指定的集合為空
IllegalArgumentException	如果指定集合的某個(gè)元素的某些屬性阻止它被添加到此集合中

retainAll

boolean retainAll(Collection<?> c)

僅保留此集合中包含在指定集合中的元素（可選操作）。 換句話說，從這個(gè)集合中移除所有不包含在指定集合中的元素。 如果指定的集合也是一個(gè)集合，則此操作有效地修改此集合，使其值是兩個(gè)集合的交集。

指定者：

接口CollectionE中的retainAll

參數(shù)：

參數(shù)名稱	參數(shù)描述
c	包含要保留在此集合中的元素的集合

返回:

如果此集合因調(diào)用而更改，則為 true

Throws:

Throw名稱	Throw描述
UnsupportedOperationException	如果此 set 不支持 retainAll 操作
ClassCastException	如果此集合的元素的類與指定的集合不兼容（可選）
NullPointerException	如果此集合包含空元素并且指定的集合不允許空元素（可選），或者指定的集合為空

removeAll

boolean removeAll(Collection<?> c)

從此集合中刪除指定集合中包含的所有元素（可選操作）。 如果指定的集合也是一個(gè)集合，這個(gè)操作有效地修改了這個(gè)集合，使得它的值是兩個(gè)集合的不對(duì)稱集合差。

指定者：

接口 CollectionE 中的 removeAll

參數(shù)：

參數(shù)名稱	參數(shù)描述
c	包含要從此集合中刪除的元素的集合

返回:

如果此集合因調(diào)用而更改，則為 true

Throws:

Throw名稱	Throw描述
UnsupportedOperationException	如果此 set 不支持 removeAll 操作
ClassCastException	如果此集合的元素的類與指定的集合不兼容（可選）
NullPointerException	如果此集合包含空元素并且指定的集合不允許空元素（可選），或者指定的集合為空

clear

void clear()

從此集合中移除所有元素（可選操作）。 此調(diào)用返回后，該集合將為空。

指定者：

在界面 CollectionE 中清除

Throws:

Throw名稱	Throw描述
UnsupportedOperationException	if the clear method is not supported by this set

equals

boolean equals(Object o)

比較指定對(duì)象與此集合是否相等。 如果指定對(duì)象也是一個(gè)集合，則返回 true，這兩個(gè)集合具有相同的大小，并且指定集合的每個(gè)成員都包含在此集合中（或等效地，此集合的每個(gè)成員都包含在指定集合中）。 此定義確保 equals 方法在 set 接口的不同實(shí)現(xiàn)中正常工作。

指定者：

接口 CollectionE 中的等于

覆蓋：

類 Object 中的等于

參數(shù)：

參數(shù)名稱	參數(shù)描述
o	要與此集合比較是否相等的對(duì)象

返回:

如果指定的對(duì)象等于此集合，則為 true

hashCode

int hashCode()

返回此集合的哈希碼值。 集合的哈希碼定義為集合中元素的哈希碼之和，其中空元素的哈希碼定義為零。 這確保了 s1.equals(s2) 意味著任何兩個(gè)集合 s1 和 s2 的 s1.hashCode()==s2.hashCode()，這是 Object#hashCode 的一般合同所要求的。

指定者：

接口 CollectionE 中的 hashCode

覆蓋：

類 Object 中的 hashCode

返回:

此集合的哈希碼值

spliterator

default SpliteratorE spliterator()

在此集合中的元素上創(chuàng)建一個(gè) Spliterator。

Spliterator 報(bào)告 Spliterator#DISTINCT。 實(shí)施應(yīng)記錄附加特征值的報(bào)告。

指定者：

接口 CollectionE 中的分離器

指定者：

接口 IterableE 中的分離器

返回:

此集合中元素的拆分器