Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Java IntStream: Working with Primitive Streams

Learn how to use Java IntStream for efficient primitive integer processing, covering creation, operations, performance, and common pitfalls.

~5 min readJava
#IntStream#Java Streams#Stream API#Functional Programming
Illustration of a Java IntStream pipeline showing primitive integer values flowing through transformation stages into an aggregated result.

The examples in this article show how to create and use IntStream for primitive integer processing. You will see the main factory methods, common intermediate and terminal operations, performance trade-offs, and edge cases that can lead to bugs.

What IntStream Is and Why It Exists

IntStream is a primitive specialization of the Stream API for int values, defined in the java.util.stream package. It provides the same functional-style pipeline model as Stream<T>, but operates directly on primitive int data. The main reason it exists is to avoid the boxing and unboxing overhead that occurs when integers are wrapped in Integer objects.

When you write Stream<Integer>, every element is an object reference. Operations like map, filter, and reduce can allocate Integer instances as values move through the pipeline. IntStream avoids that allocation for the common case of processing numeric data, which makes it a good fit for numeric range processing, aggregation, and bulk integer transformations.

Creating an IntStream

There are several ways to obtain an IntStream, and the choice depends on the source of your data.

The most direct approach is IntStream.of, which takes a varargs array of int values:

java
IntStream values = IntStream.of(3, 1, 4, 1, 5, 9);

For sequential integer ranges, range and rangeClosed are the most common factory methods:

java
IntStream open = IntStream.range(1, 5); // 1, 2, 3, 4 IntStream closed = IntStream.rangeClosed(1, 5); // 1, 2, 3, 4, 5

The difference is the upper bound: range excludes it, while rangeClosed includes it. This off-by-one distinction is a frequent source of bugs, so it is worth checking which one your loop logic expects.

If you have an existing int[] array, Arrays.stream gives you an IntStream directly:

java
int[] numbers = {10, 20, 30, 40}; IntStream stream = Arrays.stream(numbers);

For a List<Integer> or another collection, you convert through mapToInt:

java
List<Integer> list = List.of(5, 10, 15); IntStream stream = list.stream().mapToInt(Integer::intValue);

IntStream.iterate and IntStream.generate produce infinite streams. iterate applies a unary operator to the previous value, while generate calls a supplier for each element. Both require limit to terminate when consumed:

java
IntStream evens = IntStream.iterate(0, n -> n + 2).limit(10);

Intermediate Operations: Transforming the Stream

Intermediate operations are lazy; they do not execute until a terminal operation is invoked. The common ones for IntStream are filter, map, distinct, sorted, limit, and skip.

filter keeps elements that satisfy a predicate:

java
IntStream evenNumbers = IntStream.range(1, 100) .filter(n -> n % 2 == 0);

map transforms each element into another int:

java
IntStream squares = IntStream.range(1, 10) .map(n -> n * n);

distinct removes duplicates, and sorted orders the elements. Both are stateful operations. sorted buffers the entire stream, and distinct needs to track seen values, so the memory cost can be significant for large streams.

boxed converts an IntStream into a Stream<Integer>. You need this when you want to collect into a List<Integer> or use operations that only exist on the object stream:

java
List<Integer> collected = IntStream.range(1, 10) .boxed() .collect(Collectors.toList());

Without boxed, you cannot call collect with a Collector that expects objects.

Terminal Operations: Producing a Result

A terminal operation triggers the pipeline and produces a result. IntStream provides numeric aggregations that Stream<Integer> does not have directly.

sum, average, min, and max are the most frequently used:

java
int total = IntStream.range(1, 101).sum(); OptionalDouble avg = IntStream.of(4, 8, 15).average(); OptionalInt min = IntStream.of(4, 8, 15).min();

Note that average, min, and max return Optional types because the stream may be empty. sum returns 0 for an empty stream, which is consistent with the identity value of addition.

reduce gives you more control over the aggregation:

java
int product = IntStream.range(1, 6) .reduce(1, (a, b) -> a * b);

The first argument is the identity value, and the second is an associative accumulation function. The result is 120 for the range 1 through 5.

summaryStatistics collects count, sum, min, average, and max in a single pass:

java
IntSummaryStatistics stats = IntStream.of(3, 7, 2, 9) .summaryStatistics();

This is useful when you need multiple aggregate values and want to avoid traversing the stream more than once.

toArray produces an int[]:

java
int[] result = IntStream.range(1, 5).toArray();

A Practical Example: Finding Prime Numbers

A realistic use of IntStream is generating prime numbers within a range. The pipeline combines range, filter, and toArray:

java
int limit = 50; int[] primes = IntStream.rangeClosed(2, limit) .filter(n -> isPrime(n)) .toArray();

The isPrime helper checks divisibility up to the square root:

java
private static boolean isPrime(int n) { return IntStream.rangeClosed(2, (int) Math.sqrt(n)) .noneMatch(d -> n % d == 0); }

This example shows how IntStream composes well: the outer stream filters candidates, and the inner stream tests each candidate for divisibility. The noneMatch terminal operation returns true when no divisor is found.

Performance: Why Primitive Streams Matter

The main performance benefit of IntStream over Stream<Integer> is the elimination of boxing. Boxing an int into an Integer can add allocation pressure and GC work, especially in hot paths or large pipelines. IntStream avoids that by operating directly on primitive int values.

For small collections, the choice is usually not performance-critical. The benefit matters most for large numeric ranges or pipelines with many intermediate operations that would otherwise allocate boxed values.

Parallel streams add another dimension. IntStream.range is well-suited to parallel processing because the range is splittable into contiguous segments. parallel() on a range-based stream can scale across CPU cores for large workloads:

java
long sum = IntStream.rangeClosed(1, 10_000_000) .parallel() .asLongStream() .sum();

Note the asLongStream conversion: summing a large range of int values can overflow int. Using asLongStream avoids that overflow.

Common Pitfalls and Edge Cases

The most common mistake is confusing range with rangeClosed. IntStream.range(1, 10) produces 1 through 9, not 1 through 10. If your loop condition uses <=, you need rangeClosed.

Empty streams are another trap. Calling min() or max() on an empty IntStream returns an empty OptionalInt. Calling getAsInt() on that empty optional throws NoSuchElementException. Always handle the empty case:

java
OptionalInt max = IntStream.empty().max(); int value = max.orElse(0);

Infinite streams must be bounded before a terminal operation consumes them. IntStream.iterate(0, n -> n + 1).sum() would never terminate.

Stateful operations like sorted buffer the entire stream, and distinct must track seen values. In a parallel pipeline, this can negate the memory benefit of using a primitive stream in the first place, because the buffer holds elements before producing output.

Choosing Between IntStream and Traditional Loops

IntStream is not always the better choice. A simple for loop is often more readable for straightforward iteration, especially when you need to break out of the loop early or maintain multiple loop variables.

Use IntStream when:

  • You have a pipeline of transformations that would otherwise require nested loops and temporary collections.
  • You need aggregate results like sum, average, or statistics.
  • You want to parallelize a numeric computation over a range.
  • You are already working in a functional style elsewhere in the codebase.

Use a traditional loop when:

  • The logic requires early termination with break or return.
  • You need to mutate an external variable at each step.
  • The iteration order must be explicitly controlled.
  • Readability for the team matters more than functional composition.

There is no universal rule. The decision should be based on what the code is doing and how the rest of the codebase expresses similar logic.

Try matching browser tools

All tools

Small utilities that fit Java work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Java guides

More in Java

All Java guides

The guides filed next to this one in Java, in library order.