Module java.base

软件包 java.util

Interface Set<E>

参数类型

E - 由此集合维护的元素的类型

All Superinterfaces:

Collection<E> ， Iterable<E>

All Known Subinterfaces:

EventSet ， NavigableSet<E> ， ObservableSet<E> ， ObservableSetValue<E> ， SortedSet<E> ， WritableSetValue<E>

所有已知实现类：

AbstractSet ， ConcurrentHashMap.KeySetView ， ConcurrentSkipListSet ， CopyOnWriteArraySet ， EnumSet ， HashSet ， JobStateReasons ， LinkedHashSet ， ReadOnlySetProperty ， ReadOnlySetPropertyBase ， ReadOnlySetWrapper ， SetBinding ， SetExpression ， SetProperty ， SetPropertyBase ， SimpleSetProperty ， TreeSet

public interface Set<E>
extends Collection<E>

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

该Set接口放置额外的约定，超过从继承Collection接口，所有构造函数的合同，而位于该合同add ， equals和hashCode方法。 其他继承方法的声明也包括在这里以方便。 （这些声明中附带的规格已针对Set接口进行了定制，但不包含任何其他规定。）

构造函数的额外规定并不奇怪，所有构造函数都必须创建一个不包含重复元素的集合（如上所定义）。

注意：如果可变对象用作设置元素，则必须非常小心。 如果对象的值以影响equals比较的方式更改，而对象是集合中的元素，则不指定集合的行为。 这种禁止的一个特殊情况是，一个集合不允许将其本身作为一个元素。

一些集合实现对它们可能包含的元素有限制。 例如，一些实现禁止空元素，有些实现对元素的类型有限制。 尝试添加不合格元素会引发未经检查的异常，通常为NullPointerException或ClassCastException 。 尝试查询不合格元素的存在可能会引发异常，或者可能只是返回false; 一些实现将展现出前者的行为，一些实现将展现出后者。 更一般来说，尝试对不符合条件的元素的操作，其完成不会导致不合格元素插入到集合中，可能会导致异常，或者可能会成功执行该选项。 此异常在此接口的规范中标记为“可选”。

Immutable Set Static Factory Methods

27064454984920静态工厂方法提供了创建不可变集合的便捷方式。 由这些方法创建的Set实例具有以下特征：

• 它们在结构上是不可变的 。 元素无法添加或删除。 调用任何mutator方法将总是导致UnsupportedOperationException被抛出。 但是，如果包含的元素本身是可变的，这可能会导致Set的行为不一致或其内容看起来会发生变化。
• 他们不允许null元素。 尝试使用null元素创建它们将导致NullPointerException 。
• 如果所有元素是可序列化的，它们是可序列化的。
• 他们在创建时拒绝重复的元素。 传递给静态工厂方法的重复元素将导致IllegalArgumentException 。
• 集合元素的迭代顺序未指定，可能会更改。
• 他们是value-based 。 调用者不应该对返回的实例的身份进行假设。 工厂可以自由创建新的实例或重用现有的实例。 因此，对这些实例的身份敏感操作（引用等式（ == ），身份哈希码和同步）是不可靠的，应该避免。
• 它们按Serialized Form页面的规定进行序列化。

此界面是Java Collections Framework的成员。

从以下版本开始：

1.2

另请参见：

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

方法摘要

Modifier and Type	方法	描述
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 。
Iterator<E>	iterator()	返回此集合中元素的迭代器。
static <E> Set<E>	of()	返回一个包含零个元素的不可变集合。
static <E> Set<E>	of(E e1)	返回一个包含一个元素的不可变集合。
static <E> Set<E>	of(E... elements)	返回一个包含任意数量元素的不可变集合。
static <E> Set<E>	of(E e1, E e2)	返回一个包含两个元素的不可变集合。
static <E> Set<E>	of(E e1, E e2, E e3)	返回一个包含三个元素的不可变集合。
static <E> Set<E>	of(E e1, E e2, E e3, E e4)	返回一个包含四个元素的不可变集合。
static <E> Set<E>	of(E e1, E e2, E e3, E e4, E e5)	返回一个包含五个元素的不可变集合。
static <E> Set<E>	of(E e1, E e2, E e3, E e4, E e5, E e6)	返回一个包含六个元素的不可变集合。
static <E> Set<E>	of(E e1, E e2, E e3, E e4, E e5, E e6, E e7)	返回一个包含七个元素的不可变集合。
static <E> Set<E>	of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8)	返回一个包含八个元素的不可变集合。
static <E> Set<E>	of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9)	返回一个包含九个元素的不可变集合。
static <E> Set<E>	of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10)	返回一个包含十个元素的不可变集合。
boolean	remove(Object o)	如果存在，则从该集合中删除指定的元素（可选操作）。
boolean	removeAll(Collection<?> c)	从此集合中删除指定集合中包含的所有元素（可选操作）。
boolean	retainAll(Collection<?> c)	仅保留该集合中包含在指定集合中的元素（可选操作）。
int	size()	返回此集合中的元素数（其基数）。
default Spliterator<E>	spliterator()	在此集合中的元素上创建一个 Spliterator 。
Object[]	toArray()	返回一个包含此集合中所有元素的数组。
<T> T[]	toArray(T[] a)	返回一个包含此集合中所有元素的数组; 返回的数组的运行时类型是指定数组的运行时类型。

Methods inherited from interface java.util.Collection

parallelStream, removeIf, stream

Methods inherited from interface java.lang.Iterable

forEach

方法详细信息

size

int size()

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

Specified by:

size在接口 Collection<E>

结果

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

isEmpty

boolean isEmpty()

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

Specified by:

isEmpty在接口 Collection<E>

结果

true如果此集合不包含元素

contains

boolean contains(Object o)

如果此集合包含指定的元素，则返回true 。 更正式地说，返回true当且仅当此set包含的元素e这样Objects.equals(o, e) 。

Specified by:

contains在接口 Collection<E>

参数

o - 要在此集合中存在的元素要进行测试

结果

true如果这个集合包含指定的元素

异常

ClassCastException - 如果指定元素的类型与此集不兼容（ optional ）

NullPointerException - 如果指定的元素为空，并且该集合不允许空元素（ optional ）

iterator

Iterator<E> iterator()

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

Specified by:

iterator在接口 Collection<E>

Specified by:

iterator在接口 Iterable<E>

结果

这个集合中的元素的迭代器

toArray

Object[] toArray()

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

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

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

Specified by:

toArray在接口 Collection<E>

结果

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

toArray

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

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

如果这个集合适合指定的数组，有空余的空间（即，该数组的元素多于此集合），紧随集合结束后的数组中的元素设置为null 。 （这仅在调用者知道此集合不包含任何空元素时才可用于确定此集合的长度。）

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

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

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

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

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

Specified by:

toArray在接口 Collection<E>

参数类型

T - 包含集合的数组的运行时类型

参数

a - 要存储此集合的元素的阵列，如果它足够大; 否则，为此目的分配相同运行时类型的新数组。

结果

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

异常

ArrayStoreException - 如果指定数组的运行时类型不是此集合中每个元素的运行时类型的超类型

NullPointerException - 如果指定的数组为空

add

boolean add(E e)

如果指定的元素不存在，则将其指定的元素添加（可选操作）。 更正式地，将指定的元素e这一套如果集合不包含元素e2这样Objects.equals(e, e2) 。 如果该集合已经包含该元素，则该呼叫将保持不变，并返回false 。 结合对构造函数的限制，这样可以确保集合不会包含重复的元素。

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

Specified by:

add在接口 Collection<E>

参数

e - 要添加到此集合的元素

结果

true如果此集合尚未包含指定的元素

异常

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

ClassCastException - 如果指定元素的类阻止将其添加到此集合

NullPointerException - 如果指定的元素为空，并且该集合不允许空元素

IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此集合中

remove

boolean remove(Object o)

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

Specified by:

remove在接口 Collection<E>

参数

o - 要从此集合中删除的对象（如果存在）

结果

true如果这个集合包含指定的元素

异常

ClassCastException - 如果指定元素的类型与此集不兼容（ optional ）

NullPointerException - 如果指定的元素为空，并且该集合不允许空元素（ optional ）

UnsupportedOperationException - 如果此集合不支持 remove操作

containsAll

boolean containsAll(Collection<?> c)

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

Specified by:

containsAll在接口 Collection<E>

参数

c - 要在此集合中检查遏制的集合

结果

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

异常

ClassCastException - 如果指定集合中的一个或多个元素的类型与此集不兼容（ optional ）

NullPointerException - 如果指定的集合包含一个或多个空元素，并且此集合不允许空元素（ optional ），或者如果指定的集合为空

另请参见：

contains(Object)

addAll

boolean addAll(Collection<? extends E> c)

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

Specified by:

addAll在接口 Collection<E>

参数

c - 包含要添加到此集合的元素的集合

结果

true如果此设置由于呼叫而更改

异常

UnsupportedOperationException - 如果此集合不支持 addAll操作

ClassCastException - 如果指定集合的元素的类阻止将其添加到此集合

NullPointerException - 如果指定的集合包含一个或多个空元素，并且此集合不允许空元素，或者如果指定的集合为空

IllegalArgumentException - 如果指定集合的元素的某些属性阻止将其添加到此集合

另请参见：

add(Object)

retainAll

boolean retainAll(Collection<?> c)

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

Specified by:

retainAll在接口 Collection<E>

参数

c - 包含要保留在此集合中的元素的集合

结果

true如果此设置由于调用而更改

异常

UnsupportedOperationException - 如果此集合不支持 retainAll操作

ClassCastException - 如果此集合的元素的类与指定的集合不兼容（ optional ）

NullPointerException - 如果此集合包含空元素，并且指定的集合不允许空元素（ optional ），或者如果指定的集合为空

另请参见：

remove(Object)

removeAll

boolean removeAll(Collection<?> c)

从此集合中删除指定集合中包含的所有元素（可选操作）。 如果指定的集合也是集合，则该操作有效地修改该集合，使其值是两组的非对称集合差异 。

Specified by:

removeAll在接口 Collection<E>

参数

c - 包含要 c集合中删除的元素的集合

结果

true如果此设置由于呼叫而更改

异常

UnsupportedOperationException - 如果此集合不支持 removeAll操作

ClassCastException - 如果此集合的元素的类与指定的集合不兼容（ optional ）

NullPointerException - 如果此集合包含空元素，并且指定的集合不允许空元素（ optional ），或者如果指定的集合为空

另请参见：

remove(Object) ， contains(Object)

clear

void clear()

从此集合中删除所有元素（可选操作）。 此呼叫返回后，该组将为空。

Specified by:

clear在接口 Collection<E>

异常

UnsupportedOperationException - 如果此集合不支持 clear方法

equals

boolean equals(Object o)

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

Specified by:

equals在接口 Collection<E>

重写：

equals在 Object

参数

o - 要与此集合相等的对象进行比较

结果

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

另请参见：

Object.hashCode() ， HashMap

hashCode

int hashCode()

返回此集合的哈希码值。 集合的哈希码被定义为集合中的元素的哈希码的总和，其中null元素的哈希码被定义为零。 这确保s1.equals(s2)意味着s1.hashCode()==s2.hashCode()对于任何两套s1和s2 ，根据s2的一般合同要求 。

Specified by:

hashCode在接口 Collection<E>

重写：

hashCode在 Object

结果

该集合的哈希码值

另请参见：

Object.equals(Object) ， equals(Object)

spliterator

default Spliterator<E> spliterator()

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

Spliterator报告Spliterator.DISTINCT 。 实施应记录其他特征值的报告。

Specified by:

spliterator在接口 Collection<E>

Specified by:

spliterator在接口 Iterable<E>

实现要求：

默认实现从集合的Iterator创建了一个late-binding分割Iterator 。 分割器继承集合迭代器的故障快速属性。

创建的Spliterator另外报告Spliterator.SIZED 。

Implementation Note:

创建的 Spliterator另外报告 Spliterator.SUBSIZED 。

结果

一个 Spliterator在这个集合中的元素

从以下版本开始：

1.8

of

static <E> Set<E> of()

返回一个包含零个元素的不可变集合。 详见Immutable Set Static Factory Methods 。

参数类型

E - Set的元素类型

结果

一个空的 Set

从以下版本开始：

9

of

static <E> Set<E> of(E e1)

返回一个包含一个元素的不可变集合。 详见Immutable Set Static Factory Methods 。

参数类型

E - Set的元素类型

参数

e1 - 单个元素

结果

一个 Set包含指定的元素

异常

NullPointerException - 如果元素是 null

从以下版本开始：

9

of

static <E> Set<E> of(E e1,
                     E e2)

返回一个包含两个元素的不可变集合。 详见Immutable Set Static Factory Methods 。

参数类型

E - Set的元素类型

参数

e1 - 第一个元素

e2 - 第二个元素

结果

一个包含指定元素的 Set

异常

IllegalArgumentException - 如果元素是重复的

NullPointerException - 如果元素是 null

从以下版本开始：

9

of

static <E> Set<E> of(E e1,
                     E e2,
                     E e3)

返回一个包含三个元素的不可变集合。 详见Immutable Set Static Factory Methods 。

参数类型

E - Set的元素类型

参数

e1 - 第一个元素

e2 - 第二个元素

e3 - 第三个元素

结果

一个包含指定元素的 Set

异常

IllegalArgumentException - 如果有任何重复的元素

NullPointerException - 如果元素是 null

从以下版本开始：

9

of

static <E> Set<E> of(E e1,
                     E e2,
                     E e3,
                     E e4)

返回一个包含四个元素的不可变集合。 详见Immutable Set Static Factory Methods 。

参数类型

E - Set的元素类型

参数

e1 - 第一个元素

e2 - 第二个元素

e3 - 第三个元素

e4 - 第四个元素

结果

一个包含指定元素的 Set

异常

IllegalArgumentException - 如果有任何重复的元素

NullPointerException - 如果一个元素是 null

从以下版本开始：

9

of

static <E> Set<E> of(E e1,
                     E e2,
                     E e3,
                     E e4,
                     E e5)

返回一个包含五个元素的不可变集合。 详见Immutable Set Static Factory Methods 。

参数类型

E - Set的元素类型

参数

e1 - 第一个元素

e2 - 第二个元素

e3 - 第三个元素

e4 - 第四个元素

e5 - 第五个元素

结果

一个包含指定元素的 Set

异常

IllegalArgumentException - 如果有任何重复的元素

NullPointerException - 如果一个元素是 null

从以下版本开始：

9

of

static <E> Set<E> of(E e1,
                     E e2,
                     E e3,
                     E e4,
                     E e5,
                     E e6)

返回一个包含六个元素的不可变集合。 详见Immutable Set Static Factory Methods 。

参数类型

E - Set的元素类型

参数

e1 - 第一个元素

e2 - 第二个元素

e3 - 第三个元素

e4 - 第四个元素

e5 - 第五个元素

e6 - 第六个元素

结果

一个包含指定元素的 Set

异常

IllegalArgumentException - 如果有任何重复元素

NullPointerException - 如果一个元素是 null

从以下版本开始：

9

of

static <E> Set<E> of(E e1,
                     E e2,
                     E e3,
                     E e4,
                     E e5,
                     E e6,
                     E e7)

返回一个包含七个元素的不可变集合。 详见Immutable Set Static Factory Methods 。

参数类型

E - Set的元素类型

参数

e1 - 第一个元素

e2 - 第二个元素

e3 - 第三个元素

e4 - 第四个元素

e5 - 第五个元素

e6 - 第六个元素

e7 - 第七个元素

结果

一个包含指定元素的 Set

异常

IllegalArgumentException - 如果有任何重复的元素

NullPointerException - 如果元素是 null

从以下版本开始：

9

of

static <E> Set<E> of(E e1,
                     E e2,
                     E e3,
                     E e4,
                     E e5,
                     E e6,
                     E e7,
                     E e8)

返回一个包含八个元素的不可变集合。 详见Immutable Set Static Factory Methods 。

参数类型

E - Set的元素类型

参数

e1 - 第一个元素

e2 - 第二个元素

e3 - 第三个元素

e4 - 第四个元素

e5 - 第五个元素

e6 - 第六个元素

e7 - 第七个元素

e8 - 第八个元素

结果

一个包含指定元素的 Set

异常

IllegalArgumentException - 如果有任何重复的元素

NullPointerException - 如果一个元素是 null

从以下版本开始：

9

of

static <E> Set<E> of(E e1,
                     E e2,
                     E e3,
                     E e4,
                     E e5,
                     E e6,
                     E e7,
                     E e8,
                     E e9)

返回一个包含九个元素的不可变集合。 详见Immutable Set Static Factory Methods 。

参数类型

E - Set的元素类型

参数

e1 - 第一个元素

e2 - 第二个元素

e3 - 第三个元素

e4 - 第四个元素

e5 - 第五个元素

e6 - 第六个元素

e7 - 第七个元素

e8 - 第八个元素

e9 - 第九个元素

结果

一个包含指定元素的 Set

异常

IllegalArgumentException - 如果有任何重复的元素

NullPointerException - 如果一个元素是 null

从以下版本开始：

9

of

static <E> Set<E> of(E e1,
                     E e2,
                     E e3,
                     E e4,
                     E e5,
                     E e6,
                     E e7,
                     E e8,
                     E e9,
                     E e10)

返回一个包含十个元素的不可变集合。 详见Immutable Set Static Factory Methods 。

参数类型

E - Set的元素类型

参数

e1 - 第一个元素

e2 - 第二个元素

e3 - 第三个元素

e4 - 第四个元素

e5 - 第五个元素

e6 - 第六个元素

e7 - 第七个元素

e8 - 第八个元素

e9 - 第九个元素

e10 - 第十个元素

结果

一个包含指定元素的 Set

异常

IllegalArgumentException - 如果有任何重复的元素

NullPointerException - 如果一个元素是 null

从以下版本开始：

9

of

@SafeVarargs
static <E> Set<E> of(E... elements)

返回一个包含任意数量元素的不可变集合。 详见Immutable Set Static Factory Methods 。

API Note:

该方法也接受一个数组作为参数。 结果集的元素类型将是数组的组件类型，集合的大小将等于数组的长度。 要使用单个元素创建一个数组，请执行以下操作：

   String[] array = ... ; Set<String[]> list = Set.<String[]>of(array);  

这将导致Set.of(E)方法被调用。

参数类型

E - Set的元素类型

参数

elements - 要包含在集合中的元素

结果

一个包含指定元素的 Set

异常

IllegalArgumentException - 如果有任何重复元素

NullPointerException - 如果元素是 null或者数组是 null

从以下版本开始：

9