Module java.base
Package java.util

# Class Spliterators.AbstractSpliterator<T>

java.lang.Object
java.util.Spliterators.AbstractSpliterator<T>

All Implemented Interfaces:
  `Spliterator<T>`

Enclosing class:
  Spliterators

public abstract static class Spliterators.AbstractSpliterator<T> extends Object implements Spliterator<T>
An abstract `Spliterator` that implements `trySplit` to permit limited parallelism.

An extending class need only implement `tryAdvance`. The extending class should override `forEachRemaining` if it can provide a more performant implementation.

API Note:
  This class is a useful aid for creating a spliterator when it is not possible or difficult to efficiently partition elements in a manner allowing balanced parallel computation.

  An alternative to using this class, that also permits limited parallelism, is to create a spliterator from an iterator (see `Spliterators.spliterator(Iterator, long, int)`. Depending on the circumstances using an iterator may be easier or more convenient than extending this class, such as when there is already an iterator available to use.

Since:
  1.8
See Also:
  - `Spliterators.spliterator(Iterator, long, int)`

## Nested Class Summary

## Nested classes/interfaces declared in interface java.util.Spliterator

`Spliterator.OfDouble, Spliterator.OfInt, Spliterator.OfLong, Spliterator.OfPrimitive<T,T_CONS,T_SPLITR extends Spliterator.OfPrimitive<T,T_CONS,T_SPLITR>>`

## Field Summary

### Fields declared in interface java.util.Spliterator

`CONCURRENT, DISTINCT, IMMUTABLE, NONNULL, ORDERED, SIZED, SORTED, SUBSIZED`

## Constructor Summary

Constructors
Modifier
Constructor
Description
`protected`
`AbstractSpliterator(long est, int additionalCharacteristics)`
Creates a spliterator reporting the given estimated size and additionalCharacteristics.

## Method Summary

Modifier and Type
Method
Description
`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 `Spliterator.forEachRemaining(java.util.function.Consumer<? super T>)` traversal, or returns `Long.MAX_VALUE` if infinite, unknown, or too expensive to compute.
`Spliterator<T>`
`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.

### Methods declared in class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Methods declared in interface java.util.Spliterator

`forEachRemaining, getComparator, getExactSizeIfKnown, hasCharacteristics, tryAdvance`

## Constructor Details

### AbstractSpliterator

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

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`.

## Method Details

### trySplit

public Spliterator<T> 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 `Spliterator.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.

Specified by:
  `trySplit` in interface `Spliterator<T>`
Returns:
  a `Spliterator` covering some portion of the elements, or `null` if this spliterator cannot be split

### estimateSize

public long estimateSize()
Returns an estimate of the number of elements that would be encountered by a `Spliterator.forEachRemaining(java.util.function.Consumer<? super T>)` traversal, or returns `Long.MAX_VALUE` if infinite, unknown, or too expensive to compute.

If this Spliterator is `Spliterator.SIZED` and has not yet been partially traversed or split, or this Spliterator is `Spliterator.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 `Spliterator.trySplit()`.

Specified by:
  `estimateSize` in interface `Spliterator<T>`
Implementation Requirements:
  This implementation returns the estimated size as reported when created and, if the estimate size is known, decreases in size when split.
Returns:
  the estimated size, or `Long.MAX_VALUE` if infinite, unknown, or too expensive to compute.

### characteristics

public int characteristics()
Returns a set of characteristics of this Spliterator and its elements. The result is represented as ORed values from `Spliterator.ORDERED`, `Spliterator.DISTINCT`, `Spliterator.SORTED`, `Spliterator.SIZED`, `Spliterator.NONNULL`, `Spliterator.IMMUTABLE`, `Spliterator.CONCURRENT`, `Spliterator.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.

Specified by:
  `characteristics` in interface `Spliterator<T>`
Implementation Requirements:
  This implementation returns the characteristics as reported when created.
Returns:
  a representation of characteristics