Spliterator in java 8

It is similar to the other iterators available in Java to traverse the elements of the source(Collection, Generator function or IO channel). Spliterator is a base utility for Streams, especially parallel ones.

In order to use Spliterator for collections, we create an object of Spliterator by calling the spliterator() method available in the Collection interface.

The Spliterator interface provides the following eight methods:

1. characteristics()

it is one of the most import method which is used to get the set of characteristics of this Spliterator and its elements. The returned result is from the following:

ORDERED(0x00000010)
SIZED(0x00000040)
SUBSIZED(0x00004000)
IMMUTABLE(0x00000400)
DISTINCT(0x00000001)
SORTED(0x00000004)
NONNULL(0x00000100)
CONCURRENT(0x00001000)

The syntax of characteristics() method is as follows:

The characteristics() method accepts no parameter and returns the characteristics of the invoking spliterator that are encoded into an integer value.

2. estimateSize()

The estimateSize() method is used to get the estimate of the number of elements that are left to iterate. It returns Long.MAX_VALUE if the source is infinite, unknown or too expensive to compute.

The syntax of the estimateSize() method is as follows:

The estimateSize() method accepts no parameter and returns the estimate of the number of elements that are left to iterate.

3. getExactSizeIfKnown()

It is similar to the estimateSize() method. The only difference is that the getExactSizeIfKnown() method returns -1 if the source is infinite, unknown or too expensive to compute.

The syntax of the getExactSizeIfKnown() method is as follows:

The method accepts no parameter and returns the number of elements that are left to iterate.

4. getComparator()

it is used to sort the Spliterator's source. The sorting is done by a Comparator and returns that comparator as a result.

The syntax of the getComparator() method is as follows:

The getComparator() method accepts no parameter and returns the following values and exceptions:

It returns the comparator by which sorting of the spliterator's source is done.
The method returns null in the case when the source is sorted in the natural order.
The method throws IllegalStateException when the source is not sorted.

5. hasCharacteristics()

The hasCharacteristics() method is used to identify whether the Spilitirator's characteristics include all the given characteristics or not.

The syntax of the hasCharacteristics() method is as follows:

The hasCharacteristics() method accepts characteristics as a parameter and returns true or false when the given characteristics are present in the spliterator.

6. tryAdvance(Consumer <?super T> action)

The tryAdvance() method is used to perform the given action on the remaining elements and returns true. If elements are not present, it returns false.

The given action will be performed on the next element in encounter order when the Spliterator is ordered.

The syntax of tryAdvance() method is as follows:

The tryAdvance() method accepts action as a parameter. It returns true if there is a next element and false when elements remain.

It can also throw NullPointerException When the specified action is null.

7. forEachRemaining(Consumer<?super T> action)

The forEachRemaining() method is used to perform the given action on each element sequentially in the current thread. It performs action until the action throws NullPointerException or all the elements have been processed.

Actions are performed in encounter order when the spliterator is ordered.

The forEachRemaining() method has the following syntax:

The forEachRemaining() method accepts action as a parameter and returns void.

The forEachRemaining() method also throws NullPointerException when the specified action is null.

8. Spliterator <T> trySplit()

The trySplit() method spit the spliterator only if possible and return a reference to a new spliterator for the partition. It returns null when splitting is not possible of the spliterator.

If the splitting process is done successfully, the original spliterator iterates over one portion of the sequence and the returned spliterator iterates over the other portion.

The syntax of the trySplit() method is as follows:

The trySplit() method accepts no parameter and returns a Spliterator covering some portion of the elements or null when the spliterator cannot be split.

Let's takes some example to understand the working of all the above discussed methods.

SpliteratorExample1.java

// import required classes and package if any 
import java.util.ArrayList; 
import java.util.Scanner; 
import java.util.Spliterator; 
import java.util.stream.Stream; 
 
// SpliteratorExample1 class to understand all the methods of the Spliterator class 
public class SpliteratorExample1 { 
    // main() method start 
    public static void main(String[] args) { 
        int size; 
        
        // create a Scanner class object to take input from the user 
        Scanner sc = new Scanner(System.in); 
        
        // Create an array list for doubles. 
        ArrayList<Integer> ages; 
        
        System.out.println("Enter size of the ArrayList:"); 
        size = sc.nextInt(); 
        
        ages = new ArrayList<Integer>(size); 
        
        for(int i = 0; i < size; i++) { 
            System.out.println("Enter "+(i+1)+" Age:"); 
            int data = sc.nextInt(); 
            ages.add(data); 
        } 
        
        // close Scanner class object 
        sc.close(); 
        
        // use the stream() method to obtain a Stream to the array list. 
        Stream<Integer> stream1 = ages.stream(); 
        
        // use spliterator() method to get the Spliterator object on ages 
        Spliterator<Integer> spliterator1 = stream1.spliterator(); 
        
        // use estimateSize() method to get estimate size 
        System.out.println("The estimate size of the ArrayList is : " + spliterator1.estimateSize()); 
        
        // use getExactSizeIfKnown() method to get the exact size of ArrayList if known 
        System.out.println("The exact size of the ArrayList is: " + spliterator1.getExactSizeIfKnown()); 
        
        // use hasCharacteristics() and characteristics() methods 
        System.out.println(spliterator1.hasCharacteristics(spliterator1.characteristics())); 
        
        System.out.println("Elements of the ArrayList:"); 
        
        // use forEachRemaining() method to print each element of the ArrayList	 
        spliterator1.forEachRemaining((n) -> System.out.println(n)); 
        
        // again use stream() to obtain another Stream to the ArrayList. 
        Stream<Integer> stream2 = ages.stream(); 
        spliterator1 = stream2.spliterator(); 
        
        // use trySplit() method 
        Spliterator<Integer> spliterator2 = spliterator1.trySplit(); 
        
        // If spliterator1 could be split, use spliterator2 first. 
        if(spliterator2 != null) { 
            System.out.println("Element of the ArrayList obtain from spliterator2: "); 
            spliterator2.forEachRemaining((n) -> System.out.println(n)); 
        } 
        
        // Now, use the spliterator1 
        System.out.println("\nElement of the ArrayList obtain from spliterator1"); 
        spliterator1.forEachRemaining((n) -> System.out.println(n)); 
        
    } 
}

Output:

SpliteratorExample2.java

/// import required classes and package if any 
 import java.util.ArrayList; 
import java.util.Scanner; 
import java.util.Spliterator; 
 
// SpliteratorExample2 class to understand how to use Spliterator with Collections 
public class SpliteratorExample2 
{ 
    // main() method start 
    public static void main(String[] args) 
    { 
        int size; 
        
        // create a Scanner class object to take input from the user 
        Scanner sc = new Scanner(System.in); 
        
        
        // Create an array list for ages. 
        ArrayList<Integer> ages; 
        
        System.out.println("Enter size of the ArrayList:"); 
        size = sc.nextInt(); 
        
        ages = new ArrayList<Integer>(size); 
        
        for(int i = 0; i < size; i++) { 
            System.out.println("Enter "+(i+1)+" Age:"); 
            int data = sc.nextInt(); 
            ages.add(data); 
        } 
        
        // close Scanner class object 
        sc.close(); 
        
        // use tryAdvance() method to print ArrayList elements 
        System.out.println("Elements of the ArrayList: "); 
        
        // use spliterator() method to obtain Spliterator object on ages 
        Spliterator<Integer> spliterator1 = ages.spliterator(); 
        
        while(spliterator1.tryAdvance((n) -> System.out.println(n))); 
        
        // Use tryAdvance() to get absolute values of elements of ArrayList. 
        
        // create a new list that contains absolute values. 
        ArrayList<Integer> newAges = new ArrayList<>(); 
        
        spliterator1 = ages.spliterator(); 
        
        while(spliterator1.tryAdvance((n) -> newAges.add(Math.abs(n)))); 
        
        System.out.print("Absolute values of the elements of the ArrayList:\n"); 
        
        // use spliterator() to get Spliterator object on newAges 
        spliterator1 = newAges.spliterator(); 
        
        
        while(spliterator1.tryAdvance((n) -> System.out.println(n))); 
        
    } 
} 

Output: