鸿蒙OS Collection

Collection

public interface Collection<E>
extends Iterable<E>

集合层次结构中的根接口。 集合表示一组对象，称为其元素。 一些集合允许重复元素，而另一些则不允许。 有些是有序的，有些是无序的。 JDK 不提供此接口的任何直接实现：它提供更具体的子接口（如 Set 和 List）的实现。 此接口通常用于传递集合并在需要最大通用性的地方操作它们。

Bags 或 multisets（可能包含重复元素的无序集合）应该直接实现这个接口。

所有通用 Collection 实现类（通常通过其子接口之一间接实现 Collection）应提供两个“标准”构造函数：一个 void（无参数）构造函数，它创建一个空集合，以及一个具有单个参数类型的构造函数集合，它创建一个具有与其参数相同的元素的新集合。实际上，后一个构造函数允许用户复制任何集合，生成所需实现类型的等效集合。没有办法强制执行此约定（因为接口不能包含构造函数），但 Java 平台库中的所有通用 Collection 实现都遵守。

此接口中包含的“破坏性”方法，即修改其操作的集合的方法，指定在此集合不支持操作时抛出 UnsupportedOperationException。如果是这种情况，如果调用对集合没有影响，这些方法可能会（但不是必须）抛出 UnsupportedOperationException。例如，如果要添加的集合为空，则对不可修改的集合调用 addAll(java.util.Collection) 方法可能但不是必须抛出异常。

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

由每个集合决定自己的同步策略。在实现没有更强有力的保证的情况下，未定义的行为可能是由于对正在被另一个线程改变的集合上的任何方法的调用引起的；这包括直接调用，将集合传递给可能执行调用的方法，以及使用现有迭代器检查集合。

Collections Framework 接口中的许多方法都是根据 Object#equals(Object) 方法定义的。例如，contains(Object o) 方法的规范说：“当且仅当此集合包含至少一个元素 e 使得 (o==null ? e==null : o.equals(e)) 。”本规范不应被解释为暗示使用非空参数 o 调用 Collection.contains 将导致对任何元素 e 调用 o.equals(e)。实现可以自由地实现优化，从而避免调用 equals，例如，首先比较两个元素的哈希码。 （Object#hashCode() 规范保证具有不相等哈希码的两个对象不能相等。）更一般地说，各种集合框架接口的实现可以自由地利用底层 Object 方法的指定行为，只要实现者认为它合适.

一些执行集合递归遍历的集合操作可能会失败，但对于集合直接或间接包含自身的自引用实例的异常。 这包括 clone()、equals()、hashCode() 和 toString() 方法。 实现可以选择处理自引用场景，但是大多数当前的实现不这样做。

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

方法总结

修饰符和类型	方法	描述
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。
IteratorE	iterator()	返回此集合中元素的迭代器。
default StreamE	parallelStream()	返回以该集合为源的可能并行 Stream。
boolean	remove(Object o)	从此集合中移除指定元素的单个实例（如果存在）（可选操作）。
boolean	removeAll(Collection<?> c)	移除此集合的所有也包含在指定集合中的元素（可选操作）。
default boolean	removeIf(Predicate<? super E> filter)	删除此集合中满足给定谓词的所有元素。
boolean	retainAll(Collection<?> c)	仅保留此集合中包含在指定集合中的元素（可选操作）。
int	size()	返回此集合中的元素数。
default SpliteratorE	spliterator()	在此集合中的元素上创建一个 Spliterator。
default StreamE	stream()	返回以此集合为源的顺序流。
Object[]	toArray()	返回一个包含此集合中所有元素的数组。
<T> T[]	toArray(T[] a)	返回一个包含此集合中所有元素的数组； 返回数组的运行时类型是指定数组的运行时类型。

从接口 java.lang.Iterable 继承的方法
forEach

方法详情

size

int size()

返回此集合中的元素数。 如果此集合包含多个 Integer.MAX_VALUE 元素，则返回 Integer.MAX_VALUE。

返回:

此集合中的元素数

isEmpty

boolean isEmpty()

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

返回:

如果此集合不包含任何元素，则为 true

contains

boolean contains(Object o)

如果此集合包含指定元素，则返回 true。 更正式地说，当且仅当此集合包含至少一个元素 e 满足 (o==null ? e==null : o.equals(e)) 时才返回 true。

参数：

参数名称	参数描述
o	要测试其在此集合中的存在的元素

返回：

如果此集合包含指定元素，则为 true

Throws:

Throw名称	Throw描述
ClassCastException	如果指定元素的类型与此集合不兼容（可选）
NullPointerException	如果指定元素为空且此集合不允许空元素（可选）

iterator

IteratorE iterator()

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

指定者：

