当前页面: 在线文档首页 > JavaTM 2 Platform Standard Edition 6.0 API 规范中文版

Set (Java Platform SE 6) - JavaTM 2 Platform Standard Edition 6.0 API 规范中文版

---

概述  软件包   类  使用  树  已过时  索引  帮助		JavaTM Platform Standard Ed. 6
上一个类   下一个类	框架    无框架
摘要： 嵌套 | 字段 | 构造方法 | 方法	详细信息： 字段 | 构造方法 | 方法

---

java.util
接口 Set<E>

类型参数：

E - 此 set 所维护元素的类型

所有超级接口：

Collection<E>, Iterable<E>

所有已知子接口：

NavigableSet<E>, SortedSet<E>

所有已知实现类：

AbstractSet, ConcurrentSkipListSet, CopyOnWriteArraySet, EnumSet, HashSet, JobStateReasons, LinkedHashSet, TreeSet

---

public interface Set<E>
extends Collection<E>

一个不包含重复元素的 collection。更确切地讲，set 不包含满足 e1.equals(e2) 的元素对 e1 和 e2，并且最多包含一个 null 元素。正如其名称所暗示的，此接口模仿了数学上的 set 抽象。

在所有构造方法以及 add、equals 和 hashCode 方法的协定上，Set 接口还加入了其他规定，这些规定超出了从 Collection 接口所继承的内容。出于方便考虑，它还包括了其他继承方法的声明（这些声明的规范已经专门针对 Set 接口进行了修改，但是没有包含任何其他的规定）。

对这些构造方法的其他规定是（不要奇怪），所有构造方法必须创建一个不包含重复元素的 set（正如上面所定义的）。

注：如果将可变对象用作 set 元素，那么必须极其小心。如果对象是 set 中某个元素，以一种影响 equals 比较的方式改变对象的值，那么 set 的行为就是不确定的。此项禁止的一个特殊情况是不允许某个 set 包含其自身作为元素。

某些 set 实现对其所包含的元素有所限制。例如，某些实现禁止 null 元素，而某些则对其元素的类型所有限制。试图添加不合格的元素会抛出未经检查的异常，通常是 NullPointerException 或 ClassCastException。试图查询不合格的元素是否存在可能会抛出异常，也可能简单地返回 false；某些实现会采用前一种行为，而某些则采用后者。概括地说，试图对不合格元素执行操作时，如果完成该操作后不会导致在 set 中插入不合格的元素，则该操作可能抛出一个异常，也可能成功，这取决于实现的选择。此接口的规范中将这样的异常标记为“可选”。

此接口是 Java Collections Framework 的成员。

从以下版本开始：

1.2

另请参见：

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

---

方法摘要
boolean	add(E e)           如果 set 中尚未存在指定的元素，则添加此元素（可选操作）。
boolean	addAll(Collection<? extends E> c)           如果 set 中没有指定 collection 中的所有元素，则将其添加到此 set 中（可选操作）。
void	clear()           移除此 set 中的所有元素（可选操作）。
boolean	contains(Object o)           如果 set 包含指定的元素，则返回 true。
boolean	containsAll(Collection<?> c)           如果此 set 包含指定 collection 的所有元素，则返回 true。
boolean	equals(Object o)           比较指定对象与此 set 的相等性。
int	hashCode()           返回 set 的哈希码值。
boolean	isEmpty()           如果 set 不包含元素，则返回 true。
Iterator<E>	iterator()           返回在此 set 中的元素上进行迭代的迭代器。
boolean	remove(Object o)           如果 set 中存在指定的元素，则将其移除（可选操作）。
boolean	removeAll(Collection<?> c)           移除 set 中那些包含在指定 collection 中的元素（可选操作）。
boolean	retainAll(Collection<?> c)           仅保留 set 中那些包含在指定 collection 中的元素（可选操作）。
int	size()           返回 set 中的元素数（其容量）。
Object[]	toArray()           返回一个包含 set 中所有元素的数组。
<T> T[]	toArray(T[] a)           返回一个包含此 set 中所有元素的数组；返回数组的运行时类型是指定数组的类型。

 

方法详细信息

size

int size()

返回 set 中的元素数（其容量）。如果 set 包含多个 Integer.MAX_VALUE 元素，则返回 Integer.MAX_VALUE。

指定者：

接口 Collection<E> 中的 size

返回：

此 set 中的元素数（其容量）

---

isEmpty

boolean isEmpty()

如果 set 不包含元素，则返回 true。

指定者：

接口 Collection<E> 中的 isEmpty

返回：

如果此 set 不包含元素，则返回 true

---

contains

boolean contains(Object o)

如果 set 包含指定的元素，则返回 true。更确切地讲，当且仅当 set 包含满足 (o==null ? e==null : o.equals(e)) 的元素 e 时返回 true。

指定者：

接口 Collection<E> 中的 contains

参数：

o - 要测试此 set 中是否存在的元素

返回：

如果此 set 包含指定的元素，则返回 true

抛出：

ClassCastException - 如果指定元素的类型与此 set 不兼容（可选）

NullPointerException - 如果指定的元素为 null 并且此 set 不允许 null 元素（可选）

---

iterator

Iterator<E> iterator()

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

指定者：

接口 Collection<E> 中的 iterator

指定者：

接口 Iterable<E> 中的 iterator

返回：

在此 set 中的元素上进行迭代的迭代器

---

toArray

Object[] toArray()

返回一个包含 set 中所有元素的数组。如果此 set 对其迭代器返回的元素的顺序作出了某些保证，那么此方法也必须按相同的顺序返回这些元素。

由于此 set 不维护对返回数组的任何引用，因而它是安全的。（换句话说，即使此 set 受到数组的支持，此方法也必须分配一个新的数组）。因此，调用者可以随意修改返回的数组。

此方法充当基于数组的 API 与基于 collection 的 API 之间的桥梁。

指定者：

接口 Collection<E> 中的 toArray

返回：

包含此 set 中所有元素的数组

---

toArray

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

返回一个包含此 set 中所有元素的数组；返回数组的运行时类型是指定数组的类型。如果指定的数组能容纳该 set，则它将在其中返回。否则，将分配一个具有指定数组的运行时类型和此 set 大小的新数组。

如果指定的数组能容纳此 set，并有剩余的空间（即该数组的元素比此 set 多），那么会将列表中紧接该 set 尾部的元素设置为 null。（只有在调用者知道此 set 不包含任何 null 元素时才能用此方法确定此 set 的长度）。

如果此 set 对其迭代器返回的元素的顺序作出了某些保证，那么此方法也必须按相同的顺序返回这些元素。

像 toArray() 方法一样，此方法充当基于数组的 API 与基于 collection 的 API 之间的桥梁。更进一步说，此方法允许对输出数组的运行时类型上进行精确控制，在某些情况下，可以用来节省分配开销。

假定 x 是只包含字符串的一个已知 set。以下代码用来将该 set 转储到一个新分配的 String 数组：

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

注意，toArray(new Object[0]) 和 toArray() 在功能上是相同的。

指定者：

接口 Collection<E> 中的 toArray

参数：

a - 存储此 set 中元素的数组（如果其足够大）；否则将为此分配一个具有相同运行时类型的新数组。

返回：

包含此 set 中所有元素的数组

抛出：

ArrayStoreException - 如果指定数组的运行时类型不是此 set 中所有元素的运行时类型的超类型

NullPointerException - 如果指定的数组为 null

---

add

boolean add(E e)

如果 set 中尚未存在指定的元素，则添加此元素（可选操作）。更确切地讲，如果此 set 没有包含满足 (e==null ? e2==null : e.equals(e2)) 的元素 e2，则向该 set 中添加指定的元素 e。如果此 set 已经包含该元素，则该调用不改变此 set 并返回 false。结合构造方法上的限制，这就可以确保 set 永远不包含重复的元素。

上述规定并未暗示 set 必须接受所有元素；set 可以拒绝添加任意特定的元素，包括 null，并抛出异常，这与 Collection.add 规范中所描述的一样。每个 set 实现应该明确地记录对其可能包含元素的所有限制。

指定者：

接口 Collection<E> 中的 add

参数：

e - 要添加到 set 中的元素

返回：

如果 set 尚未包含指定的元素，则返回 true

抛出：

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

ClassCastException - 如果指定元素的类不允许它添加到此 set

NullPointerException - 如果指定的元素为 null 并且此 set 不允许 null 元素

IllegalArgumentException - 如果指定元素的某些属性不允许它添加到此 set

---

remove

boolean remove(Object o)

如果 set 中存在指定的元素，则将其移除（可选操作）。更确切地讲，如果此 set 中包含满足 (o==null ? e==null : o.equals(e)) 的元素 e，则移除它。如果此 set 包含指定的元素（或者此 set 由于调用而发生更改），则返回 true（一旦调用返回，则此 set 不再包含指定的元素）。

指定者：

接口 Collection<E> 中的 remove

参数：

o - 从 set 中移除的对象（如果存在）

返回：

如果此 set 包含指定的对象，则返回 true

抛出：

ClassCastException - 如果指定元素的类型与此 set 不兼容（可选）

NullPointerException - 如果指定的元素为 null，并且此 set 不允许 null 元素（可选）

UnsupportedOperationException - 如果此 set 不支持 remove 操作

---

containsAll

boolean containsAll(Collection<?> c)

如果此 set 包含指定 collection 的所有元素，则返回 true。如果指定的 collection 也是一个 set，那么当该 collection 是此 set 的子集 时返回 true。

指定者：

接口 Collection<E> 中的 containsAll

参数：

