Spliterators.AbstractIntSpliterator

AI-generated Key Takeaways

• Spliterators.AbstractIntSpliterator is an abstract class implementing Spliterator.OfInt and enabling parallel processing through trySplit.

• Extending classes only need to implement tryAdvance, and optionally override forEachRemaining for performance optimization.

• It provides a base implementation for splitting an int stream, requiring subclasses to handle element iteration.

• trySplit method supports limited parallelism, enabling potentially faster processing of elements.

• AbstractIntSpliterator reports size and characteristics for the spliterator, guiding stream operations.

public static abstract class Spliterators.AbstractIntSpliterator extends Object
implements Spliterator.OfInt

An abstract Spliterator.OfInt that implements trySplit to permit limited parallelism.

To implement a spliterator an extending class need only implement Spliterator.OfInt.tryAdvance(java.util.function.IntConsumer) tryAdvance}. The extending class should override Spliterator.OfInt.forEachRemaining(java.util.function.IntConsumer) forEach} if it can provide a more performant implementation.

See Also

• Spliterators.spliterator(java.util.PrimitiveIterator.OfInt, long, int)

Inherited Constant Summary

From interface java.util.Spliterator

int	CONCURRENT	Characteristic value signifying that the element source may be safely concurrently modified (allowing additions, replacements, and/or removals) by multiple threads without external synchronization.
int	DISTINCT	Characteristic value signifying that, for each pair of encountered elements x, y, !x.equals(y).
int	IMMUTABLE	Characteristic value signifying that the element source cannot be structurally modified; that is, elements cannot be added, replaced, or removed, so such changes cannot occur during traversal.
int	NONNULL	Characteristic value signifying that the source guarantees that encountered elements will not be null.
int	ORDERED	Characteristic value signifying that an encounter order is defined for elements.
int	SIZED	Characteristic value signifying that the value returned from estimateSize() prior to traversal or splitting represents a finite size that, in the absence of structural source modification, represents an exact count of the number of elements that would be encountered by a complete traversal.
int	SORTED	Characteristic value signifying that encounter order follows a defined sort order.
int	SUBSIZED	Characteristic value signifying that all Spliterators resulting from trySplit() will be both SIZED and SUBSIZED.

Protected Constructor Summary

AbstractIntSpliterator(long est, int additionalCharacteristics) Creates a spliterator reporting the given estimated size and characteristics.

Public Method Summary

int	characteristics() Returns a set of characteristics of this Spliterator and its elements.
long	estimateSize() Returns an estimate of the number of elements that would be encountered by a forEachRemaining(Consumer) traversal, or returns Long.MAX_VALUE if infinite, unknown, or too expensive to compute.
Spliterator.OfInt	trySplit() If this spliterator can be partitioned, returns a Spliterator covering elements, that will, upon return from this method, not be covered by this Spliterator. This implementation permits limited parallelism.

Inherited Method Summary

From class java.lang.Object

Object	clone() Creates and returns a copy of this Object.
boolean	equals(Object obj) Compares this instance with the specified object and indicates if they are equal.
void	finalize() Invoked when the garbage collector has detected that this instance is no longer reachable.
final Class<?>	getClass() Returns the unique instance of Class that represents this object's class.
int	hashCode() Returns an integer hash code for this object.
final void	notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up.
final void	notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up.
String	toString() Returns a string containing a concise, human-readable description of this object.
final void	wait(long timeout, int nanos) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.
final void	wait(long timeout) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.
final void	wait() Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object.

From interface java.util.Spliterator.OfInt

void	forEachRemaining(Consumer<? super Integer> action)
void	forEachRemaining(IntConsumer action)
boolean	tryAdvance(Consumer<? super Integer> action)
abstract boolean	tryAdvance(IntConsumer action)
abstract Spliterator.OfInt	trySplit() If this spliterator can be partitioned, returns a Spliterator covering elements, that will, upon return from this method, not be covered by this Spliterator.

From interface java.util.Spliterator.OfPrimitive

