鴻蒙OS Spliterator

Spliterator

public interface Spliterator<T>

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

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

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

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

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

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

盡管它們?cè)诓⑿兴惴ㄖ杏忻黠@的用途，但分離器并不期望是線程安全的。 相反，使用拆分器的并行算法的實(shí)現(xiàn)應(yīng)確保拆分器一次僅由一個(gè)線程使用。 這通常很容易通過串行線程限制來實(shí)現(xiàn)，這通常是通過遞歸分解工作的典型并行算法的自然結(jié)果。 調(diào)用 trySplit() 的線程可以將返回的 Spliterator 移交給另一個(gè)線程，該線程又可以遍歷或進(jìn)一步拆分該 Spliterator。 如果兩個(gè)或多個(gè)線程在同一個(gè)拆分器上同時(shí)操作，拆分和遍歷的行為是不確定的。 如果原始線程將拆分器交給另一個(gè)線程進(jìn)行處理，最好在 tryAdvance() 消耗任何元素之前進(jìn)行該切換，因?yàn)槟承┍ＷC（例如 SIZED 拆分器的估計(jì)大?。ǎ┑臏?zhǔn)確性）僅有效 在遍歷開始之前。

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

嵌套類摘要

字段摘要

方法總結(jié)

字段詳細(xì)信息

CONCURRENT

static final int CONCURRENT

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

頂級(jí) Spliterator 不應(yīng)同時(shí)報(bào)告 CONCURRENT 和 SIZED，因?yàn)槿绻诒闅v期間同時(shí)修改源，則有限大?。ㄈ绻阎┛赡軙?huì)改變。 這樣的 Spliterator 是不一致的，并且不能保證使用該 Spliterator 的任何計(jì)算。 如果子拆分大小已知并且在遍歷時(shí)未反映對(duì)源的添加或刪除，則子拆分器可能會(huì)報(bào)告 SIZED。

DISTINCT

static final int DISTINCT

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

IMMUTABLE

static final int IMMUTABLE

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

NONNULL

static final int NONNULL

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

ORDERED

static final int ORDERED

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

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

SIZED

static final int SIZED

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

SORTED

static final int SORTED

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

報(bào)告 SORTED 的 Spliterator 也必須報(bào)告 ORDERED。

SUBSIZED

static final int SUBSIZED

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

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

方法詳情

tryAdvance

boolean tryAdvance(Consumer<? super T> action)

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

參數(shù)：

返回:

如果在進(jìn)入此方法時(shí)不存在剩余元素，則為 false，否則為 true。

Throws:

forEachRemaining

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

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

參數(shù)：

Throws:

trySplit

SpliteratorT trySplit()

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

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

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

• 在拆分之前為 estimateSize() 報(bào)告的值，在拆分之后，對(duì)于 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) 遍歷將遇到的元素?cái)?shù)量的估計(jì)值，如果無限、未知或計(jì)算成本太高，則返回 Long#MAX_VALUE。

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

返回:

估計(jì)的大小，如果是無限的、未知的或計(jì)算成本太高，則為 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 報(bào)告了一組不一致的特征（從單個(gè)調(diào)用或跨多個(gè)調(diào)用返回的特征），則無法保證使用此 Spliterator 的任何計(jì)算。

返回:

特征的表示

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: