Java 8 IntSummaryStatistics and summaryStatistics()
Introduction
This tutorial explains Java 8'ssummaryStatistics() 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.

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(fromIntStream.summaryStatistics()):getCount()andgetSum()returnlong,getMin()andgetMax()returnint,getAverage()returnsdouble. Because the sum is along, it does not overflow whereIntStream.sum()would.LongSummaryStatistics(fromLongStream): the same withlongminimum, maximum and sum. It also acceptsintvalues.DoubleSummaryStatistics(fromDoubleStream):doublesum, minimum, maximum and average. Its sum uses compensated summation, which loses less precision than adding the doubles one by one.
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());
}
}
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 theIntegers into anIntStream, andsummaryStatistics()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 outcount(): since Java 9 it can skip themapToInt()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
intthatIntStream.sum()returns, butgetSum()adds them in alongand 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_VALUEand the maximumInteger.MIN_VALUE- the starting values of the accumulator, not real data. CheckgetCount()before you show them. - Part 5:
IntSummaryStatisticsworks without a stream too: create one withnewand callaccept()for each value, for example while reading a file line by line. It implementsIntConsumer, sointStream.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-argumentcollect()with exactly these method references. In a parallel stream each thread fills its ownIntSummaryStatisticswithaccept(), and the partial results are merged withcombine(), so no object is shared between threads. The result is the same as in part 1. - Part 8:
mapToDouble()andDoubleSummaryStatisticswork the same way withdoublevalues.
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.
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 howsummaryStatistics() 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.Java 8 Tutorials
Java 8 Primitive Streams: mapToInt, mapToObj and boxedClick to read tutorial: Java 8 Primitive Streams: mapToInt, mapToObj and boxed Java 8 Stream forEach vs forEachOrdered with ExamplesClick to read tutorial: Java 8 Stream forEach vs forEachOrdered with Examples Java 8 String chars() and codePoints() with ExamplesClick to read tutorial: Java 8 String chars() and codePoints() with Examples Java 8 Streams API Tutorial with ExamplesClick to read tutorial: Java 8 Streams API Tutorial with Examples Java 8 IntStream range() and rangeClosed() with ExamplesClick to read tutorial: Java 8 IntStream range() and rangeClosed() with Examples Java 8 Primitive Functional Interfaces TutorialClick to read tutorial: Java 8 Primitive Functional Interfaces Tutorial Java 8 Parallel Streams Tutorial with ExamplesClick to read tutorial: Java 8 Parallel Streams Tutorial with Examples
Java 8 Primitive Streams: mapToInt, mapToObj and boxedClick to read tutorial: Java 8 Primitive Streams: mapToInt, mapToObj and boxed Java 8 Stream forEach vs forEachOrdered with ExamplesClick to read tutorial: Java 8 Stream forEach vs forEachOrdered with Examples Java 8 String chars() and codePoints() with ExamplesClick to read tutorial: Java 8 String chars() and codePoints() with Examples Java 8 Streams API Tutorial with ExamplesClick to read tutorial: Java 8 Streams API Tutorial with Examples Java 8 IntStream range() and rangeClosed() with ExamplesClick to read tutorial: Java 8 IntStream range() and rangeClosed() with Examples Java 8 Primitive Functional Interfaces TutorialClick to read tutorial: Java 8 Primitive Functional Interfaces Tutorial Java 8 Parallel Streams Tutorial with ExamplesClick to read tutorial: Java 8 Parallel Streams Tutorial with Examples