Java 8 IntSummaryStatistics and summaryStatistics()

Introduction

This tutorial explains Java 8's summaryStatistics() method of IntStream, LongStream and DoubleStream, and the classes it returns: IntSummaryStatistics, LongSummaryStatistics and DoubleSummaryStatistics. One call gives the count, sum, minimum, maximum and average of a stream in a single pass. We will see how the statistics object works inside, what it holds for an empty stream, how to fill it without a stream and merge two of them with accept() and combine(), and how it relates to the summarizingInt() collector.

(Note - This tutorial uses primitive streams and mapToInt(), explained in Java 8 primitive streamsClick to read tutorial: Java 8 Primitive Streams: mapToInt, mapToObj and boxed.)

One pass instead of five

Suppose you need the fastest, the slowest and the average of a list of response times, plus how many there were and their total. With the individual terminal operations that is five streams, and each one walks through all the data again - a stream can be used only once. summaryStatistics() walks through the data once and keeps five running values while it does. Java 8 summaryStatistics keeps count, sum, min and max while the stream passes once, instead of five separate streams
An IntSummaryStatistics object is a small accumulator. Its accept(int value) method adds one value: it increases the count, adds to the sum and updates the minimum and maximum. The average is not stored; getAverage() divides the sum by the count when you ask for it. The getters are getCount(), getSum(), getMin(), getMax() and getAverage().

The three classes and their types

  • IntSummaryStatistics (from IntStream.summaryStatistics()): getCount() and getSum() return long, getMin() and getMax() return int, getAverage() returns double. Because the sum is a long, it does not overflow where IntStream.sum() would.
  • LongSummaryStatistics (from LongStream): the same with long minimum, maximum and sum. It also accepts int values.
  • DoubleSummaryStatistics (from DoubleStream): double sum, minimum, maximum and average. Its sum uses compensated summation, which loses less precision than adding the doubles one by one.
All three are mutable and not thread-safe; the stream takes care of that when it runs in parallel, as we will see below.

Java 8 code example of summaryStatistics()

The program works with the response times of a web page, in milliseconds.
Java 8 code using IntStream.summaryStatistics(), IntSummaryStatistics getters, accept() and combine()
//ResponseTimes.java
import java.util.Arrays;
import java.util.DoubleSummaryStatistics;
import java.util.IntSummaryStatistics;
import java.util.List;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.stream.IntStream;

public class ResponseTimes {

  public static void main(String[] args) {
    List<Integer> times = Arrays.asList(120, 95, 310, 88, 143, 102, 97);

    // 1. All five statistics in one call
    IntSummaryStatistics stats = times.stream().mapToInt(Integer::intValue).summaryStatistics();
    System.out.println("1. " + stats);
    System.out.printf("   fastest %d ms, slowest %d ms, average %.1f ms over %d requests%n",
        stats.getMin(), stats.getMax(), stats.getAverage(), stats.getCount());

    // 2. How often the data is read: four streams against one
    AtomicInteger reads = new AtomicInteger();
    times.stream().mapToInt(t -> { reads.incrementAndGet(); return t; }).min();
    times.stream().mapToInt(t -> { reads.incrementAndGet(); return t; }).max();
    times.stream().mapToInt(t -> { reads.incrementAndGet(); return t; }).average();
    times.stream().mapToInt(t -> { reads.incrementAndGet(); return t; }).sum();
    int fourStreams = reads.getAndSet(0);
    times.stream().mapToInt(t -> { reads.incrementAndGet(); return t; }).summaryStatistics();
    System.out.println("2. values read by four streams: " + fourStreams + ", by summaryStatistics(): " + reads.get());

    // 3. getSum() is a long, so it does not overflow like IntStream.sum()
    int[] uploads = {2_000_000_000, 2_000_000_000};
    System.out.println("3. IntStream.sum(): " + IntStream.of(uploads).sum()
        + ", getSum(): " + IntStream.of(uploads).summaryStatistics().getSum());

    // 4. An empty stream
    IntSummaryStatistics none = IntStream.empty().summaryStatistics();
    System.out.println("4. " + none);

    // 5. Without a stream: accept() one value at a time
    IntSummaryStatistics serverA = new IntSummaryStatistics();
    for (int t : new int[] {210, 180, 260}) {
      serverA.accept(t);
    }
    IntSummaryStatistics serverB = IntStream.of(90, 70).summaryStatistics();
    System.out.println("5. server A: " + serverA);

    // 6. combine() merges the statistics of server B into those of server A
    serverA.combine(serverB);
    System.out.println("6. both servers: " + serverA);

    // 7. What summaryStatistics() does: a three-argument collect(), also in parallel
    IntSummaryStatistics parallel = times.parallelStream().mapToInt(Integer::intValue)
        .collect(IntSummaryStatistics::new, IntSummaryStatistics::accept, IntSummaryStatistics::combine);
    System.out.println("7. parallel collect: " + parallel);

    // 8. DoubleSummaryStatistics: seconds instead of milliseconds
    DoubleSummaryStatistics seconds = times.stream().mapToDouble(t -> t / 1000.0).summaryStatistics();
    System.out.printf("8. %.3f s to %.3f s, total %.3f s%n", seconds.getMin(), seconds.getMax(), seconds.getSum());
  }
}
 OUTPUT of the above code
1. IntSummaryStatistics{count=7, sum=955, min=88, average=136.428571, max=310}
   fastest 88 ms, slowest 310 ms, average 136.4 ms over 7 requests
2. values read by four streams: 28, by summaryStatistics(): 7
3. IntStream.sum(): -294967296, getSum(): 4000000000
4. IntSummaryStatistics{count=0, sum=0, min=2147483647, average=0.000000, max=-2147483648}
5. server A: IntSummaryStatistics{count=3, sum=650, min=180, average=216.666667, max=260}
6. both servers: IntSummaryStatistics{count=5, sum=810, min=70, average=162.000000, max=260}
7. parallel collect: IntSummaryStatistics{count=7, sum=955, min=88, average=136.428571, max=310}
8. 0.088 s to 0.310 s, total 0.955 s

Explanation of the code

  • Part 1: mapToInt() turns the Integers into an IntStream, and summaryStatistics() returns all five values. toString() prints them on one line, which is handy for logging; the getters read them one by one.
  • Part 2: the counter in the lambda shows how many values each approach reads. Four terminal operations read the seven values four times; summaryStatistics() reads them once. (The program leaves out count(): since Java 9 it can skip the mapToInt() lambda when the size of the source is known, so the counter would not show its read.)
  • Part 3: two uploads of 2 billion bytes overflow the int that IntStream.sum() returns, but getSum() adds them in a long and is right.
  • Part 4: an empty stream gives a count of 0, a sum of 0 and an average of 0.0. The minimum is Integer.MAX_VALUE and the maximum Integer.MIN_VALUE - the starting values of the accumulator, not real data. Check getCount() before you show them.
  • Part 5: IntSummaryStatistics works without a stream too: create one with new and call accept() for each value, for example while reading a file line by line. It implements IntConsumer, so intStream.forEach(stats) also works.
  • Part 6: combine() adds the statistics of another object to this one - here the two requests of server B to the three of server A.
  • Part 7: summaryStatistics() is a three-argument collect() with exactly these method references. In a parallel stream each thread fills its own IntSummaryStatistics with accept(), and the partial results are merged with combine(), so no object is shared between threads. The result is the same as in part 1.
  • Part 8: mapToDouble() and DoubleSummaryStatistics work the same way with double values.

How it runs in parallel

Part 7 is worth a closer look, because it is the pattern every mutable accumulator in the Streams API follows. Java 8 parallel summaryStatistics - each chunk fills its own IntSummaryStatistics with accept, then combine merges them The stream splits the data into chunks, one per worker thread. Each chunk gets its own new IntSummaryStatistics from the supplier and fills it with accept(). When two chunks are done, combine() merges one into the other: the counts and sums are added, and the smaller minimum and larger maximum are kept. The same three steps - create, accumulate, merge - are what a custom collectorClick to read tutorial: Java 8 Custom Collector with Collector.of() Tutorial defines.

Which one to use - summaryStatistics() vs summarizingInt()

Collectors.summarizingInt() returns the same IntSummaryStatistics, but as a collector for a stream of objects. You do not need mapToInt() first, and above all it works as a downstream collector - for example the statistics per group with groupingBy(Order::getRegion, summarizingInt(Order::getQuantity)). Use summaryStatistics() when you already have a primitive stream and want one result, and the collector inside groupingBy()Click to read: groupingBy() or partitioningBy()Click to read: partitioningBy(). The collector is covered in summarizingInt, summarizingLong and summarizingDoubleClick to read: summarizingInt, summarizingLong and summarizingDouble.

Summary

In this tutorial we saw how summaryStatistics() computes the count, sum, minimum, maximum and average of a primitive stream in one pass, and which types IntSummaryStatistics, LongSummaryStatistics and DoubleSummaryStatistics return - including a long sum that does not overflow. We looked at the misleading minimum and maximum of an empty stream, filled the statistics without a stream with accept(), merged two with combine(), and saw that a parallel stream uses the same two methods. Lastly we compared it with the summarizingInt() collector.