鸿蒙OS AbstractCollection

AbstractCollection

java.lang.Object

|---java.util.AbstractCollection<E&

public abstract class AbstractCollection<E>
extends Object
implements Collection<E>

此类提供 Collection 接口的骨架实现，以最大限度地减少实现此接口所需的工作量。

要实现一个不可修改的集合，程序员只需要扩展这个类并提供迭代器和大小方法的实现。 （迭代器方法返回的迭代器必须实现hasNext和next。）

要实现一个可修改的集合，程序员必须另外重写这个类的 add 方法（否则会抛出 UnsupportedOperationException），并且迭代器方法返回的迭代器必须另外实现它的 remove 方法。

根据 Collection 接口规范中的建议，程序员通常应该提供一个 void（无参数）和 Collection 构造函数。

此类中每个非抽象方法的文档都详细描述了它的实现。如果正在实现的集合允许更有效的实现，则可以覆盖这些方法中的每一个。

此类是 Java 集合框架的成员。

构造函数摘要

修饰符	构造函数	描述
protected	AbstractCollection()	唯一的构造函数。

方法总结

修饰符和类型	方法	描述
boolean	add(E e)	确保此集合包含指定的元素（可选操作）。
boolean	addAll(Collection<? extends E> c)	将指定集合中的所有元素添加到此集合（可选操作）。
void	clear()	从此集合中移除所有元素（可选操作）。
boolean	contains(Object o)	如果此集合包含指定元素，则返回 true。
boolean	containsAll(Collection<?> c)	如果此集合包含指定集合中的所有元素，则返回 true。
boolean	isEmpty()	如果此集合不包含任何元素，则返回 true。
abstract IteratorE	iterator()	返回此集合中包含的元素的迭代器。
boolean	remove(Object o)	如果存在，则从此集合中删除指定元素的单个实例（可选操作）。
boolean	removeAll(Collection<?> c)	移除此集合的所有也包含在指定集合中的元素（可选操作）。
boolean	retainAll(Collection<?> c)	仅保留此集合中包含在指定集合中的元素（可选操作）。
abstract int	size()	返回此集合中的元素数。
Object[]	toArray()	返回一个包含此集合中所有元素的数组。
<T> T[]	toArray(T[] a)	返回一个包含此集合中所有元素的数组； 返回数组的运行时类型是指定数组的运行时类型。
String	toString()	返回此集合的字符串表示形式。

从接口 java.util.Collection 继承的方法
equals, hashCode, parallelStream, removeIf, spliterator, stream

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

从类 java.lang.Object 继承的方法
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

构造函数详细信息

AbstractCollection

protected AbstractCollection()

唯一的构造函数。 （用于子类构造函数的调用，通常是隐式的。）

方法详情

iterator

public abstract IteratorE iterator()

返回此集合中包含的元素的迭代器。

指定者：

接口 CollectionE 中的迭代器

指定者：

接口 IterableE 中的迭代器

返回:

此集合中包含的元素的迭代器

size

public abstract int size()

从接口复制的描述：集合

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

指定者：

接口 CollectionE 中的大小

返回:

此集合中的元素数

isEmpty

public boolean isEmpty()

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

此实现返回 size() == 0。

指定者：

接口 CollectionE 中的 isEmpty

返回:

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

contains

public boolean contains(Object o)

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

此实现迭代集合中的元素，依次检查每个元素是否与指定元素相等。

指定者：

包含在接口 CollectionE 中

参数：

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

返回:

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

Throws:

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

toArray

public Object[] toArray()

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

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

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

此实现返回一个数组，其中包含此集合的迭代器返回的所有元素，以相同的顺序存储在数组的连续元素中，从索引 0 开始。返回数组的长度等于迭代器返回的元素数，即使此集合的大小在迭代期间发生变化，如果集合允许在迭代期间进行并发修改，也可能发生这种情况。 size 方法仅作为优化提示调用；即使迭代器返回不同数量的元素，也会返回正确的结果。

该方法等价于：

 List<E> list = new ArrayList<E>(size());
 for (E e : this)
     list.add(e);
 return list.toArray();

指定者：

接口 CollectionE 中的 toArray

返回:

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

toArray

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

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

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

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

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

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

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

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

此实现返回一个数组，其中包含此集合的迭代器以相同顺序返回的所有元素，存储在数组的连续元素中，从索引 0 开始。如果迭代器返回的元素数量太大而无法放入指定的数组 ，然后元素在一个新分配的数组中返回，其长度等于迭代器返回的元素数，即使此集合的大小在迭代期间发生变化，如果集合允许在迭代期间进行并发修改，可能会发生这种情况。 size 方法仅作为优化提示调用； 即使迭代器返回不同数量的元素，也会返回正确的结果。

该方法等价于：

 List<E> list = new ArrayList<E>(size());
 for (E e : this)
     list.add(e);
 return list.toArray(a);

指定者：

接口 CollectionE 中的 toArray

类型参数：

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

参数:

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

返回:

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

Throws:

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

add

public boolean add(E e)

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

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

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

此实现总是抛出 UnsupportedOperationException。

指定者：

添加接口CollectionE

参数：

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

返回:

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

Throws:

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

remove

public boolean remove(Object o)

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

此实现遍历集合以查找指定元素。 如果找到该元素，则使用迭代器的 remove 方法从集合中删除该元素。

请注意，如果此集合的迭代器方法返回的迭代器未实现 remove 方法并且此集合包含指定的对象，则此实现将引发 UnsupportedOperationException。

指定者：

在接口 CollectionE 中删除

参数：

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

返回:

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

Throws:

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

containsAll

public boolean containsAll(Collection<?> c)

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

这个实现遍历指定的集合，依次检查迭代器返回的每个元素，看它是否包含在这个集合中。 如果所有元素都如此包含，则返回 true，否则返回 false。

指定者：

接口 CollectionE 中的 containsAll

参数：

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

返回:

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

Throws:

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

addAll

public boolean addAll(Collection<? extends E> c)

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

此实现遍历指定的集合，并将迭代器返回的每个对象依次添加到此集合中。

请注意，此实现将抛出 UnsupportedOperationException 除非 add 被覆盖（假设指定的集合是非空的）。

指定者：

接口 CollectionE 中的 addAll

参数：

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

返回:

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

Throws:

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

removeAll

public boolean removeAll(Collection<?> c)

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

这个实现迭代这个集合，依次检查迭代器返回的每个元素，看看它是否包含在指定的集合中。 如果它如此包含，则使用迭代器的 remove 方法将其从该集合中删除。

请注意，如果迭代器方法返回的迭代器没有实现 remove 方法并且此集合包含一个或多个与指定集合共有的元素，则此实现将抛出 UnsupportedOperationException。

指定者：

接口 CollectionE 中的 removeAll

参数：

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

返回:

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

Throws:

Throw名称	Throw描述
UnsupportedOperationException	如果此集合不支持 removeAll 方法
ClassCastException	如果此集合中的一个或多个元素的类型与指定的集合不兼容（可选）
NullPointerException	if this collection contains one or more null elements and the specified collection does not support null elements (optional), or if the specified collection is null

retainAll

public boolean retainAll(Collection<?> c)

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

这个实现迭代这个集合，依次检查迭代器返回的每个元素，看看它是否包含在指定的集合中。 如果它没有被包含，它会使用迭代器的 remove 方法从这个集合中删除。

请注意，如果迭代器方法返回的迭代器未实现 remove 方法并且此集合包含指定集合中不存在的一个或多个元素，则此实现将抛出 UnsupportedOperationException。

指定者：

接口CollectionE中的retainAll

参数：

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

返回:

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

Throws:

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

clear

public void clear()

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

此实现迭代此集合，使用 Iterator.remove 操作删除每个元素。 大多数实现可能会选择覆盖此方法以提高效率。

请注意，如果此集合的迭代器方法返回的迭代器未实现 remove 方法并且此集合非空，则此实现将抛出 UnsupportedOperationException。

指定者：

在界面 CollectionE 中清除

Throws:

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

toString

public String toString()

返回此集合的字符串表示形式。 字符串表示由集合元素的列表组成，按其迭代器返回的顺序排列，用方括号 ("[]") 括起来。 相邻元素由字符“、”（逗号和空格）分隔。 通过 String#valueOf(Object) 将元素转换为字符串。

覆盖：

类 Object 中的 toString

返回:

此集合的字符串表示形式