Module java.base
Package java.util

Interface Set<E>

类型参数:
E - 此集合中包含的元素的类型
所有超接口:
Collection<E>, Iterable<E>
所有已知子接口:
EventSet, NavigableSet<E>, SequencedSet<E>, SortedSet<E>
所有已知实现类:
AbstractSet, ConcurrentHashMap.KeySetView, ConcurrentSkipListSet, CopyOnWriteArraySet, EnumSet, HashSet, JobStateReasons, LinkedHashSet, TreeSet
public interface Set<E> extends Collection<E>
一个不包含重复元素的集合。更正式地说，集合不包含任何一对元素e1和e2，使得e1.equals(e2)，并且最多包含一个空元素。正如其名称所暗示的，此接口模拟了数学中的集合抽象概念。

Set接口对所有构造函数的契约以及add、equals和hashCode方法的契约施加了额外的规定，超出了从Collection接口继承的规定。其他继承方法的声明也包括在此处以方便查阅。（这些声明附带的规范已经针对Set接口进行了调整，但它们不包含任何额外的规定。）

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

注意：如果将可变对象用作集合元素，则必须格外小心。如果在对象作为集合元素时以影响equals比较的方式更改对象的值，则集合的行为未指定。这种禁止的特殊情况是，集合不得包含自身作为元素。

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

不可修改的集合

Set.of和Set.copyOf静态工厂方法提供了一种方便的方式来创建不可修改的集合。这些方法创建的Set实例具有以下特征：

  • 它们是不可修改的。元素不能被添加或移除。调用Set上的任何修改器方法将始终导致抛出UnsupportedOperationException。但是，如果包含的元素本身是可变的，则可能导致Set的行为不一致或其内容似乎发生更改。
  • 它们不允许null元素。尝试使用null元素创建它们将导致NullPointerException。
  • 如果所有元素都是可序列化的，则它们是可序列化的。
  • 它们在创建时拒绝重复元素。传递给静态工厂方法的重复元素将导致IllegalArgumentException。
  • 集合元素的迭代顺序是未指定的，并且可能会更改。
  • 它们是基于值的。程序员应该将相等的实例视为可互换，并且不应将它们用于同步，否则可能会发生不可预测的行为。例如，在将来的版本中，同步可能会失败。调用者不应该对返回的实例的身份做任何假设。工厂可以创建新实例或重用现有实例。
  • 它们按照序列化形式页面上指定的方式进行序列化。

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

