鴻蒙OS Spliterator

Spliterator

public interface Spliterator<T>

用于遍歷和劃分源元素的對象。 Spliterator 覆蓋的元素來源可以是，例如，數(shù)組、集合、IO 通道或生成器函數(shù)。

Spliterator 可以單獨遍歷元素（tryAdvance()）或批量順序遍歷元素（forEachRemaining()）。

Spliterator 也可以將它的一些元素（使用 trySplit()）劃分為另一個 Spliterator，以用于可能的并行操作。 使用無法拆分或以高度不平衡或低效的方式拆分的 Spliterator 操作不太可能從并行性中受益。 遍歷和拆分排氣元件； 每個 Spliterator 僅對單個批量計算有用。

Spliterator 還報告其結(jié)構(gòu)、源和元素的一組特征（），來自 ORDERED、DISTINCT、SORTED、SIZED、NONNULL、IMMUTABLE、CONCURRENT 和 SUBSIZED。 Spliterator 客戶端可以使用這些來控制、專門化或簡化計算。 例如，Collection 的 Spliterator 會報告 SIZED，Set 的 Spliterator 會報告 DISTINCT，SortedSet 的 Spliterator 也會報告 SORTED。 特征被報告為一個簡單的聯(lián)合位集。 一些特征還限制了方法的行為； 例如，如果 ORDERED，遍歷方法必須符合其記錄的順序。 未來可能會定義新的特性，因此實現(xiàn)者不應(yīng)為未列出的值賦予含義。

不報告 IMMUTABLE 或 CONCURRENT 的 Spliterator 應(yīng)該有一個文檔化的策略，涉及： 當 spliterator 綁定到元素源時；結(jié)合后檢測到的元素源的結(jié)構(gòu)干擾檢測。后期綁定 Spliterator 在第一次遍歷、第一次拆分或第一次查詢估計大小時綁定到元素的源，而不是在創(chuàng)建 Spliterator 時。非后期綁定的 Spliterator 在構(gòu)造點或任何方法的第一次調(diào)用時綁定到元素的源。綁定之前對源所做的修改會在遍歷 Spliterator 時反映出來。綁定 Spliterator 后，如果檢測到結(jié)構(gòu)干擾，應(yīng)盡最大努力拋出 ConcurrentModificationException。執(zhí)行此操作的拆分器稱為快速失敗。 Spliterator 的批量遍歷方法 (forEachRemaining()) 可以優(yōu)化遍歷并在遍歷所有元素后檢查結(jié)構(gòu)干擾，而不是檢查每個元素并立即失敗。

Spliterators 可以通過estimateSize() 方法估計剩余元素的數(shù)量。 理想情況下，正如 SIZED 特性所反映的那樣，該值恰好對應(yīng)于成功遍歷中將遇到的元素數(shù)量。 然而，即使在不完全知道的情況下，估計值仍然可能對在源上執(zhí)行的操作有用，例如幫助確定進一步拆分或順序遍歷剩余元素是否更可取。

盡管它們在并行算法中有明顯的用途，但分離器并不期望是線程安全的。 相反，使用拆分器的并行算法的實現(xiàn)應(yīng)確保拆分器一次僅由一個線程使用。 這通常很容易通過串行線程限制來實現(xiàn)，這通常是通過遞歸分解工作的典型并行算法的自然結(jié)果。 調(diào)用 trySplit() 的線程可以將返回的 Spliterator 移交給另一個線程，該線程又可以遍歷或進一步拆分該 Spliterator。 如果兩個或多個線程在同一個拆分器上同時操作，拆分和遍歷的行為是不確定的。 如果原始線程將拆分器交給另一個線程進行處理，最好在 tryAdvance() 消耗任何元素之前進行該切換，因為某些保證（例如 SIZED 拆分器的估計大小（）的準確性）僅有效 在遍歷開始之前。

為 OfInt、OfLong 和 OfDouble 值提供了 Spliterator 的原始子類型特化。 Spliterator#tryAdvance(java.util.function.Consumer) 和 Spliterator#forEachRemaining(java.util.function.Consumer) 的子類型默認實現(xiàn)將原始值框到其相應(yīng)包裝類的實例中。 這種裝箱可能會破壞使用原始專業(yè)化獲得的任何性能優(yōu)勢。 為避免裝箱，應(yīng)使用相應(yīng)的基于基元的方法。 例如，應(yīng)該優(yōu)先使用 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() 遍歷原始值不會影響遇到轉(zhuǎn)換為裝箱值的值的順序。

嵌套類摘要

字段摘要

方法總結(jié)

字段詳細信息

CONCURRENT

static final int CONCURRENT

特征值表示元素源可以被多個線程安全地同時修改（允許添加、替換和/或刪除）而無需外部同步。 如果是這樣，Spliterator 應(yīng)該有一個關(guān)于遍歷期間修改的影響的文檔化策略。

頂級 Spliterator 不應(yīng)同時報告 CONCURRENT 和 SIZED，因為如果在遍歷期間同時修改源，則有限大小（如果已知）可能會改變。 這樣的 Spliterator 是不一致的，并且不能保證使用該 Spliterator 的任何計算。 如果子拆分大小已知并且在遍歷時未反映對源的添加或刪除，則子拆分器可能會報告 SIZED。

DISTINCT

static final int DISTINCT

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

IMMUTABLE

static final int IMMUTABLE

表示元素源不能進行結(jié)構(gòu)修改的特征值； 也就是說，元素不能被添加、替換或刪除，因此在遍歷過程中不會發(fā)生這種變化。 不報告 IMMUTABLE 或 CONCURRENT 的 Spliterator 應(yīng)具有有關(guān)在遍歷期間檢測到的結(jié)構(gòu)干擾的文檔化策略（例如拋出 ConcurrentModificationException）。

NONNULL

static final int NONNULL

表示源保證遇到的元素不會為空的特征值。 （例如，這適用于大多數(shù)并發(fā)集合、隊列和映射。）

ORDERED

static final int ORDERED

表示為元素定義相遇順序的特征值。 如果是這樣，則此 Spliterator 保證方法 trySplit() 拆分元素的嚴格前綴，該方法 tryAdvance(java.util.function.Consumer) 按前綴順序逐個元素，以及該 forEachRemaining(java.util.function.Consumer) 按相遇順序執(zhí)行動作。

如果對應(yīng)的 Collection#iterator 記錄了訂單，則 Collection 具有遇到訂單。 如果是這樣，遭遇順序與記錄的順序相同。 否則，集合沒有遇到順序。

SIZED

static final int SIZED

特征值表示在遍歷或拆分之前從estimateSize() 返回的值表示有限大小，在沒有結(jié)構(gòu)源修改的情況下，表示完整遍歷將遇到的元素數(shù)量的精確計數(shù)。

SORTED

static final int SORTED

表示遇到順序遵循定義的排序順序的特征值。 如果是這樣，則方法 getComparator() 返回關(guān)聯(lián)的 Comparator，如果所有元素都是 Comparable 并且按其自然順序排序，則返回 null。

報告 SORTED 的 Spliterator 也必須報告 ORDERED。

SUBSIZED

static final int SUBSIZED

特征值表示由 trySplit() 產(chǎn)生的所有拆分器都將是 SIZED 和 SUBSIZED。 （這意味著所有子拆分器，無論是直接的還是間接的，都將被調(diào)整大小。）

不按照 SUBSIZED 的要求報告 SIZED 的 Spliterator 是不一致的，并且不能保證使用該 Spliterator 的任何計算。

方法詳情

tryAdvance

boolean tryAdvance(Consumer<? super T> action)

如果存在剩余元素，則對其執(zhí)行給定的操作，返回 true； 否則返回假。 如果此 Spliterator 是 ORDERED，則按遇到順序?qū)ο乱粋€元素執(zhí)行操作。 操作引發(fā)的異常將轉(zhuǎn)發(fā)給調(diào)用者。

參數(shù)：

返回:

如果在進入此方法時不存在剩余元素，則為 false，否則為 true。

Throws:

forEachRemaining

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

在當前線程中按順序?qū)γ總€剩余元素執(zhí)行給定的操作，直到處理完所有元素或該操作引發(fā)異常。 如果此 Spliterator 是 ORDERED，則按遇到順序執(zhí)行操作。 操作引發(fā)的異常將轉(zhuǎn)發(fā)給調(diào)用者。

參數(shù)：

Throws:

trySplit

SpliteratorT trySplit()

如果此 spliterator 可以分區(qū)，則返回一個 Spliterator 覆蓋元素，從該方法返回時，該 Spliterator 不會被此 Spliterator 覆蓋。

如果此 Spliterator 是 ORDERED，則返回的 Spliterator 必須涵蓋元素的嚴格前綴。

除非此 Spliterator 涵蓋無限數(shù)量的元素，否則對 trySplit() 的重復(fù)調(diào)用最終必須返回 null。 在非空返回時：

• 在拆分之前為 estimateSize() 報告的值，在拆分之后，對于 this 和返回的 Spliterator，必須大于或等于 estimateSize()； 和
• 如果此 Spliterator 是 SUBSIZED，則此 spliterator 在拆分之前的estimateSize() 必須等于此 spliterator 的estimateSize() 與拆分后返回的 Spliterator 之和。

此方法可能出于任何原因返回 null，包括空虛、遍歷開始后無法拆分、數(shù)據(jù)結(jié)構(gòu)約束和效率考慮。

返回:

覆蓋部分元素的 Spliterator，如果此 spliterator 無法拆分，則為 null

estimateSize

long estimateSize()

返回 forEachRemaining(java.util.function.Consumer) 遍歷將遇到的元素數(shù)量的估計值，如果無限、未知或計算成本太高，則返回 Long#MAX_VALUE。

如果這個 Spliterator 是 SIZED 并且還沒有被部分遍歷或拆分，或者這個 Spliterator 是 SUBSIZED 并且還沒有被部分遍歷，那么這個估計必須是一個完整的遍歷會遇到的元素的準確計數(shù)。 否則，這個估計可能是任意不準確的，但必須根據(jù)調(diào)用 trySplit() 的指定減少。

返回:

估計的大小，如果是無限的、未知的或計算成本太高，則為 Long.MAX_VALUE。

getExactSizeIfKnown

default long getExactSizeIfKnown()

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

返回:

確切的大?。ㄈ绻阎駝t為 -1。

characteristics

int characteristics()

返回此 Spliterator 及其元素的一組特征。 結(jié)果表示為 ORDERED、DISTINCT、SORTED、SIZED、NONNULL、IMMUTABLE、CONCURRENT、SUBSIZED 的 ORed 值。 在給定拆分器上重復(fù)調(diào)用特性（），在調(diào)用 trySplit 之前或之間，應(yīng)該總是返回相同的結(jié)果。

如果 Spliterator 報告了一組不一致的特征（從單個調(diào)用或跨多個調(diào)用返回的特征），則無法保證使用此 Spliterator 的任何計算。

返回:

特征的表示

hasCharacteristics

default boolean hasCharacteristics(int characteristics)

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

參數(shù)：

返回:

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

getComparator

default Comparator<? super T> getComparator()

如果此 Spliterator 的源由 Comparator 排序，則返回該 Comparator。 如果源在 Comparable 中已排序，則返回 null。 否則，如果源未排序，則拋出 IllegalStateException。

返回:

比較器，如果元素按自然順序排序，則返回 null。

Throws: