Set

public interface Set<E>
extends Collection<E>

不包含重复元素的集合。 更正式地说，集合不包含一对元素 e1 和 e2 使得 e1.equals(e2)，并且最多包含一个空元素。 正如它的名字所暗示的，这个接口模拟了数学集合抽象。

除了从 Collection 接口继承的那些之外，Set 接口对所有构造函数的合约以及 add、equals 和 hashCode 方法的合约进行了额外的规定。 为方便起见，此处还包括其他继承方法的声明。 （这些声明随附的规范已针对 Set 接口进行了定制，但它们不包含任何附加规定。）

毫不奇怪，对构造函数的附加规定是，所有构造函数都必须创建一个不包含重复元素的集合（如上所述）。

注意：如果将可变对象用作集合元素，则必须非常小心。如果对象的值以影响等于比较的方式更改，而对象是集合中的一个元素，则不指定集合的行为。此禁令的一个特殊情况是不允许集合包含自身作为元素。

一些集合实现对它们可能包含的元素有限制。例如，一些实现禁止空元素，而一些实现对其元素的类型有限制。尝试添加不合格的元素会引发未经检查的异常，通常是 NullPointerException 或 ClassCastException。尝试查询不合格元素的存在可能会引发异常，或者它可能只是返回 false；一些实现会表现出前一种行为，而另一些会表现出后者。更一般地，尝试对不合格元素执行操作，该不合格元素的完成不会导致将不合格元素插入集合中，这可能会引发异常，也可能会成功，这取决于实现的选择。此类异常在此接口的规范中被标记为“可选”。

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

方法总结

修饰符和类型	方法	描述
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)	比较指定对象与此集合是否相等。
int	hashCode()	返回此集合的哈希码值。
boolean	isEmpty()	如果此集合不包含任何元素，则返回 true。
IteratorE	iterator()	返回此集合中元素的迭代器。
boolean	remove(Object o)	如果存在，则从此集合中删除指定的元素（可选操作）。
boolean	removeAll(Collection<?> c)	从此集合中删除指定集合中包含的所有元素（可选操作）。
boolean	retainAll(Collection<?> c)	仅保留此集合中包含在指定集合中的元素（可选操作）。
int	size()	返回此集合中的元素数（其基数）。
default SpliteratorE	spliterator()	在此集合中的元素上创建一个 Spliterator。
Object[]	toArray()	返回一个包含此集合中所有元素的数组。
<T> T[]	toArray(T[] a)	返回一个包含该集合中所有元素的数组； 返回数组的运行时类型是指定数组的运行时类型。

从接口 java.util.Collection 继承的方法
parallelStream, removeIf, stream

从接口 java.lang.Iterable 继承的方法
forEach

方法详情

size

int size()

返回此集合中的元素数（其基数）。 如果此集合包含多个 Integer.MAX_VALUE 元素，则返回 Integer.MAX_VALUE。

指定者：

接口 CollectionE 中的大小

返回:

该集合中的元素数量（其基数）

isEmpty

boolean isEmpty()

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

指定者：

接口 CollectionE 中的 isEmpty

返回:

如果此集合不包含任何元素，则为 true

contains

boolean contains(Object o)

如果此集合包含指定的元素，则返回 true。 更正式地说，当且仅当此集合包含满足 (o==null ? e==null : o.equals(e)) 的元素 e 时才返回 true。

指定者：

包含在接口 CollectionE 中

参数：

参数名称	参数描述
o	要测试其在该集合中的存在的元素

返回:

如果此集合包含指定元素，则为 true

Throws:

Throw名称	Throw描述
ClassCastException	如果指定元素的类型与此集合不兼容（可选）
NullPointerException	如果指定元素为空且此集合不允许空元素（可选）

iterator

IteratorE iterator()

返回此集合中元素的迭代器。 返回的元素没有特定的顺序（除非这个集合是某个提供保证的类的实例）。

指定者：

接口 CollectionE 中的迭代器

指定者：

接口 IterableE 中的迭代器

返回:

此集合中元素的迭代器

toArray

Object[] toArray()

返回一个包含此集合中所有元素的数组。 如果此集合对其迭代器返回其元素的顺序做出任何保证，则此方法必须以相同的顺序返回元素。

