Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Java DoubleStream: Primitive Double Streams Explained

Learn how to use Java DoubleStream for efficient primitive double processing, including creation, operations, performance tradeoffs, and edge cases.

~4 min readJava
#Java#DoubleStream#Stream API#Primitive Streams
Diagram of a DoubleStream pipeline transforming primitive double values through filter and map stages into a summary statistics result.

DoubleStream is a specialized stream type in the java.util.stream package that operates on primitive double values. Unlike Stream<Double>, which boxes each value into a Double object, DoubleStream keeps values as raw primitives throughout the pipeline. This distinction matters for both memory footprint and iteration overhead, especially when a pipeline processes large collections of floating-point data.

DoubleStream follows the same general shape as the other primitive stream types (IntStream and LongStream): you create a stream, apply zero or more intermediate operations, and finish with a terminal operation that produces a result or side effect.

Creating a DoubleStream

The DoubleStream interface provides several factory methods for constructing streams from different sources.

java
DoubleStream.of(1.5, 2.5, 3.5); DoubleStream.iterate(0.0, d -> d + 0.5).limit(10); DoubleStream.generate(Math::random).limit(5); DoubleStream.builder() .add(1.0) .add(2.0) .add(3.0) .build();

of is the simplest option when you have a fixed set of values. iterate produces an infinite stream from a seed and a DoubleUnaryOperator that computes the next value, so it must be paired with limit to avoid an unbounded pipeline. generate works similarly for values produced by a supplier. The builder is useful when the number of elements is not known until runtime.

You can also convert an array or a collection into a DoubleStream:

java
double[] values = {1.0, 2.0, 3.0}; DoubleStream stream = Arrays.stream(values); List<Double> list = List.of(1.0, 2.0, 3.0); DoubleStream fromList = list.stream().mapToDouble(Double::doubleValue);

Arrays.stream accepts a double[] directly. For a List<Double>, you map each boxed value back to a primitive with mapToDouble.

Intermediate Operations on DoubleStream

Intermediate operations transform the stream and return a new DoubleStream. They are lazy; nothing executes until a terminal operation is invoked.

java
DoubleStream.of(1.0, 2.0, 3.0, 4.0) .filter(d -> d > 2.0) .map(d -> d * 10) .distinct() .sorted();

filter keeps only values that satisfy the predicate. map applies a DoubleUnaryOperator to each element. distinct removes duplicates, and sorted orders the remaining values in ascending order.

Unlike Stream<Double>, the primitive stream does not accept a general Function<T, R> for map. The operation takes a DoubleUnaryOperator, a functional interface with a double applyAsDouble(double) method. This avoids boxing at every stage of the pipeline.

boxed() converts a DoubleStream into a Stream<Double>. This is occasionally necessary when you need to use a collector that only works with object streams, such as Collectors.toList().

java
List<Double> list = DoubleStream.of(1.0, 2.0, 3.0) .boxed() .collect(Collectors.toList());

Terminal Operations and Their Return Types

Terminal operations trigger pipeline execution. DoubleStream provides several that return primitive results directly.

java
double sum = DoubleStream.of(1.0, 2.0, 3.0).sum(); OptionalDouble average = DoubleStream.of(1.0, 2.0, 3.0).average(); OptionalDouble max = DoubleStream.of(1.0, 2.0, 3.0).max(); long count = DoubleStream.of(1.0, 2.0, 3.0).count();

sum returns a primitive double. average and max return OptionalDouble because the stream may be empty. Calling getAsDouble() on an empty OptionalDouble throws NoSuchElementException, so check isPresent() first or use orElse.

summaryStatistics() bundles several results into a single object:

java
DoubleSummaryStatistics stats = DoubleStream.of(1.0, 2.0, 3.0) .summaryStatistics(); double min = stats.getMin(); double max = stats.getMax(); double avg = stats.getAverage(); long count = stats.getCount();

When you need multiple aggregate results, summaryStatistics() computes them in a single pass, so the stream is consumed only once.

forEach and forEachOrdered are terminal operations for side effects. Use forEachOrdered when the order of processing matters for parallel streams.

Performance: Why Primitive Streams Avoid Boxing

The main reason to choose DoubleStream over Stream<Double> is allocation. Each element in a Stream<Double> is a reference to a Double object. When a pipeline processes millions of values, boxing creates a large number of short-lived objects that the garbage collector must reclaim.

DoubleStream operates on primitive double values, so a pipeline that stays primitive avoids allocating a Double object for each element. The difference is most visible when processing large arrays. For small datasets, the overhead is negligible, and readability may matter more than allocation cost.

There is a tradeoff. DoubleStream supports a narrower set of operations than Stream<Double>. You cannot apply arbitrary Function instances to elements without converting to an object stream. If your pipeline relies heavily on custom object transformations, the boxing cost may be unavoidable.

Edge Cases: NaN, Infinity, and Empty Streams

Floating-point semantics introduce behavior that differs from integer streams. For example, sum() returns NaN if the stream contains Double.NaN, and it also returns NaN if the stream contains both positive and negative infinity. min() and max() use the natural ordering of double values, which treats -0.0 as less than 0.0.

An empty DoubleStream produces OptionalDouble.empty() for average, min, and max. sum() returns 0.0 for an empty stream, and count() returns 0.

java
OptionalDouble result = DoubleStream.empty().average(); System.out.println(result.isPresent()); // false

DoubleStream.empty() is the standard way to represent a stream with no elements. It is useful when a method must return a DoubleStream but has no data to provide.

DoubleStream vs Stream<Double>: Choosing the Right Type

The choice between the two types depends on the source data and the operations required.

ConsiderationDoubleStreamStream<Double>
Element storagePrimitive doubleBoxed Double reference
Per-element allocationNoneOne object per element
Available operationsPrimitive-specific setFull Stream API
Conversionboxed() to object streammapToDouble() to primitive

Use DoubleStream when the data originates from a double[] or a computation that produces primitives, and when the pipeline consists of filtering, mapping, and aggregation. Use Stream<Double> when you need collectors, custom Function transformations, or interoperability with generic APIs that require object types.

A common pattern is to convert a Stream<Double> to DoubleStream early in the pipeline, perform the heavy numeric work, and convert back only at the end if necessary. This keeps the allocation-heavy portion of the pipeline as small as possible while still allowing object-stream operations where they are genuinely required.

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.