How to Iterate Over a Stream With Indices

1. Overview

Java Streams are not collections and elements cannot be accessed using their indices, but there are still a few tricks to make this possible.

In this short article, we’re going to look at how to iterate over a Stream using IntStream, StreamUtils, EntryStream, and Vavr‘s Stream.

2. Using Plain Java

We can navigate through a Stream using an Integer range, and also benefit from the fact that the original elements are in an array or a collection accessible by indices.

Let’s implement a method which iterates with indices and demonstrates this approach.

Simply put, we want to get an array of Strings and only select even indexed elements:

public List<String> getEvenIndexedStrings(String[] names) {
    List<String> evenIndexedNames = IntStream
      .range(0, names.length)
      .filter(i -> i % 2 == 0)
      .mapToObj(i -> names[i])
      .collect(Collectors.toList());
    
    return evenIndexedNames;
}

Let’s now test out the implementation:

@Test
public void whenCalled_thenReturnListOfEvenIndexedStrings() {
    String[] names 
      = {"Afrim", "Bashkim", "Besim", "Lulzim", "Durim", "Shpetim"};
    List<String> expectedResult 
      = Arrays.asList("Afrim", "Besim", "Durim");
    List<String> actualResult 
      = StreamIndices.getEvenIndexedStrings(names);
   
    assertEquals(expectedResult, actualResult);
}

3. Using StreamUtils

Another way to iterate with indices can be done using zipWithIndex() method of StreamUtils from the proton-pack library (the latest version can be found here).

First, you need to add it to your pom.xml:

<dependency>
    <groupId>com.codepoetics</groupId>
    <artifactId>protonpack</artifactId>
    <version>1.16</version>
</dependency>

Now, let’s look at the code:

public List<Indexed<String>> getEvenIndexedStrings(List<String> names) {
    List<Indexed<String>> list = StreamUtils
      .zipWithIndex(names.stream())
      .filter(i -> i.getIndex() % 2 == 0)
      .collect(Collectors.toList());
    
    return list;
}

The following tests this method and passes successfully:

@Test
public void whenCalled_thenReturnListOfEvenIndexedStrings() {
    List<String> names = Arrays.asList(
      "Afrim", "Bashkim", "Besim", "Lulzim", "Durim", "Shpetim");
    List<Indexed<String>> expectedResult = Arrays.asList(
      Indexed.index(0, "Afrim"), 
      Indexed.index(2, "Besim"), 
      Indexed.index(4, "Durim"));
    List<Indexed<String>> actualResult 
      = StreamIndices.getEvenIndexedStrings(names);
    
    assertEquals(expectedResult, actualResult);
}

4. Using StreamEx

We can also iterate with indexes using filterKeyValue() of EntryStream class from StreamEx library (the latest version can be found here). First, we need to add it to our pom.xml:

<dependency>
    <groupId>one.util</groupId>
    <artifactId>streamex</artifactId>
    <version>0.8.1</version>
</dependency>

Let’s see a simple application of this method using our previous example:

public List<String> getEvenIndexedStringsVersionTwo(List<String> names) {
    return EntryStream.of(names)
      .filterKeyValue((index, name) -> index % 2 == 0)
      .values()
      .toList();
}

We’ll use a similar test to test this:

@Test
public void whenCalled_thenReturnListOfEvenIndexedStringsVersionTwo() {
    String[] names 
      = {"Afrim", "Bashkim", "Besim", "Lulzim", "Durim", "Shpetim"};
    List<String> expectedResult 
      = Arrays.asList("Afrim", "Besim", "Durim");
    List<String> actualResult 
      = StreamIndices.getEvenIndexedStrings(names);
   
   assertEquals(expectedResult, actualResult);
}

5. Iteration Using Vavr‘s Stream

Another plausible way of iteration is using zipWithIndex() method of Vavr (previously known as Javaslang)’s Stream implementation:

<dependency>	
     <groupId>io.vavr</groupId>	
     <artifactId>vavr</artifactId>	
    <version>0.10.4</version>	
</dependency>

public List<String> getOddIndexedStringsVersionTwo(String[] names) {
    return Stream
      .of(names)
      .zipWithIndex()
      .filter(tuple -> tuple._2 % 2 == 1)
      .map(tuple -> tuple._1)
      .toJavaList();
}

We can test this example with the following method:

@Test
public void whenCalled_thenReturnListOfOddStringsVersionTwo() {
    String[] names 
      = {"Afrim", "Bashkim", "Besim", "Lulzim", "Durim", "Shpetim"};
    List<String> expectedResult 
      = Arrays.asList("Bashkim", "Lulzim", "Shpetim");
    List<String> actualResult 
      = StreamIndices.getOddIndexedStringsVersionTwo(names);

    assertEquals(expectedResult, actualResult);
}

If you want to read more about Vavr, check this article.

6. Using AtomicInteger

An alternative approach to tracking indices within a Stream is by utilizing AtomicInteger, which allows us to maintain a mutable counter across lambda expressions. This works well with sequential streams because the elements are processed in order. Here’s how we can implement it:

public List<String> getEvenIndexedStringsUsingAtomicInteger(String[] names) {
    AtomicInteger index = new AtomicInteger(0);
    return Arrays.stream(names)
      .filter(name -> index.getAndIncrement() % 2 == 0)
      .collect(Collectors.toList());
}

This approach works as expected in sequential streams, where elements are processed in a predictable, sequential manner:

@Test
public void whenCalledSequentially_thenReturnListOfEvenIndexedStrings() {
    String[] names = {"Afrim", "Bashkim", "Besim", "Lulzim", "Durim", "Shpetim"};
    List<String> expectedResult = Arrays.asList("Afrim", "Besim", "Durim");
    List<String> actualResult = StreamIndices.getEvenIndexedStringsUsingAtomicInteger(names);
    
    assertEquals(expectedResult, actualResult);
}

While AtomicInteger works well in sequential streams, it has significant drawbacks when applied to parallel streams due to potential race conditions. In a parallel stream, elements may be processed concurrently by multiple threads, and this can result in an unpredictable order of element processing.

The getAndIncrement() is atomic, the order of element processing isn’t guaranteed. This can cause inconsistent index assignments, as threads may increment the counter out of sync with the actual order of elements:

public List<String> getEvenIndexedStringsAtomicIntegerParallel(String[] names) {
    AtomicInteger index = new AtomicInteger(0);
    return Arrays.stream(names)
      .parallel()  // Switch to parallel stream
      .filter(name -> index.getAndIncrement() % 2 == 0)
      .collect(Collectors.toList());
}

When running the above method in parallel, the result can be inconsistent because of race conditions. Here’s an example of a test where we expect potential failures:

@Test
public void whenCalledInParallel_thenResultInconsistent() {
    String[] names = {"Afrim", "Bashkim", "Besim", "Lulzim", "Durim", "Shpetim"};
    List<String> result = StreamIndices.getEvenIndexedStringsAtomicIntegerParallel(names);
    
    // May fail intermittently in parallel mode
    assertNotEquals(Arrays.asList("Afrim", "Besim", "Durim"), result); 
}

To avoid this issue in parallel streams, we could switch to other mechanisms for indexing elements, such as using IntStream.range(). This would eliminate the race condition and ensure correct indexing.

7. Conclusion

In this quick tutorial, we saw four approaches on how to iterate through streams using indices. Streams have gotten a lot of attention and being able to also iterate through them with indices can be helpful.

There are a lot of features that are included in Java 8 Streams, some of which are already covered on Baeldung.