返回的数组将是“安全的”，因为该集合不维护对它的引用。 （换句话说，即使这个集合是由一个数组支持的，这个方法也必须分配一个新数组）。 因此，调用者可以自由修改返回的数组。

此方法充当基于数组和基于集合的 API 之间的桥梁。

指定者：

接口 CollectionE 中的 toArray

返回:

包含此集合中所有元素的数组

toArray

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

返回一个包含该集合中所有元素的数组；返回数组的运行时类型是指定数组的运行时类型。如果集合适合指定的数组，则在其中返回。否则，将使用指定数组的运行时类型和该集合的大小分配一个新数组。

如果此集合适合指定的数组并有剩余空间（即，数组的元素比此集合多），则数组中紧跟集合末尾的元素设置为 null。 （只有当调用者知道这个集合不包含任何空元素时，这在确定这个集合的长度时才有用。）

如果此集合对其迭代器返回其元素的顺序做出任何保证，则此方法必须以相同的顺序返回元素。

与 toArray() 方法一样，此方法充当基于数组的 API 和基于集合的 API 之间的桥梁。此外，此方法允许对输出数组的运行时类型进行精确控制，并且在某些情况下可用于节省分配成本。

假设 x 是一个已知只包含字符串的集合。以下代码可用于将集合转储到新分配的字符串数组中：

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

请注意，toArray(new Object[0]) 在功能上与 toArray() 相同。

指定者：

接口 CollectionE 中的 toArray

类型参数：

类型参数名称	类型参数描述
T	包含集合的数组的运行时类型

参数:

参数名称	参数描述
a	这个集合的元素要存储到的数组，如果它足够大的话； 否则，将为此目的分配相同运行时类型的新数组。

返回:

包含此集合中所有元素的数组

Throws:

Throw名称	Throw描述
ArrayStoreException	如果指定数组的运行时类型不是此集合中每个元素的运行时类型的超类型
NullPointerException	如果指定的数组为空

add

boolean add(E e)

如果指定元素尚不存在，则将其添加到此集合中（可选操作）。 更正式地说，如果集合不包含元素 e2，则将指定的元素 e 添加到此集合中，使得 (e==null ? e2==null : e.equals(e2))。 如果该集合已包含该元素，则调用将保持该集合不变并返回 false。 结合对构造函数的限制，这确保了集合永远不会包含重复的元素。

上述规定并不意味着集合必须接受所有元素； 集合可以拒绝添加任何特定元素，包括 null，并抛出异常，如 Collection#add 规范中所述。 单独的集合实现应该清楚地记录对它们可能包含的元素的任何限制。

指定者：

添加接口CollectionE

参数：

参数名称	参数描述
e	要添加到此集合的元素

返回:

如果此集合尚未包含指定元素，则为 true

Throws:

Throw名称	Throw描述
UnsupportedOperationException	如果此集合不支持添加操作
ClassCastException	如果指定元素的类阻止它被添加到这个集合中
NullPointerException	如果指定元素为空且此集合不允许空元素
IllegalArgumentException	如果指定元素的某些属性阻止它被添加到此集合中

remove

boolean remove(Object o)

如果存在，则从此集合中删除指定的元素（可选操作）。 更正式地说，如果这个集合包含这样一个元素，则删除一个元素 e 使得 (o==null ? e==null : o.equals(e))。 如果此 set 包含该元素（或等效地，如果此 set 由于调用而更改），则返回 true。 （一旦调用返回，该集合将不包含该元素。）

指定者：

在接口 CollectionE 中删除

参数：

参数名称	参数描述
o	要从此集合中删除的对象（如果存在）

返回:

如果此集合包含指定的元素，则为 true

Throws:

Throw名称	Throw描述
ClassCastException	如果指定元素的类型与此集合不兼容（可选）
NullPointerException	如果指定元素为空且此集合不允许空元素（可选）
UnsupportedOperationException	如果此 set 不支持删除操作

containsAll

boolean containsAll(Collection<?> c)

如果此集合包含指定集合的所有元素，则返回 true。 如果指定的集合也是一个集合，如果它是这个集合的子集，则此方法返回 true。

指定者：

接口 CollectionE 中的 containsAll

参数：

参数名称	参数描述
c	要检查此集合中包含的集合

返回:

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

Throws:

Throw名称	Throw描述
ClassCastException	如果指定集合中的一个或多个元素的类型与该集合不兼容（可选）
NullPointerException	如果指定的集合包含一个或多个空元素并且此集合不允许空元素（可选），或者指定的集合为空

addAll

boolean addAll(Collection<? extends E> c)

如果指定集合中的所有元素尚不存在，则将它们添加到此集合中（可选操作）。 如果指定的集合也是一个集合，那么 addAll 操作会有效地修改这个集合，使其值是两个集合的并集。 如果在操作正在进行时修改了指定的集合，则此操作的行为是未定义的。

指定者：

接口 CollectionE 中的 addAll

参数：

参数名称	参数描述
c	包含要添加到此集合的元素的集合

返回:

如果此集合因调用而更改，则为 true

Throws:

Throw名称	Throw描述
UnsupportedOperationException	如果此 set 不支持 addAll 操作
ClassCastException	如果指定集合的元素的类阻止将其添加到此集合中
NullPointerException	如果指定的集合包含一个或多个空元素并且此集合不允许空元素，或者指定的集合为空
IllegalArgumentException	如果指定集合的某个元素的某些属性阻止它被添加到此集合中

retainAll

boolean retainAll(Collection<?> c)

仅保留此集合中包含在指定集合中的元素（可选操作）。 换句话说，从这个集合中移除所有不包含在指定集合中的元素。 如果指定的集合也是一个集合，则此操作有效地修改此集合，使其值是两个集合的交集。

指定者：

接口CollectionE中的retainAll

参数：

参数名称	参数描述
c	包含要保留在此集合中的元素的集合

返回:

如果此集合因调用而更改，则为 true

Throws:

Throw名称	Throw描述
UnsupportedOperationException	如果此 set 不支持 retainAll 操作
ClassCastException	如果此集合的元素的类与指定的集合不兼容（可选）
NullPointerException	如果此集合包含空元素并且指定的集合不允许空元素（可选），或者指定的集合为空

removeAll

boolean removeAll(Collection<?> c)

从此集合中删除指定集合中包含的所有元素（可选操作）。 如果指定的集合也是一个集合，这个操作有效地修改了这个集合，使得它的值是两个集合的不对称集合差。

指定者：

接口 CollectionE 中的 removeAll

参数：

参数名称	参数描述
c	包含要从此集合中删除的元素的集合

返回:

如果此集合因调用而更改，则为 true

Throws:

Throw名称	Throw描述
UnsupportedOperationException	如果此 set 不支持 removeAll 操作
ClassCastException	如果此集合的元素的类与指定的集合不兼容（可选）
NullPointerException	如果此集合包含空元素并且指定的集合不允许空元素（可选），或者指定的集合为空

clear

void clear()

从此集合中移除所有元素（可选操作）。 此调用返回后，该集合将为空。

指定者：

在界面 CollectionE 中清除

Throws:

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

equals

boolean equals(Object o)

比较指定对象与此集合是否相等。 如果指定对象也是一个集合，则返回 true，这两个集合具有相同的大小，并且指定集合的每个成员都包含在此集合中（或等效地，此集合的每个成员都包含在指定集合中）。 此定义确保 equals 方法在 set 接口的不同实现中正常工作。

指定者：

接口 CollectionE 中的等于

覆盖：

类 Object 中的等于

参数：

参数名称	参数描述
o	要与此集合比较是否相等的对象

返回:

如果指定的对象等于此集合，则为 true

hashCode

int hashCode()

返回此集合的哈希码值。 集合的哈希码定义为集合中元素的哈希码之和，其中空元素的哈希码定义为零。 这确保了 s1.equals(s2) 意味着任何两个集合 s1 和 s2 的 s1.hashCode()==s2.hashCode()，这是 Object#hashCode 的一般合同所要求的。

指定者：

接口 CollectionE 中的 hashCode

覆盖：

类 Object 中的 hashCode

返回:

此集合的哈希码值

spliterator

default SpliteratorE spliterator()

在此集合中的元素上创建一个 Spliterator。

Spliterator 报告 Spliterator#DISTINCT。 实施应记录附加特征值的报告。

指定者：

接口 CollectionE 中的分离器

指定者：

接口 IterableE 中的分离器

返回:

此集合中元素的拆分器