模块  java.base
软件包  java.util

Interface Set<E>

  • 参数类型
    E - 此集维护的元素类型
    All Superinterfaces:
    Collection<E> ， Iterable<E>
    All Known Subinterfaces:
    EventSet ， NavigableSet<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)和最多一个null元素。 正如其名称所暗示的，此接口模拟数学集抽象。

    该Set接口放置额外的约定，超过从继承Collection接口，所有构造函数的合同，而位于该合同add ， equals和hashCode方法。 为方便起见，此处还包括其他继承方法的声明。 （这些声明附带的规范是针对Set接口定制的，但它们不包含任何其他规定。）

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

    注意：如果将可变对象用作set元素，则必须非常小心。 如果在对象是集合中的元素时以影响equals比较的方式更改对象的值，则不指定集合的行为。 这种禁令的一个特例是，不允许将一个集合作为一个元素包含在内。

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

    Unmodifiable Sets

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

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

    此接口是Java Collections Framework的成员。

    从以下版本开始：
    1.2
    另请参见：
    Collection ， List ， SortedSet ， HashSet ， TreeSet ， AbstractSet ， Collections.singleton(java.lang.Object) ， Collections.EMPTY_SET

    • 方法摘要

      所有方法  静态方法  实例方法 抽象方法  Default Methods 
      变量和类型 方法 描述
      boolean add​(E e)
      如果指定的元素尚不存在，则将其添加到此集合（可选操作）。
      boolean addAll​(Collection<? extends E> c)
      如果指定集合中的所有元素尚未存在（可选操作），则将其添加到此集合中。
      void clear()
      从该集合中删除所有元素（可选操作）。
      boolean contains​(Object o)
      如果此set包含指定的元素，则返回 true 。
      boolean containsAll​(Collection<?> c)
      如果此集合包含指定集合的所有元素，则返回 true 。
      static <E> Set<E> copyOf​(Collection<? extends E> coll)
      返回包含给定Collection的元素的 unmodifiable Set 。
      boolean equals​(Object o)
      将指定对象与此set进行相等性比较。
      int hashCode()
      返回此set的哈希码值。
      boolean isEmpty()
      如果此集合不包含任何元素，则返回 true 。
      Iterator<E> iterator()
      返回此set中元素的迭代器。
      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()
      返回包含此set中所有元素的数组。
      <T> T[] toArray​(T[] a)
      返回一个包含此set中所有元素的数组; 返回数组的运行时类型是指定数组的运行时类型。

    • 方法详细信息

      • 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)
        如果此set包含指定的元素，则返回true 。 更正式地说，返回true当且仅当此set包含的元素e ，使得Objects.equals(o, e) 。
        Specified by:
        contains在界面 Collection<E>
        参数
        o - 要测试其在此集合中的存在的元素
        结果
        true如果此集包含指定的元素
        异常
        ClassCastException - 如果指定元素的类型与此集不兼容（ optional ）
        NullPointerException - 如果指定的元素为null且此set不允许null元素（ optional ）

      • iterator

        Iterator<E> iterator()
        返回此set中元素的迭代器。 元素以无特定顺序返回（除非此集合是某个提供保证的类的实例）。
        Specified by:
        iterator在界面 Collection<E>
        Specified by:
        iterator接口 Iterable<E>
        结果
        这个集合中元素的迭代器

      • toArray

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

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

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

        Specified by:
        toArray接口 Collection<E>
        结果
        包含此集合中所有元素的数组

      • toArray

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

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

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

        与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 - 如果指定的数组为null

      • add

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

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

        Specified by:
        add接口 Collection<E>
        参数
        e - 要添加到此集合的元素
        结果
        true如果此集合尚未包含指定的元素
        异常
        UnsupportedOperationException - 如果此集合不支持 add操作
        ClassCastException - 如果指定元素的类阻止将其添加到此集合中
        NullPointerException - 如果指定的元素为null且此set不允许null元素
        IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此集合中

      • remove

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

      • containsAll

        boolean containsAll​(Collection<?> c)
        如果此集合包含指定集合的所有元素，则返回true 。 如果指定的集合也是集合，则此方法返回true如果它是此集合的子集）。
        Specified by:
        containsAll接口 Collection<E>
        参数
        c - 要检查此集合中的包含的集合
        结果
        true如果此集包含指定集合的所有元素
        异常
        ClassCastException - 如果指定集合中的一个或多个元素的类型与此集不兼容（ optional ）
        NullPointerException - 如果指定的集合包含一个或多个null元素，并且此set不允许null元素（ optional ），或者指定的集合为null
        另请参见：
        contains(Object)

      • addAll

        boolean addAll​(Collection<? extends E> c)
        如果指定集合中的所有元素尚未存在（可选操作），则将其添加到此集合中。 如果指定的集合也是一个集合，则addAll操作会有效地修改此集合，以使其值为两个集合的并集。 如果在操作正在进行时修改了指定的集合，则此操作的行为是不确定的。
        Specified by:
        addAll接口 Collection<E>
        参数
        c - 包含要添加到此集合的元素的集合
        结果
        true如果此设置因呼叫而更改
        异常
        UnsupportedOperationException - 如果此集合不支持 addAll操作
        ClassCastException - 如果指定集合的元素的类阻止将其添加到此集合中
        NullPointerException - 如果指定的集合包含一个或多个null元素，并且此集合不允许null元素，或者指定的集合为null
        IllegalArgumentException - 如果指定集合的某个元素的某些属性阻止将其添加到此集合中
        另请参见：
        add(Object)

      • retainAll

        boolean retainAll​(Collection<?> c)
        仅保留此集合中包含在指定集合中的元素（可选操作）。 换句话说，从该集合中删除未包含在指定集合中的所有元素。 如果指定的集合也是一个集合，则此操作会有效地修改此集合，使其值为两个集合的交集 。
        Specified by:
        retainAll在界面 Collection<E>
        参数
        c - 包含要在此集中保留的元素的集合
        结果
        true如果此设置因呼叫而更改
        异常
        UnsupportedOperationException - 如果此集合不支持 retainAll操作
        ClassCastException - 如果此集合的元素的类与指定的集合不兼容（ optional ）
        NullPointerException - 如果此set包含null元素且指定的collection不允许null元素（ optional ），或者指定的collection是null
        另请参见：
        remove(Object)

      • removeAll

        boolean removeAll​(Collection<?> c)
        从此集合中删除指定集合中包含的所有元素（可选操作）。 如果指定的集合也是一个集合，则此操作会有效地修改此集合，以使其值为两个集合的不对称集合差异 。
        Specified by:
        removeAll接口 Collection<E>
        参数
        c - 包含要 c集合中删除的元素的集合
        结果
        true如果此设置因呼叫而更改
        异常
        UnsupportedOperationException - 如果此集合不支持 removeAll操作
        ClassCastException - 如果此集合的元素的类与指定的集合不兼容（ optional ）
        NullPointerException - 如果此set包含null元素且指定的collection不允许null元素（ optional ），或者指定的collection是null
        另请参见：
        remove(Object) ， contains(Object)

      • clear

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

      • equals

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

      • hashCode

        int hashCode()
        返回此set的哈希码值。 集合的哈希码被定义为集合中元素的哈希码的总和，其中null元素的哈希码被定义为零。 这确保了s1.equals(s2)暗示s1.hashCode()==s2.hashCode()对于任何两组s1和s2 ，如s2的一般合同所要求的那样 。
        Specified by:
        hashCode接口 Collection<E>
        重写：
        hashCode类 Object
        结果
        此集的哈希码值
        另请参见：
        Object.equals(Object) ， equals(Object)

      • of

        static <E> Set<E> of()
        返回包含零元素的不可修改集。 有关详细信息，请参阅Unmodifiable Sets 。
        参数类型
        E - Set的元素类型
        结果
        空的 Set
        从以下版本开始：
        9

      • of

        static <E> Set<E> of​(E e1)
        返回包含一个元素的不可修改集。 有关详细信息，请参阅Unmodifiable Sets 。
        参数类型
        E - Set的元素类型
        参数
        e1 - 单个元素
        结果
        包含指定元素的 Set
        异常
        NullPointerException - 如果元素是 null
        从以下版本开始：
        9

      • of

        static <E> Set<E> of​(E e1,                     E e2)
        返回包含两个元素的不可修改集。 有关详细信息，请参见Unmodifiable Sets 。
        参数类型
        E - Set的元素类型
        参数
        e1 - 第一个元素
        e2 - 第二个元素
        结果
        包含指定元素的 Set
        异常
        IllegalArgumentException - 如果元素是重复的
        NullPointerException - 如果元素是 null
        从以下版本开始：
        9

      • of

        static <E> Set<E> of​(E e1,                     E e2,                     E e3)
        返回包含三个元素的不可修改集。 有关详细信息，请参阅Unmodifiable Sets 。
        参数类型
        E - Set的元素类型
        参数
        e1 - 第一个元素
        e2 - 第二个元素
        e3 - 第三个要素
        结果
        包含指定元素的 Set
        异常
        IllegalArgumentException - 如果有任何重复的元素
        NullPointerException - 如果元素是 null
        从以下版本开始：
        9

      • of

        static <E> Set<E> of​(E e1,                     E e2,                     E e3,                     E e4)
        返回包含四个元素的不可修改集。 有关详细信息，请参阅Unmodifiable Sets 。
        参数类型
        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)
        返回包含五个元素的不可修改集。 有关详细信息，请参阅Unmodifiable Sets 。
        参数类型
        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)
        返回包含六个元素的不可修改集。 有关详细信息，请参阅Unmodifiable Sets 。
        参数类型
        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)
        返回包含七个元素的不可修改集。 有关详细信息，请参阅Unmodifiable Sets 。
        参数类型
        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)
        返回包含八个元素的不可修改集。 有关详细信息，请参阅Unmodifiable Sets 。
        参数类型
        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)
        返回包含九个元素的不可修改集。 有关详细信息，请参阅Unmodifiable Sets 。
        参数类型
        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)
        返回包含十个元素的不可修改集。 有关详细信息，请参见Unmodifiable Sets 。
        参数类型
        E - Set的元素类型
        参数
        e1 - 第一个元素
        e2 - 第二个元素
        e3 - 第三个要素
        e4 - 第四个要素
        e5 - 第五个元素
        e6 - 第六个元素
        e7 - 第七个要素
        e8 - 第八个元素
        e9 - 第九个元素
        e10 - 第十个元素
        结果
        包含指定元素的 Set
        异常
        IllegalArgumentException - 如果有任何重复的元素
        NullPointerException - 如果元素是 null
        从以下版本开始：
        9

      • of

        @SafeVarargsstatic <E> Set<E> of​(E... elements)
        返回包含任意数量元素的不可修改集。 有关详细信息，请参阅Unmodifiable Sets 。
        API Note:
        此方法还接受单个数组作为参数。 结果集的元素类型将是数组的组件类型，并且集的大小将等于数组的长度。 要使用作为数组的单个元素创建集，请执行以下操作： 
           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的元素的unmodifiable Set 。 给定的Collection不能为null，并且不能包含任何null元素。 如果给定的Collection包含重复元素，则保留重复项的任意元素。 如果随后修改了给定的Collection，则返回的Set将不会反映此类修改。
        Implementation Note:
        如果给定的Collection是 unmodifiable Set ，则调用copyOf通常不会创建副本。
        参数类型
        E - Set的元素类型
        参数
        coll - Collection绘制元素的 Collection必须为非null
        结果
        Set包含给定 Collection的元素
        异常
        NullPointerException - 如果coll为null，或者它包含任何空值
        从以下版本开始：
        10