模块 java.base
 java.util

接口 Set<E>

类型参数:
E - 此集合维护的元素类型
所有父级接口:
Collection<E> , Iterable<E>
所有已知的子接口:
EventSet , NavigableSet<E> , SortedSet<E>
所有已知的实现类:
AbstractSet , ConcurrentHashMap.KeySetView , ConcurrentSkipListSet , CopyOnWriteArraySet , EnumSet , HashSet , JobStateReasons , LinkedHashSet , TreeSet

public interface Set<E> extends Collection <E>
不包含重复元素的集合。更正式地说,集合不包含满足 e1.equals(e2) 的一对元素 e1e2,并且最多包含一个空元素。顾名思义,这个接口模拟数学set抽象。

Set 接口在所有构造函数的契约以及 addequalshashCode 方法的契约上放置了额外的规定,除了从 Collection 接口继承的那些。为方便起见,此处还包含其他继承方法的声明。 (这些声明附带的规范已针对 Set 接口进行了定制,但它们不包含任何附加规定。)

毫无疑问,构造方法的附加规定是所有构造方法必须创建一个不包含重复元素(如上定义)的集合。

注意:如果将可变对象用作集合元素,则必须格外小心。如果对象的值以影响 equals 比较的方式更改,而对象是集合中的元素,则未指定集合的行为。该禁令的一个特例是集合不允许将自身作为元素包含。

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

不可修改集

Set.of Set.copyOf 静态工厂方法提供了一种创建不可修改集的便捷方法。通过这些方法创建的Set实例具有以下特征:

  • 他们是不可修改的。不能添加或删除元素。在 Set 上调用任何 mutator 方法将始终导致抛出 UnsupportedOperationException。但是,如果包含的元素本身是可变的,这可能会导致 Set 行为不一致或其内容看起来发生了变化。
  • 他们不允许 null 元素。尝试使用 null 元素创建它们会导致 NullPointerException
  • 如果所有元素都是可序列化的,则它们是可序列化的。
  • 他们在创建时拒绝重复元素。传递给静态工厂方法的重复元素导致 IllegalArgumentException
  • set 元素的迭代顺序未指定,可能会发生变化。
  • 他们是 value-based 。程序员应该将 equal 实例视为可互换的,不应将它们用于同步,否则可能会发生不可预测的行为。例如,在未来的版本中,同步可能会失败。调用者不应假设返回实例的身份。工厂可以自由创建新实例或重用现有实例。
  • 它们按照 Serialized Form 页面上的指定进行序列化。

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

