鸿蒙OS Spliterator

Spliterator

public interface Spliterator<T>

用于遍历和划分源元素的对象。 Spliterator 覆盖的元素来源可以是，例如，数组、集合、IO 通道或生成器函数。

Spliterator 可以单独遍历元素（tryAdvance()）或批量顺序遍历元素（forEachRemaining()）。

Spliterator 也可以将它的一些元素（使用 trySplit()）划分为另一个 Spliterator，以用于可能的并行操作。 使用无法拆分或以高度不平衡或低效的方式拆分的 Spliterator 操作不太可能从并行性中受益。 遍历和拆分排气元件； 每个 Spliterator 仅对单个批量计算有用。

Spliterator 还报告其结构、源和元素的一组特征（），来自 ORDERED、DISTINCT、SORTED、SIZED、NONNULL、IMMUTABLE、CONCURRENT 和 SUBSIZED。 Spliterator 客户端可以使用这些来控制、专门化或简化计算。 例如，Collection 的 Spliterator 会报告 SIZED，Set 的 Spliterator 会报告 DISTINCT，SortedSet 的 Spliterator 也会报告 SORTED。 特征被报告为一个简单的联合位集。 一些特征还限制了方法的行为； 例如，如果 ORDERED，遍历方法必须符合其记录的顺序。 未来可能会定义新的特性，因此实现者不应为未列出的值赋予含义。

不报告 IMMUTABLE 或 CONCURRENT 的 Spliterator 应该有一个文档化的策略，涉及： 当 spliterator 绑定到元素源时；结合后检测到的元素源的结构干扰检测。后期绑定 Spliterator 在第一次遍历、第一次拆分或第一次查询估计大小时绑定到元素的源，而不是在创建 Spliterator 时。非后期绑定的 Spliterator 在构造点或任何方法的第一次调用时绑定到元素的源。绑定之前对源所做的修改会在遍历 Spliterator 时反映出来。绑定 Spliterator 后，如果检测到结构干扰，应尽最大努力抛出 ConcurrentModificationException。执行此操作的拆分器称为快速失败。 Spliterator 的批量遍历方法 (forEachRemaining()) 可以优化遍历并在遍历所有元素后检查结构干扰，而不是检查每个元素并立即失败。

Spliterators 可以通过estimateSize() 方法估计剩余元素的数量。 理想情况下，正如 SIZED 特性所反映的那样，该值恰好对应于成功遍历中将遇到的元素数量。 然而，即使在不完全知道的情况下，估计值仍然可能对在源上执行的操作有用，例如帮助确定进一步拆分或顺序遍历剩余元素是否更可取。

尽管它们在并行算法中有明显的用途，但分离器并不期望是线程安全的。 相反，使用拆分器的并行算法的实现应确保拆分器一次仅由一个线程使用。 这通常很容易通过串行线程限制来实现，这通常是通过递归分解工作的典型并行算法的自然结果。 调用 trySplit() 的线程可以将返回的 Spliterator 移交给另一个线程，该线程又可以遍历或进一步拆分该 Spliterator。 如果两个或多个线程在同一个拆分器上同时操作，拆分和遍历的行为是不确定的。 如果原始线程将拆分器交给另一个线程进行处理，最好在 tryAdvance() 消耗任何元素之前进行该切换，因为某些保证（例如 SIZED 拆分器的估计大小（）的准确性）仅有效 在遍历开始之前。

为 OfInt、OfLong 和 OfDouble 值提供了 Spliterator 的原始子类型特化。 Spliterator#tryAdvance(java.util.function.Consumer) 和 Spliterator#forEachRemaining(java.util.function.Consumer) 的子类型默认实现将原始值框到其相应包装类的实例中。 这种装箱可能会破坏使用原始专业化获得的任何性能优势。 为避免装箱，应使用相应的基于基元的方法。 例如，应该优先使用 Spliterator.OfInt#tryAdvance(java.util.function.IntConsumer) 和 Spliterator.OfInt#forEachRemaining(java.util.function.IntConsumer)，而不是 Spliterator.OfInt#tryAdvance(java.util.function。 消费者）和 Spliterator.OfInt#forEachRemaining（java.util.function.Consumer）。 使用基于装箱的方法 tryAdvance() 和 forEachRemaining() 遍历原始值不会影响遇到转换为装箱值的值的顺序。

嵌套类摘要

字段摘要

方法总结

字段详细信息

CONCURRENT

static final int CONCURRENT

特征值表示元素源可以被多个线程安全地同时修改（允许添加、替换和/或删除）而无需外部同步。 如果是这样，Spliterator 应该有一个关于遍历期间修改的影响的文档化策略。

顶级 Spliterator 不应同时报告 CONCURRENT 和 SIZED，因为如果在遍历期间同时修改源，则有限大小（如果已知）可能会改变。 这样的 Spliterator 是不一致的，并且不能保证使用该 Spliterator 的任何计算。 如果子拆分大小已知并且在遍历时未反映对源的添加或删除，则子拆分器可能会报告 SIZED。

DISTINCT

static final int DISTINCT

特征值表示，对于每对遇到的元素 x, y, !x.equals(y)。 例如，这适用于基于 Set 的 Spliterator。

IMMUTABLE

static final int IMMUTABLE

表示元素源不能进行结构修改的特征值； 也就是说，元素不能被添加、替换或删除，因此在遍历过程中不会发生这种变化。 不报告 IMMUTABLE 或 CONCURRENT 的 Spliterator 应具有有关在遍历期间检测到的结构干扰的文档化策略（例如抛出 ConcurrentModificationException）。

NONNULL

static final int NONNULL

表示源保证遇到的元素不会为空的特征值。 （例如，这适用于大多数并发集合、队列和映射。）

ORDERED

static final int ORDERED

表示为元素定义相遇顺序的特征值。 如果是这样，则此 Spliterator 保证方法 trySplit() 拆分元素的严格前缀，该方法 tryAdvance(java.util.function.Consumer) 按前缀顺序逐个元素，以及该 forEachRemaining(java.util.function.Consumer) 按相遇顺序执行动作。

如果对应的 Collection#iterator 记录了订单，则 Collection 具有遇到订单。 如果是这样，遭遇顺序与记录的顺序相同。 否则，集合没有遇到顺序。

SIZED

static final int SIZED

特征值表示在遍历或拆分之前从estimateSize() 返回的值表示有限大小，在没有结构源修改的情况下，表示完整遍历将遇到的元素数量的精确计数。

SORTED

static final int SORTED

表示遇到顺序遵循定义的排序顺序的特征值。 如果是这样，则方法 getComparator() 返回关联的 Comparator，如果所有元素都是 Comparable 并且按其自然顺序排序，则返回 null。

报告 SORTED 的 Spliterator 也必须报告 ORDERED。

SUBSIZED

static final int SUBSIZED

特征值表示由 trySplit() 产生的所有拆分器都将是 SIZED 和 SUBSIZED。 （这意味着所有子拆分器，无论是直接的还是间接的，都将被调整大小。）

不按照 SUBSIZED 的要求报告 SIZED 的 Spliterator 是不一致的，并且不能保证使用该 Spliterator 的任何计算。

方法详情

tryAdvance

boolean tryAdvance(Consumer<? super T> action)

如果存在剩余元素，则对其执行给定的操作，返回 true； 否则返回假。 如果此 Spliterator 是 ORDERED，则按遇到顺序对下一个元素执行操作。 操作引发的异常将转发给调用者。

参数：

返回:

如果在进入此方法时不存在剩余元素，则为 false，否则为 true。

Throws:

forEachRemaining

default void forEachRemaining(Consumer<? super T> action)

在当前线程中按顺序对每个剩余元素执行给定的操作，直到处理完所有元素或该操作引发异常。 如果此 Spliterator 是 ORDERED，则按遇到顺序执行操作。 操作引发的异常将转发给调用者。

参数：

Throws:

trySplit

SpliteratorT trySplit()

如果此 spliterator 可以分区，则返回一个 Spliterator 覆盖元素，从该方法返回时，该 Spliterator 不会被此 Spliterator 覆盖。

如果此 Spliterator 是 ORDERED，则返回的 Spliterator 必须涵盖元素的严格前缀。

除非此 Spliterator 涵盖无限数量的元素，否则对 trySplit() 的重复调用最终必须返回 null。 在非空返回时：

• 在拆分之前为 estimateSize() 报告的值，在拆分之后，对于 this 和返回的 Spliterator，必须大于或等于 estimateSize()； 和
• 如果此 Spliterator 是 SUBSIZED，则此 spliterator 在拆分之前的estimateSize() 必须等于此 spliterator 的estimateSize() 与拆分后返回的 Spliterator 之和。

此方法可能出于任何原因返回 null，包括空虚、遍历开始后无法拆分、数据结构约束和效率考虑。

返回:

覆盖部分元素的 Spliterator，如果此 spliterator 无法拆分，则为 null

estimateSize

long estimateSize()

返回 forEachRemaining(java.util.function.Consumer) 遍历将遇到的元素数量的估计值，如果无限、未知或计算成本太高，则返回 Long#MAX_VALUE。

如果这个 Spliterator 是 SIZED 并且还没有被部分遍历或拆分，或者这个 Spliterator 是 SUBSIZED 并且还没有被部分遍历，那么这个估计必须是一个完整的遍历会遇到的元素的准确计数。 否则，这个估计可能是任意不准确的，但必须根据调用 trySplit() 的指定减少。

返回:

估计的大小，如果是无限的、未知的或计算成本太高，则为 Long.MAX_VALUE。

getExactSizeIfKnown

default long getExactSizeIfKnown()

如果此 Spliterator 为 SIZED，则返回 estimateSize() 的便捷方法，否则返回 -1。

返回:

确切的大小（如果已知），否则为 -1。

characteristics

int characteristics()

返回此 Spliterator 及其元素的一组特征。 结果表示为 ORDERED、DISTINCT、SORTED、SIZED、NONNULL、IMMUTABLE、CONCURRENT、SUBSIZED 的 ORed 值。 在给定拆分器上重复调用特性（），在调用 trySplit 之前或之间，应该总是返回相同的结果。

如果 Spliterator 报告了一组不一致的特征（从单个调用或跨多个调用返回的特征），则无法保证使用此 Spliterator 的任何计算。

返回:

特征的表示

hasCharacteristics

default boolean hasCharacteristics(int characteristics)

如果此 Spliterator 的 features() 包含所有给定的特征，则返回 true。

参数：

返回:

如果所有指定的特征都存在，则为 true，否则为 false

getComparator

default Comparator<? super T> getComparator()

如果此 Spliterator 的源由 Comparator 排序，则返回该 Comparator。 如果源在 Comparable 中已排序，则返回 null。 否则，如果源未排序，则抛出 IllegalStateException。

返回:

比较器，如果元素按自然顺序排序，则返回 null。

Throws: