Java : Spliterator with Examples

final var list = List.of("aaa", "bbb", "ccc");
System.out.println(list); // [aaa, bbb, ccc]
System.out.println(list.size()); // 3

final var spliterator = list.spliterator();

System.out.println("-- forEachRemaining --");
spliterator.forEachRemaining(s -> {
    System.out.println(s);
});

// Result
// ↓
//-- forEachRemaining --
//aaa
//bbb
//ccc

final var list = List.of("a", "b", "c", "d", "e");
System.out.println(list); // [a, b, c, d, e]
System.out.println(list.size()); // 5

final var s1 = list.spliterator();
System.out.println("s1 size : " + s1.estimateSize()); // s1 size : 5

final var s2 = s1.trySplit();
System.out.println("s1 size : " + s1.estimateSize()); // s1 size : 3
System.out.println("s2 size : " + s2.estimateSize()); // s2 size : 2

System.out.println("-- s1 --");
s1.forEachRemaining(System.out::println);

// Result
// ↓
//-- s1 --
//c
//d
//e

System.out.println("-- s2 --");
s2.forEachRemaining(System.out::println);

// Result
// ↓
//-- s2 --
//a
//b

static final 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.

final var queue = new ConcurrentLinkedQueue<String>();
queue.add("a");
queue.add("b");

final var spliterator = queue.spliterator();

System.out.printf("0x%x%n", spliterator.characteristics()); // 0x1110

System.out.printf("CONCURRENT : 0x%x%n", Spliterator.CONCURRENT); // CONCURRENT : 0x1000
System.out.printf("NONNULL : 0x%x%n", Spliterator.NONNULL); // NONNULL : 0x100
System.out.printf("ORDERED : 0x%x%n", Spliterator.ORDERED); // ORDERED : 0x10

static final int DISTINCT

Characteristic value signifying that, for each pair of encountered elements x, y, !x.equals(y).

final var set = new HashSet<String>();
set.add("a");
set.add("b");

final var spliterator = set.spliterator();

System.out.printf("0x%x%n", spliterator.characteristics()); // 0x41

System.out.printf("SIZED : 0x%x%n", Spliterator.SIZED); // SIZED : 0x40
System.out.printf("DISTINCT : 0x%x%n", Spliterator.DISTINCT); // DISTINCT : 0x1

static final 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.

final var list = new CopyOnWriteArrayList<String>();
list.add("a");
list.add("b");

final var spliterator = list.spliterator();

System.out.printf("0x%x%n", spliterator.characteristics()); // 0x4450

System.out.printf("SUBSIZED : 0x%x%n", Spliterator.SUBSIZED); // SUBSIZED : 0x4000
System.out.printf("IMMUTABLE : 0x%x%n", Spliterator.IMMUTABLE); // IMMUTABLE : 0x400
System.out.printf("SIZED : 0x%x%n", Spliterator.SIZED); // SIZED : 0x40
System.out.printf("ORDERED : 0x%x%n", Spliterator.ORDERED); // ORDERED : 0x10

static final int NONNULL

Characteristic value signifying that the source guarantees that encountered elements will not be null.

final var deque = new ArrayDeque<String>();
deque.add("a");
deque.add("b");
//deque.add(null); // NullPointerException

final var spliterator = deque.spliterator();

System.out.printf("0x%x%n", spliterator.characteristics()); // 0x4150

System.out.printf("SUBSIZED : 0x%x%n", Spliterator.SUBSIZED); // SUBSIZED : 0x4000
System.out.printf("NONNULL : 0x%x%n", Spliterator.NONNULL); // NONNULL : 0x100
System.out.printf("SIZED : 0x%x%n", Spliterator.SIZED); // SIZED : 0x40
System.out.printf("ORDERED : 0x%x%n", Spliterator.ORDERED); // ORDERED : 0x10

static final int ORDERED

Characteristic value signifying that an encounter order is defined for elements.

final var list = new ArrayList<String>();
list.add("a");
list.add("b");

final var spliterator = list.spliterator();

System.out.printf("0x%x%n", spliterator.characteristics()); // 0x4050

System.out.printf("SUBSIZED : 0x%x%n", Spliterator.SUBSIZED); // SUBSIZED : 0x4000
System.out.printf("SIZED : 0x%x%n", Spliterator.SIZED); // SIZED : 0x40
System.out.printf("ORDERED : 0x%x%n", Spliterator.ORDERED); // ORDERED : 0x10

static final 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.

final var list = new ArrayList<String>();
list.add("a");
list.add("b");

final var spliterator = list.spliterator();

System.out.printf("0x%x%n", spliterator.characteristics()); // 0x4050

System.out.printf("SUBSIZED : 0x%x%n", Spliterator.SUBSIZED); // SUBSIZED : 0x4000
System.out.printf("SIZED : 0x%x%n", Spliterator.SIZED); // SIZED : 0x40
System.out.printf("ORDERED : 0x%x%n", Spliterator.ORDERED); // ORDERED : 0x10

static final int SORTED

Characteristic value signifying that encounter order follows a defined sort order.

final var set = new TreeSet<String>();
set.add("a");
set.add("b");

final var spliterator = set.spliterator();

System.out.printf("0x%x%n", spliterator.characteristics()); // 0x55

System.out.printf("SIZED : 0x%x%n", Spliterator.SIZED); // SIZED : 0x40
System.out.printf("ORDERED : 0x%x%n", Spliterator.ORDERED); // ORDERED : 0x10
System.out.printf("SORTED : 0x%x%n", Spliterator.SORTED); // SORTED : 0x4
System.out.printf("DISTINCT : 0x%x%n", Spliterator.DISTINCT); // DISTINCT : 0x1

static final int SUBSIZED

Characteristic value signifying that all Spliterators resulting from trySplit() will be both SIZED and SUBSIZED.

final var list = new ArrayList<String>();
list.add("a");
list.add("b");

final var spliterator = list.spliterator();

System.out.printf("0x%x%n", spliterator.characteristics()); // 0x4050

System.out.printf("SUBSIZED : 0x%x%n", Spliterator.SUBSIZED); // SUBSIZED : 0x4000
System.out.printf("SIZED : 0x%x%n", Spliterator.SIZED); // SIZED : 0x40
System.out.printf("ORDERED : 0x%x%n", Spliterator.ORDERED); // ORDERED : 0x10

int characteristics ()

Returns a set of characteristics of this Spliterator and its elements.

Please see : ORDERED , SIZED

long estimateSize ()

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

final var list = List.of("a", "b", "c", "d", "e");
System.out.println(list); // [a, b, c, d, e]
System.out.println(list.size()); // 5

final var spliterator = list.spliterator();
System.out.println(spliterator.estimateSize()); // 5
System.out.println(spliterator.getExactSizeIfKnown()); // 5

final var queue = new ConcurrentLinkedQueue<String>();
queue.add("a");
queue.add("b");
queue.add("c");

System.out.println(queue); // [a, b, c]
System.out.println(queue.size()); // 3

final var spliterator = queue.spliterator();
System.out.println(spliterator.estimateSize() == Long.MAX_VALUE); // true
System.out.println(spliterator.getExactSizeIfKnown()); // -1

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

final var list = List.of("aaa", "bbb", "ccc");
System.out.println(list); // [aaa, bbb, ccc]
System.out.println(list.size()); // 3

final var spliterator = list.spliterator();

System.out.println("-- forEachRemaining --");
spliterator.forEachRemaining(s -> {
    System.out.println(s);
});

// Result
// ↓
//-- forEachRemaining --
//aaa
//bbb
//ccc

default Comparator<? super T> getComparator ()

If this Spliterator's source is SORTED by a Comparator, returns that Comparator.

final var set = new TreeSet<String>();
set.add("c");
set.add("d");
set.add("a");
set.add("b");

System.out.println(set); // [a, b, c, d]

final var spliterator = set.spliterator();
final var comparator = spliterator.getComparator();

System.out.println(comparator); // null

final Comparator<String> reverse = Comparator.reverseOrder();

final var set = new TreeSet<>(reverse);
set.add("c");
set.add("d");
set.add("a");
set.add("b");

System.out.println(set); // [d, c, b, a]

final var spliterator = set.spliterator();
final var comparator = spliterator.getComparator();
System.out.println(comparator == reverse); // true

final var list = List.of("a", "b", "c");
System.out.println(list); // [a, b, c]

final var spliterator = list.spliterator();

try {
    final var comparator = spliterator.getComparator();
} catch (IllegalStateException e) {
    System.out.println("IllegalStateException!");
}

// Result
// ↓
//IllegalStateException!

default long getExactSizeIfKnown ()

Convenience method that returns estimateSize() if this Spliterator is SIZED, else -1.

Please see : estimateSize()

default boolean hasCharacteristics (int characteristics)

Returns true if this Spliterator's characteristics() contain all of the given characteristics.

final var set = new HashSet<String>();
set.add("a");
set.add("b");

final var spliterator = set.spliterator();

System.out.printf("0x%x%n", spliterator.characteristics()); // 0x41

System.out.printf("SIZED : 0x%x%n", Spliterator.SIZED); // SIZED : 0x40
System.out.printf("DISTINCT : 0x%x%n", Spliterator.DISTINCT); // DISTINCT : 0x1

System.out.println(spliterator.hasCharacteristics(Spliterator.SIZED)); // true
System.out.println(spliterator.hasCharacteristics(Spliterator.DISTINCT)); // true
System.out.println(spliterator.hasCharacteristics(Spliterator.ORDERED)); // false

boolean tryAdvance (Consumer<? super T> action)

If a remaining element exists, performs the given action on it, returning true; else returns false.

final var list = List.of("aaa", "bbb", "ccc");
final var spliterator = list.spliterator();

System.out.println("-- tryAdvance --");
final var ret1 = spliterator.tryAdvance(System.out::println);
System.out.println("ret : " + ret1);

System.out.println("-- tryAdvance --");
final var ret2 = spliterator.tryAdvance(System.out::println);
System.out.println("ret : " + ret2);

System.out.println("-- tryAdvance --");
final var ret3 = spliterator.tryAdvance(System.out::println);
System.out.println("ret : " + ret3);

System.out.println("-- tryAdvance --");
final var ret4 = spliterator.tryAdvance(System.out::println);
System.out.println("ret : " + ret4);

// Result
// ↓
//-- tryAdvance --
//aaa
//ret : true
//-- tryAdvance --
//bbb
//ret : true
//-- tryAdvance --
//ccc
//ret : true
//-- tryAdvance --
//ret : false

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.

final var list = List.of("a", "b", "c", "d", "e");
System.out.println(list); // [a, b, c, d, e]
System.out.println(list.size()); // 5

final var s1 = list.spliterator();
System.out.println("s1 size : " + s1.estimateSize()); // s1 size : 5

final var s2 = s1.trySplit();
System.out.println("s1 size : " + s1.estimateSize()); // s1 size : 3
System.out.println("s2 size : " + s2.estimateSize()); // s2 size : 2

System.out.println("-- s1 --");
s1.forEachRemaining(System.out::println);

// Result
// ↓
//-- s1 --
//c
//d
//e

System.out.println("-- s2 --");
s2.forEachRemaining(System.out::println);

// Result
// ↓
//-- s2 --
//a
//b