自从:
1.2
参见:
  • 方法总结

    修饰符和类型
    方法
    描述
    boolean
    add(E e)
    如果指定的元素不存在,则将其添加到此集合(可选操作)。
    boolean
    addAll(Collection<? extends E> c)
    将指定集合中的所有元素添加到此集合(如果它们不存在)(可选操作)。
    void
    从此集合中删除所有元素(可选操作)。
    boolean
    如果此集合包含指定元素,则返回 true
    boolean
    如果此集合包含指定集合的所有元素,则返回 true
    static <E> Set<E>
    copyOf(Collection<? extends E> coll)
    返回包含给定 Collection 元素的 不可修改的集合
    boolean
    比较指定对象与此集合是否相等。
    int
    返回此集合的哈希码值。
    boolean
    如果此集合不包含任何元素,则返回 true
    返回此集合中元素的迭代器。
    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
    如果指定元素存在(可选操作),则从该集合中移除指定元素。
    boolean
    从此集合中删除指定集合中包含的所有元素(可选操作)。
    boolean
    仅保留此集合中包含在指定集合中的元素(可选操作)。
    int
    size()
    返回此集合中的元素数(其基数)。
    default Spliterator<E>
    在此集合中的元素上创建一个 Spliterator
    返回包含此集合中所有元素的数组。
    <T> T[]
    toArray(T[] a)
    返回包含此集合中所有元素的数组;返回数组的运行时类型是指定数组的类型。

    在接口 java.util.Collection 中声明的方法

    parallelStream, removeIf, stream, toArray

    在接口 java.lang.Iterable 中声明的方法

    forEach
  • 方法详情

    • 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。更正式地说,返回 true 当且仅当此集合包含元素 e 使得 Objects.equals(o, e)
      指定者:
      contains 在接口 Collection<E>
      参数:
      o - 要测试其在该集合中是否存在的元素
      返回:
      true 如果此集合包含指定元素
      抛出:
      ClassCastException - 如果指定元素的类型与此集合不兼容 (optional)
      NullPointerException - 如果指定元素为空且此集合不允许空元素 (optional)
    • iterator

      Iterator <E > iterator()
      返回此集合中元素的迭代器。返回的元素没有特定的顺序(除非这个集合是某个提供保证的类的实例)。
      指定者:
      iterator 在接口 Collection<E>
      指定者:
      iterator 在接口 Iterable<E>
      返回:
      此集合中元素的迭代器
    • toArray

      Object [] toArray()
      返回包含此集合中所有元素的数组。如果此集合对其迭代器返回其元素的顺序作出任何保证,则此方法必须以相同的顺序返回元素。

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

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

      指定者:
      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() 相同。
      指定者:
      toArray 在接口 Collection<E>
      类型参数:
      T - 包含集合的数组的组件类型
      参数:
      a - 要存储此集合元素的数组,如果它足够大的话;否则,为此分配一个相同运行时类型的新数组。
      返回:
      包含此集合中所有元素的数组
      抛出:
      ArrayStoreException - 如果指定数组的运行时类型不是此集合中每个元素的运行时类型的超类型
      NullPointerException - 如果指定数组为空
    • add

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

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

      指定者:
      add 在接口 Collection<E>
      参数:
      e - 要添加到此集合的元素
      返回:
      true 如果此集合尚未包含指定元素
      抛出:
      UnsupportedOperationException - 如果此集合不支持 add 操作
      ClassCastException - 如果指定元素的类阻止它被添加到这个集合
      NullPointerException - 如果指定元素为空且此集合不允许空元素
      IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此集合
    • remove

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

      boolean containsAll(Collection <?> c)
      如果此集合包含指定集合的所有元素,则返回 true。如果指定的集合也是一个集合,如果是一个集合,则此方法返回true子集这套。
      指定者:
      containsAll 在接口 Collection<E>
      参数:
      c - 要检查此集合中是否包含的集合
      返回:
      true 如果此集合包含指定集合的所有元素
      抛出:
      ClassCastException - 如果指定集合中的一个或多个元素的类型与此集合不兼容 (optional)
      NullPointerException - 如果指定的集合包含一个或多个空元素并且此集合不允许空元素 (optional),或者如果指定的集合为空
      参见:
    • addAll

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

      boolean retainAll(Collection <?> c)
      仅保留此集合中包含在指定集合中的元素(可选操作)。换句话说,从该集合中移除所有未包含在指定集合中的元素。如果指定的集合也是一个集合,则此操作有效地修改了这个集合,使其值为intersection两组中的。
      指定者:
      retainAll 在接口 Collection<E>
      参数:
      c - 包含要保留在此集合中的元素的集合
      返回:
      true 如果此集合因调用而更改
      抛出:
      UnsupportedOperationException - 如果此集合不支持 retainAll 操作
      ClassCastException - 如果此集合的元素类与指定集合不兼容 (optional)
      NullPointerException - 如果此集合包含空元素并且指定的集合不允许空元素 (optional),或者如果指定的集合为空
      参见:
    • removeAll

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

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

      boolean equals(Object  o)
      比较指定对象与此集合是否相等。如果指定对象也是一个集合,则返回 true,这两个集合具有相同的大小,并且指定集合的每个成员都包含在这个集合中(或者等效地,这个集合的每个成员都包含在指定集合中)。此定义确保 equals 方法在 set 接口的不同实现中正常工作。
      指定者:
      equals 在接口 Collection<E>
      重写:
      equals 在类 Object
      参数:
      o - 要与此集合进行相等比较的对象
      返回:
      true如果指定的对象等于这个集合
      参见:
    • hashCode

      int hashCode()
      返回此集合的哈希码值。集合的哈希码定义为集合中元素的哈希码之和,其中null元素的哈希码定义为零。这确保 s1.equals(s2) 暗示 s1.hashCode()==s2.hashCode() 对于任何两个集合 s1s2,正如 Object.hashCode() 的总合同所要求的那样。
      指定者:
      hashCode 在接口 Collection<E>
      重写:
      hashCode 在类 Object
      返回:
      该集合的哈希码值
      参见:
    • spliterator

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

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

      指定者:
      spliterator 在接口 Collection<E>
      指定者:
      spliterator 在接口 Iterable<E>
      实现要求:
      默认实现从集合的 Iterator 创建一个 late-binding spliterator。拆分器继承了集合迭代器的 fail-fast 属性。

      创建的 Spliterator 还报告 Spliterator.SIZED

      实现注意事项:
      创建的 Spliterator 还报告 Spliterator.SUBSIZED
      返回:
      a 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 - Set 的元素类型
      参数:
      e1 - 第一个元素
      e2 - 第二个元素
      返回:
      包含指定元素的 Set
      抛出:
      IllegalArgumentException - 如果元素重复
      NullPointerException - 如果元素是 null
      自从:
      9
    • of

      static <E> Set <E> of(E e1, E e2, E e3)
      返回包含三个元素的不可修改的集合。有关详细信息,请参阅 不可修改集
      类型参数:
      E - Set 的元素类型
      参数:
      e1 - 第一个元素
      e2 - 第二个元素
      e3 - 第三个元素
      返回:
      包含指定元素的 Set
      抛出:
      IllegalArgumentException - 如果有任何重复元素
      NullPointerException - 如果元素是 null
      自从:
      9
    • of

      static <E> Set <E> of(E e1, E e2, E e3, E e4)
      返回包含四个元素的不可修改的集合。有关详细信息,请参阅 不可修改集
      类型参数:
      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)
      返回包含五个元素的不可修改的集合。有关详细信息,请参阅 不可修改集
      类型参数:
      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)
      返回包含六个元素的不可修改的集合。有关详细信息,请参阅 不可修改集
      类型参数:
      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)
      返回包含七个元素的不可修改的集合。有关详细信息,请参阅 不可修改集
      类型参数:
      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)
      返回包含八个元素的不可修改的集合。有关详细信息,请参阅 不可修改集
      类型参数:
      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)
      返回包含九个元素的不可修改的集合。有关详细信息,请参阅 不可修改集
      类型参数:
      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)
      返回包含十个元素的不可修改的集合。有关详细信息,请参阅 不可修改集
      类型参数:
      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)
      返回包含任意数量元素的不可修改集。有关详细信息,请参阅 不可修改集
      API 注意:
      此方法还接受单个数组作为参数。结果集的元素类型将是数组的组件类型,集的大小将等于数组的长度。要使用作为数组的单个元素创建集合,请执行以下操作:
      
         String[] array = ... ;
         Set<String[]> list = Set.<String[]>of(array);
        
      这将导致调用 Set.of(E) 方法。
      类型参数:
      E - Set 的元素类型
      参数:
      elements - 要包含在集合中的元素
      返回:
      包含指定元素的 Set
      抛出:
      IllegalArgumentException - 如果有任何重复元素
      NullPointerException - 如果元素是 null 或者数组是 null
      自从:
      9
    • copyOf

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