void	forEachRemaining(IntConsumer action) Performs the given action for each remaining element, sequentially in the current thread, until all elements have been processed or the action throws an exception.
abstract boolean	tryAdvance(IntConsumer action) If a remaining element exists, performs the given action on it, returning true; else returns false.
abstract T_SPLITR	trySplit() If this spliterator can be partitioned, returns a Spliterator covering elements, that will, upon return from this method, not be covered by this Spliterator.

From interface java.util.Spliterator

abstract int	characteristics() Returns a set of characteristics of this Spliterator and its elements.
abstract long	estimateSize() Returns an estimate of the number of elements that would be encountered by a forEachRemaining(Consumer) traversal, or returns Long.MAX_VALUE if infinite, unknown, or too expensive to compute.
void	forEachRemaining(Consumer<? super T> action) Performs the given action for each remaining element, sequentially in the current thread, until all elements have been processed or the action throws an exception.
Comparator<? super T>	getComparator() If this Spliterator's source is SORTED by a Comparator, returns that Comparator.
long	getExactSizeIfKnown() Convenience method that returns estimateSize() if this Spliterator is SIZED, else -1.
boolean	hasCharacteristics(int characteristics) Returns true if this Spliterator's characteristics() contain all of the given characteristics.
abstract boolean	tryAdvance(Consumer<? super T> action) If a remaining element exists, performs the given action on it, returning true; else returns false.
abstract Spliterator<Integer>	trySplit() If this spliterator can be partitioned, returns a Spliterator covering elements, that will, upon return from this method, not be covered by this Spliterator.

Protected Constructors

protected AbstractIntSpliterator (long est, int additionalCharacteristics)

Creates a spliterator reporting the given estimated size and characteristics.

Parameters

est	the estimated size of this spliterator if known, otherwise Long.MAX_VALUE.
additionalCharacteristics	properties of this spliterator's source or elements. If SIZED is reported then this spliterator will additionally report SUBSIZED.

Public Methods

public int characteristics ()

Returns a set of characteristics of this Spliterator and its elements. The result is represented as ORed values from ORDERED, DISTINCT, SORTED, SIZED, NONNULL, IMMUTABLE, CONCURRENT, SUBSIZED. Repeated calls to characteristics() on a given spliterator, prior to or in-between calls to trySplit, should always return the same result.

If a Spliterator reports an inconsistent set of characteristics (either those returned from a single invocation or across multiple invocations), no guarantees can be made about any computation using this Spliterator.

Returns

• a representation of characteristics

public long estimateSize ()

Returns an estimate of the number of elements that would be encountered by a forEachRemaining(Consumer) traversal, or returns Long.MAX_VALUE if infinite, unknown, or too expensive to compute.

If this Spliterator is SIZED and has not yet been partially traversed or split, or this Spliterator is SUBSIZED and has not yet been partially traversed, this estimate must be an accurate count of elements that would be encountered by a complete traversal. Otherwise, this estimate may be arbitrarily inaccurate, but must decrease as specified across invocations of trySplit().

Returns

• the estimated size, or Long.MAX_VALUE if infinite, unknown, or too expensive to compute.

public Spliterator.OfInt trySplit ()

If this spliterator can be partitioned, returns a Spliterator covering elements, that will, upon return from this method, not be covered by this Spliterator.

If this Spliterator is ORDERED, the returned Spliterator must cover a strict prefix of the elements.

Unless this Spliterator covers an infinite number of elements, repeated calls to trySplit() must eventually return null. Upon non-null return:

• the value reported for estimateSize() before splitting, must, after splitting, be greater than or equal to estimateSize() for this and the returned Spliterator; and
• if this Spliterator is SUBSIZED, then estimateSize() for this spliterator before splitting must be equal to the sum of estimateSize() for this and the returned Spliterator after splitting.

This method may return null for any reason, including emptiness, inability to split after traversal has commenced, data structure constraints, and efficiency considerations. This implementation permits limited parallelism.

Returns

• a Spliterator covering some portion of the elements, or null if this spliterator cannot be split