自 JDK 版本:
1.2
参见:

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    add(E e)
    将指定的元素添加到此集合中（可选操作）。
    boolean
    addAll(Collection<? extends E> c)
    将指定集合中的所有元素添加到此集合中（可选操作）。
    void
    clear()
    从此集合中移除所有元素（可选操作）。
    boolean
    contains(Object o)
    如果此集合包含指定的元素，则返回true。
    boolean
    containsAll(Collection<?> c)
    如果此集合包含指定集合的所有元素，则返回true。
    static <E> Set<E>
    copyOf(Collection<? extends E> coll)
    返回包含给定集合的元素的不可修改的Set。
    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 declared in interface java.util.Collection

    parallelStream, removeIf, stream, toArray

    Methods declared in interface java.lang.Iterable

    forEach

  • Method Details

    • size

      int size()
      返回此集合中的元素数量（基数）。如果此集合包含的元素超过Integer.MAX_VALUE个，则返回Integer.MAX_VALUE。
      指定者:
      size 在接口 Collection<E>中
      返回:
      此集合中的元素数量（基数）

    • isEmpty

      boolean isEmpty()
      如果此集合不包含任何元素，则返回true。
      指定者:
      isEmpty 在接口 Collection<E>中
      返回:
      如果此集合不包含任何元素，则返回true

    • contains

      boolean contains(Object o)
      如果此集合包含指定的元素，则返回true。更正式地说，如果此集合包含使Objects.equals(o, e)为true的元素e，则返回true。
      指定由：
      contains 在接口 Collection<E>中
      参数：
      o - 要测试其是否存在于此集合中的元素
      返回：
      如果此集合包含指定的元素，则返回true
      抛出：
      ClassCastException - 如果指定元素的类型与此集合不兼容（可选）
      NullPointerException - 如果指定元素为null且此集合不允许null元素（可选）

    • iterator

      Iterator<E> iterator()
      返回此集合中元素的迭代器。元素以无特定顺序返回（除非此集合是某个提供保证的类的实例）。
      指定由：
      iterator 在接口 Collection<E>中
      指定由：
      iterator 在接口 Iterable<E>中
      返回：
      返回此集合中元素的迭代器

    • toArray

      Object[] toArray()
      返回一个包含此集合中所有元素的数组。如果此集合对其元素的返回顺序有任何保证，那么此方法必须以相同顺序返回元素。

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

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

      指定由：
      toArray 在接口 Collection<E>中
      返回：
      返回一个包含此集合中所有元素的数组

    • toArray

      <T> T[] toArray(T[] a)
      返回一个包含此集合中所有元素的数组；返回数组的运行时类型与指定数组的类型相同。如果集合适合于指定的数组，则将其返回。否则，将使用指定数组的运行时类型和此集合的大小分配一个新数组。

      如果此集合适合于指定数组且有多余空间（即，数组的元素多于此集合），则紧随集合末尾的数组元素将设置为null。（仅当调用者知道此集合不包含任何null元素时，此功能才有用以确定此集合的长度）。

      如果此集合对其元素的返回顺序有任何保证，那么此方法必须以相同顺序返回元素。

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

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

           String[] y = x.toArray(new String[0]);
      注意，toArray(new Object[0])在功能上与toArray()相同。
      指定由：
      toArray 在接口 Collection<E>中
      类型参数：
      T - 包含集合的数组的组件类型
      参数：
      a - 如果足够大，则将此集合的元素存储到其中的数组；否则，将为此目的分配相同运行时类型的新数组。
      返回：
      返回一个包含此集合中所有元素的数组
      抛出：
      ArrayStoreException - 如果指定数组的运行时类型不是此集合中每个元素的运行时类型的超类型
      NullPointerException - 如果指定数组为null

    • add

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

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

      指定由：
      add 在接口 Collection<E>中
      参数：
      e - 要添加到此集合的元素
      返回：
      如果此集合尚未包含指定的元素，则返回true
      抛出：
      UnsupportedOperationException - 如果此集合不支持add操作
      ClassCastException - 如果指定元素的类阻止将其添加到此集合
      NullPointerException - 如果指定元素为null且此集合不允许null元素
      IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此集合

    • remove

      boolean remove(Object o)
      如果存在，则从此集合中删除指定的元素（可选操作）。更正式地说，如果此集合包含Objects.equals(o, e)的元素e，则删除该元素。如果此集合包含该元素，则返回true（或者等效地，如果此集合由于调用而更改）。（一旦调用返回，此集合将不包含该元素。）
      指定由：
      remove 在接口 Collection<E>中
      参数：
      o - 如果存在，则从此集合中删除的对象
      返回：
      如果此集合包含指定的元素，则返回true
      抛出：
      ClassCastException - 如果指定元素的类型与此集合不兼容（可选）
      NullPointerException - 如果指定元素为null且此集合不允许null元素（可选）
      UnsupportedOperationException - 如果此集合不支持remove操作

    • containsAll

      boolean containsAll(Collection<?> c)
      如果此集合包含指定集合的所有元素，则返回true。如果指定的集合也是一个集合，则此方法在该集合是此集合的子集时返回true。
      指定由：
      containsAll 在接口 Collection<E>中
      参数：
      c - 要检查其是否包含在此集合中的集合
      返回：
      如果此集合包含指定集合的所有元素，则返回true
      抛出：
      ClassCastException - 如果指定集合中一个或多个元素的类型与此集合不兼容（可选）
      NullPointerException - 如果指定集合包含一个或多个null元素且此集合不允许null元素（可选），或者指定集合为null
      参见：

    • addAll

      boolean addAll(Collection<? extends E> c)
      如果尚未存在，则将指定集合中的所有元素添加到此集合（可选操作）。如果指定的集合也是一个集合，则addAll操作有效地修改此集合，使其值为两个集合的并集。如果在操作进行时修改了指定的集合，则此操作的行为是未定义的。
      指定者:
      addAll 在接口 Collection<E>中
      参数:
      c - 包含要添加到此集合中的元素的集合
      返回值:
      如果调用导致此集合发生更改，则返回true
      抛出:
      UnsupportedOperationException - 如果此集合不支持addAll操作
      ClassCastException - 如果指定集合的元素的类别阻止将其添加到此集合中
      NullPointerException - 如果指定集合包含一个或多个空元素且此集合不允许空元素，或者指定集合为null
      IllegalArgumentException - 如果指定集合的元素的某些属性阻止将其添加到此集合中
      参见:

    • retainAll

      boolean retainAll(Collection<?> c)
      仅保留此集合中包含在指定集合中的元素（可选操作）。换句话说，从此集合中删除不包含在指定集合中的所有元素。如果指定集合也是一个集合，则此操作有效地修改此集合，使其值为两个集合的交集。
      指定者:
      retainAll 在接口 Collection<E>中
      参数:
      c - 包含要保留在此集合中的元素的集合
      返回值:
      如果调用导致此集合发生更改，则返回true
      抛出:
      UnsupportedOperationException - 如果此集合不支持retainAll操作
      ClassCastException - 如果此集合的元素的类别与指定集合不兼容（可选）
      NullPointerException - 如果此集合包含空元素且指定集合不允许空元素（可选），或者指定集合为null
      参见:

    • removeAll

      boolean removeAll(Collection<?> c)
      从此集合中删除包含在指定集合中的所有元素（可选操作）。如果指定集合也是一个集合，则此操作有效地修改此集合，使其值为两个集合的非对称集合差。
      指定者:
      removeAll 在接口 Collection<E>中
      参数:
      c - 包含要从此集合中删除的元素的集合
      返回值:
      如果调用导致此集合发生更改，则返回true
      抛出:
      UnsupportedOperationException - 如果此集合不支持removeAll操作
      ClassCastException - 如果此集合的元素的类别与指定集合不兼容（可选）
      NullPointerException - 如果此集合包含空元素且指定集合不允许空元素（可选），或者指定集合为null
      参见:

    • clear

      void clear()
      从此集合中删除所有元素（可选操作）。此调用返回后，集合将为空。
      指定者:
      clear 在接口 Collection<E>中
      抛出:
      UnsupportedOperationException - 如果此集合不支持clear方法

    • equals

      boolean equals(Object o)
      将指定对象与此集合进行比较以检查是否相等。如果指定对象也是一个集合，两个集合的大小相同，并且指定集合的每个成员都包含在此集合中（或者等效地，此集合的每个成员都包含在指定集合中），则返回true。此定义确保equals方法在集合接口的不同实现之间正常工作。
      指定者:
      equals 在接口 Collection<E>中
      覆盖:
      equals 在类 Object中
      参数:
      o - 用于与此集合比较相等的对象
      返回值:
      如果指定对象等于此集合，则返回true
      参见:

    • hashCode

      int hashCode()
      返回此集合的哈希码值。集合的哈希码定义为集合中元素的哈希码之和，其中null元素的哈希码定义为零。这确保了对于任何两个集合s1和s2，如果s1.equals(s2)，则s1.hashCode()==s2.hashCode()，这是Object.hashCode()的一般契约所要求的。
      指定者:
      hashCode 在接口 Collection<E>中
      覆盖:
      hashCode 在类 Object中
      返回值:
      此集合的哈希码值
      参见:

    • spliterator

      default Spliterator<E> spliterator()
      在此集合中的元素上创建一个Spliterator。

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

      指定者:
      spliterator 在接口 Collection<E>中
      指定者:
      spliterator 在接口 Iterable<E>中
      实现要求:
      默认实现从集合的Iterator创建一个延迟绑定的spliterator。spliterator继承集合的迭代器的快速失败属性。

      创建的Spliterator还报告Spliterator.SIZED。

      实现说明:
      创建的Spliterator还报告Spliterator.SUBSIZED。
      返回值:
      包含此集合中元素的Spliterator
      自1.8起

    • of

      static <E> Set<E> of()
      返回一个包含零个元素的不可修改集合。有关详细信息，请参见不可修改集合。
      类型参数:
      E - Set的元素类型
      返回值:
      一个空的Set
      自9起

    • of

      static <E> Set<E> of(E e1)
      返回一个包含一个元素的不可修改集合。有关详细信息，请参见不可修改集合。
      类型参数:
      E - Set的元素类型
      参数:
      e1 - 单个元素
      返回值:
      包含指定元素的Set
      抛出:
      NullPointerException - 如果元素为null
      自9起

    • of

      static <E> Set<E> of(E e1, E e2)
      返回一个包含两个元素的不可修改集合。有关详细信息，请参见不可修改集合。
      类型参数:
      E - 集合的元素类型
      参数:
      e1 - 第一个元素
      e2 - 第二个元素
      返回:
      包含指定元素的 Set
      抛出:
      IllegalArgumentException - 如果元素重复
      NullPointerException - 如果元素为 null
      自版本:
      9

    • of

      static <E> Set<E> of(E e1, E e2, E e3)
      返回一个包含三个元素的不可修改集合。详情请参阅 不可修改集合。
      类型参数:
      E - 集合的元素类型
      参数:
      e1 - 第一个元素
      e2 - 第二个元素
      e3 - 第三个元素
      返回:
      包含指定元素的 Set
      抛出:
      IllegalArgumentException - 如果存在任何重复元素
      NullPointerException - 如果元素为 null
      自版本:
      9

    • of

      static <E> Set<E> of(E e1, E e2, E e3, E e4)
      返回一个包含四个元素的不可修改集合。详情请参阅 不可修改集合。
      类型参数:
      E - 集合的元素类型
      参数:
      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)
      返回一个包含五个元素的不可修改集合。详情请参阅 不可修改集合。
      类型参数:
      E - 集合的元素类型
      参数:
      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)
      返回一个包含六个元素的不可修改集合。详情请参阅 不可修改集合。
      类型参数:
      E - 集合的元素类型
      参数:
      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)
      返回一个包含七个元素的不可修改集合。详情请参阅 不可修改集合。
      类型参数:
      E - 集合的元素类型
      参数:
      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)
      返回一个包含八个元素的不可修改集合。详情请参阅 不可修改集合。
      类型参数:
      E - 集合的元素类型
      参数:
      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)
      返回一个包含九个元素的不可修改集合。详情请参阅 不可修改集合。
      类型参数:
      E - 集合的元素类型
      参数:
      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)
      返回一个包含十个元素的不可修改集合。详情请参阅 不可修改集合。
      类型参数:
      E - 集合的元素类型
      参数:
      e1 - 第一个元素
      e2 - 第二个元素
      e3 - 第三个元素
      e4 - 第四个元素
      e5 - 第五个元素
      e6 - 第六个元素
      e7 - 第七个元素
      e8 - 第八个元素
      e9 - 第九个元素
      e10 - 第十个元素
      返回:
      包含指定元素的 Set
      抛出:
      IllegalArgumentException - 如果存在任何重复元素
      NullPointerException - 如果元素为 null
      自版本:
      9

    • of

      @SafeVarargs static <E> Set<E> of(E... elements)
      返回一个包含任意数量元素的不可修改集合。详情请参阅 不可修改集合。
      API 注释:
      此方法还接受单个数组作为参数。结果集的元素类型将是数组的组件类型，并且集合的大小将等于数组的长度。要创建包含单个数组元素的集合，请执行以下操作： 
      
     String[] array = ... ;
     Set<String[]> list = Set.<String[]>of(array);
      这将导致调用 Set.of(E) 方法。
      类型参数:
      E - 集合的元素类型
      参数:
      elements - 要包含在集合中的元素
      返回:
      包含指定元素的 Set
      抛出:
      IllegalArgumentException - 如果存在任何重复元素
      NullPointerException - 如果元素为 null 或者数组为 null
      自版本:
      9

    • copyOf

      static <E> Set<E> copyOf(Collection<? extends E> coll)
      返回一个包含给定集合元素的 不可修改集合。给定集合不能为空，并且不能包含任何空元素。如果给定集合包含重复元素，则保留其中任意一个重复元素。如果随后修改给定集合，则返回的集合将不反映这些修改。
      实现注意事项:
      如果给定的Collection是一个不可修改的Set，调用copyOf通常不会创建副本。
      类型参数:
      E - Set的元素类型
      参数:
      coll - 从中提取元素的Collection，必须非空
      返回值:
      包含给定Collection元素的Set
      抛出:
      NullPointerException - 如果coll为null，或者包含任何null值
      自版本:
      10