接口 IterableE 中的迭代器

返回:

此集合中元素的迭代器

toArray

Object[] toArray()

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

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

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

返回:

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

toArray

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

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

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

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

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

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

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

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

类型参数：

类型参数名称	类型参数描述
T	包含集合的数组的运行时类型

参数:

参数名称	参数描述
a	这个集合的元素要存储到的数组，如果它足够大的话； 否则，将为此目的分配相同运行时类型的新数组。

返回:

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

Throws:

Throw名称	Throw描述
ArrayStoreException	如果指定数组的运行时类型不是此集合中每个元素的运行时类型的超类型
NullPointerException	如果指定的数组为空

add

boolean add(E e)

确保此集合包含指定的元素（可选操作）。 如果此集合因调用而更改，则返回 true。 （如果此集合不允许重复且已包含指定元素，则返回 false。）

支持此操作的集合可能会限制可以添加到此集合的元素。 特别是，一些集合会拒绝添加空元素，而另一些则会对可能添加的元素类型施加限制。 集合类应在其文档中明确指定对可以添加哪些元素的任何限制。

如果一个集合拒绝添加一个特定元素，除了它已经包含该元素之外，它必须抛出一个异常（而不是返回 false）。 这保留了在此调用返回后集合始终包含指定元素的不变量。

参数：

参数名称	参数描述
e	要确保在此集合中存在的元素

返回:

如果此集合因调用而更改，则为 true

Throws:

Throw名称	Throw描述
UnsupportedOperationException	如果此集合不支持添加操作
ClassCastException	如果指定元素的类阻止它被添加到此集合中
NullPointerException	如果指定元素为 null 并且此集合不允许 null 元素
IllegalArgumentException	如果元素的某些属性阻止它被添加到此集合中
IllegalStateException	如果此时由于插入限制无法添加元素

remove

boolean remove(Object o)

从此集合中移除指定元素的单个实例（如果存在）（可选操作）。 更正式地说，如果这个集合包含一个或多个这样的元素，则删除一个元素 e 使得 (o==null ? e==null : o.equals(e))。 如果此集合包含指定元素（或等效地，如果此集合因调用而更改），则返回 true。

参数：

参数名称	参数描述
o	要从此集合中删除的元素（如果存在）

返回:

如果由于此调用而删除了元素，则为 true

Throws:

Throw名称	Throw描述
ClassCastException	如果指定元素的类型与此集合不兼容（可选）
NullPointerException	如果指定元素为空且此集合不允许空元素（可选）
UnsupportedOperationException	如果此集合不支持删除操作

containsAll

boolean containsAll(Collection<?> c)

如果此集合包含指定集合中的所有元素，则返回 true。

参数：

参数名称	参数描述
c	要检查此集合中包含的集合

返回:

如果此集合包含指定集合中的所有元素，则为 true

Throws:

Throw名称	Throw描述
ClassCastException	如果指定集合中的一个或多个元素的类型与该集合不兼容（可选）
NullPointerException	如果指定的集合包含一个或多个空元素并且此集合不允许空元素（可选），或者指定的集合为空。

addAll

boolean addAll(Collection<? extends E> c)

将指定集合中的所有元素添加到此集合（可选操作）。 如果在操作正在进行时修改了指定的集合，则此操作的行为是未定义的。 （这意味着如果指定的集合是这个集合，并且这个集合是非空的，那么这个调用的行为是未定义的。）

参数：

参数名称	参数描述
c	包含要添加到此集合的元素的集合

返回:

如果此集合因调用而更改，则为 true

Throws:

Throw名称	Throw描述
UnsupportedOperationException	如果此集合不支持 addAll 操作
ClassCastException	如果指定集合的元素的类阻止将其添加到此集合中
NullPointerException	如果指定的集合包含空元素并且此集合不允许空元素，或者指定的集合为空
IllegalArgumentException	如果指定集合的某个元素的某些属性阻止它被添加到此集合中
IllegalStateException	如果由于插入限制，此时不能添加所有元素

removeAll

boolean removeAll(Collection<?> c)

移除此集合的所有也包含在指定集合中的元素（可选操作）。 在此调用返回后，此集合将不包含与指定集合共有的元素。

参数：

参数名称	参数描述
c	包含要从此集合中删除的元素的集合

返回:

如果此集合因调用而更改，则为 true

Throws:

Throw名称	Throw描述
UnsupportedOperationException	如果此集合不支持 removeAll 方法
ClassCastException	如果此集合中的一个或多个元素的类型与指定的集合不兼容（可选）
NullPointerException	如果此集合包含一个或多个空元素并且指定的集合不支持空元素（可选），或者指定的集合为空

removeIf

default boolean removeIf(Predicate<? super E> filter)

删除此集合中满足给定谓词的所有元素。 在迭代期间或由谓词引发的错误或运行时异常将转发给调用者。

参数：

参数名称	参数描述
filter	对于要删除的元素返回 true 的谓词

返回:

如果删除了任何元素，则为 true

Throws:

Throw名称	Throw描述
NullPointerException	如果指定的过滤器为空
UnsupportedOperationException	如果无法从此集合中删除元素。 如果无法删除匹配的元素，或者通常不支持删除，则实现可能会抛出此异常。

retainAll

boolean retainAll(Collection<?> c)

仅保留此集合中包含在指定集合中的元素（可选操作）。 换句话说，从这个集合中移除所有不包含在指定集合中的元素。

参数：

参数名称	参数描述
c	包含要保留在此集合中的元素的集合

返回:

如果此集合因调用而更改，则为 true

Throws:

Throw名称	Throw描述
UnsupportedOperationException	如果此集合不支持 retainAll 操作
ClassCastException	如果此集合中的一个或多个元素的类型与指定的集合不兼容（可选）
NullPointerException	如果此集合包含一个或多个空元素并且指定的集合不允许空元素（可选），或者指定的集合为空

clear

void clear()

从此集合中移除所有元素（可选操作）。 此方法返回后，集合将为空。

Throws:

Throw名称	Throw描述
UnsupportedOperationException	如果此集合不支持清除操作

equals

boolean equals(Object o)

比较指定对象与此集合是否相等。

虽然 Collection 接口没有为 Object.equals 的一般约定添加任何规定，但“直接”实现 Collection 接口的程序员（换句话说，创建一个是 Collection 但不是 Set 或 List 的类）必须小心如果他们选择覆盖 Object.equals。没有必要这样做，最简单的做法是依赖 Object 的实现，但实现者可能希望实现“值比较”来代替默认的“引用比较”。 （List 和 Set 接口要求进行此类值比较。）

Object.equals 方法的一般约定规定 equals 必须是对称的（换句话说，a.equals(b) 当且仅当 b.equals(a) 时）。 List.equals 和 Set.equals 的协定规定列表仅等于其他列表，并且集合与其他集合相同。因此，当将此集合与任何列表或集合进行比较时，既不实现 List 也不实现 Set 接口的集合类的自定义 equals 方法必须返回 false。 （按照同样的逻辑，不可能编写一个同时正确实现 Set 和 List 接口的类。）

覆盖：

类 Object 中的等于

参数：

参数名称	参数描述
o	要与此集合比较是否相等的对象

返回:

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

hashCode

int hashCode()

返回此集合的哈希码值。 虽然 Collection 接口没有对 Object.hashCode 方法的通用约定添加任何规定，但程序员应注意，任何重写 Object.equals 方法的类也必须重写 Object.hashCode 方法以满足 Object 的通用约定 .hashCode 方法。 特别是，c1.equals(c2) 意味着 c1.hashCode()==c2.hashCode()。

覆盖：

类 Object 中的 hashCode

返回:

此集合的哈希码值

spliterator

default SpliteratorE spliterator()

在此集合中的元素上创建一个 Spliterator。 实现应该记录分离器报告的特征值。 如果拆分器报告 Spliterator#SIZED 并且此集合不包含任何元素，则不需要报告此类特征值。

默认实现应该被可以返回更有效拆分器的子类覆盖。 为了保留 stream() 和 parallelStream()} 方法的预期惰性行为，拆分器应该具有 IMMUTABLE 或 CONCURRENT 的特性，或者是后期绑定的。 如果这些都不可行，则覆盖类应描述拆分器的绑定和结构干扰的文档化策略，并应覆盖 stream() 和 parallelStream() 方法以使用拆分器的供应商创建流，如下所示：

     Stream<E> s = StreamSupport.stream(() -> spliterator(), spliteratorCharacteristics) 

这些要求确保由 stream() 和 parallelStream() 方法生成的流将反映在终端流操作启动时集合的内容。

指定者：

接口 IterableE 中的分离器

返回:

此集合中元素的拆分器

stream

default StreamE stream()

返回以此集合为源的顺序流。

当 spliterator() 方法无法返回 IMMUTABLE、CONCURRENT 或后期绑定的拆分器时，应覆盖此方法。 （有关详细信息，请参阅 spliterator()。）

返回:

此集合中元素的顺序流

parallelStream

default StreamE parallelStream()

返回以该集合为源的可能并行 Stream。 此方法允许返回顺序流。

当 spliterator() 方法无法返回 IMMUTABLE、CONCURRENT 或后期绑定的拆分器时，应覆盖此方法。

返回:

此集合中元素的可能并行 Stream