c - 检查是否包含在此 set 中的 collection

返回：

如果此 set 包含指定 collection 中的所有元素，则返回 true

抛出：

ClassCastException - 如果指定 collection 中的一个或多个元素的类型与此 set 不兼容（可选）

NullPointerException - 如果指定的 collection 包含一个或多个 null 元素并且此 set 不允许 null 元素（可选），或者指定的 collection 为 null

另请参见：

contains(Object)

---

addAll

boolean addAll(Collection<? extends E> c)

如果 set 中没有指定 collection 中的所有元素，则将其添加到此 set 中（可选操作）。如果指定的 collection 也是一个 set，则 addAll 操作会实际修改此 set，这样其值是两个 set 的一个并集。如果操作正在进行的同时修改了指定的 collection，则此操作的行为是不确定的。

指定者：

接口 Collection<E> 中的 addAll

参数：

c - 包含要添加到此 set 中的元素的 collection

返回：

如果此 set 由于调用而发生更改，则返回 true

抛出：

UnsupportedOperationException - 如果 set 不支持 addAll 操作

ClassCastException - 如果某些指定 collection 元素的类不允许它添加到此 set

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

IllegalArgumentException - 如果指定 collection 元素的某些属性不允许它添加到此 set

另请参见：

add(Object)

---

retainAll

boolean retainAll(Collection<?> c)

仅保留 set 中那些包含在指定 collection 中的元素（可选操作）。换句话说，移除此 set 中所有未包含在指定 collection 中的元素。如果指定的 collection 也是一个 set，则此操作会实际修改此 set，这样其值是两个 set 的一个交集。

指定者：

接口 Collection<E> 中的 retainAll

参数：

c - 包含要保留到此 set 中的元素的 collection

返回：

如果此 set 由于调用而发生更改，则返回 true

抛出：

UnsupportedOperationException - 如果此 set 不支持 retainAll 操作

ClassCastException - 如果此 set 元素的类与指定的 collection 不兼容（可选）

NullPointerException - 如果此 set 包含 null 元素并且指定的 collection 不支持 null 元素（可选），或者指定的 collection 为 null

另请参见：

remove(Object)

---

removeAll

boolean removeAll(Collection<?> c)

移除 set 中那些包含在指定 collection 中的元素（可选操作）。如果指定的 collection 也是一个 set，则此操作会实际修改此 set，这样其值是两个 set 的一个不对称差集。

指定者：

接口 Collection<E> 中的 removeAll

参数：

c - 包含要从此 set 中移除的元素的 collection

返回：

如果此 set 由于调用而发生更改，则返回 true

抛出：

UnsupportedOperationException - 如果此 set 不支持 removeAll 操作

ClassCastException - 如果此 set 元素的类与指定的 collection 不兼容（可选）

NullPointerException - 如果此 set 包含 null 元素并且指定的 collection 不允许 null 元素（可选），或者指定的 collection 为 null

另请参见：

remove(Object), contains(Object)

---

clear

void clear()

移除此 set 中的所有元素（可选操作）。此调用返回后该 set 将是空的。

指定者：

接口 Collection<E> 中的 clear

抛出：

UnsupportedOperationException - 如果此 set 不支持 clear 方法

---

equals

boolean equals(Object o)

比较指定对象与此 set 的相等性。如果指定的对象也是一个 set，两个 set 的大小相同，并且指定 set 的所有成员都包含在此 set 中（或者，此 set 的所有成员都包含在指定的 set 中也一样），则返回 true。此定义确保了 equals 方法可在不同的 set 接口实现间正常工作。

指定者：

接口 Collection<E> 中的 equals

覆盖：

类 Object 中的 equals

参数：

o - 要与此 set 进行相等性比较的对象

返回：

如果指定的对象等于此 set，则返回 true

另请参见：

Object.hashCode(), Hashtable

---

hashCode

int hashCode()

返回 set 的哈希码值。一个 set 的哈希码定义为此 set 中所有元素的哈希码和，其中 null 元素的哈希码定义为零。这就确保对于任意两个 set s1 和 s2 而言，s1.equals(s2) 就意味着 s1.hashCode()==s2.hashCode()，正如 Object.hashCode() 的常规协定所要求的那样。

指定者：

接口 Collection<E> 中的 hashCode

覆盖：

类 Object 中的 hashCode

返回：

此 set 的哈希码值

另请参见：

Object.equals(Object), equals(Object)

---

概述  软件包   类  使用  树  已过时  索引  帮助		JavaTM Platform Standard Ed. 6
上一个类   下一个类	框架    无框架
摘要： 嵌套 | 字段 | 构造方法 | 方法	详细信息： 字段 | 构造方法 | 方法

---

提交错误或意见
有关更多的 API 参考资料和开发人员文档，请参阅 Java SE 开发人员文档。该文档包含更详细的、面向开发人员的描述，以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。