This class is designed to work with (though does not require) + * {@linkplain java.util.stream streams}. For example, you can compute + * summary statistics on a stream of doubles with: + *
{@code
+ * DoubleSummaryStatistics stats = doubleStream.collect(DoubleSummaryStatistics::new,
+ * DoubleSummaryStatistics::accept,
+ * DoubleSummaryStatistics::combine);
+ * }
+ *
+ * {@code DoubleSummaryStatistics} can be used as a + * {@linkplain java.util.stream.Stream#collect(Collector) reduction} + * target for a {@linkplain java.util.stream.Stream stream}. For example: + * + *
{@code
+ * DoubleSummaryStatistics stats = people.stream()
+ * .collect(Collectors.summarizingDouble(Person::getWeight));
+ *}
+ *
+ * This computes, in a single pass, the count of people, as well as the minimum,
+ * maximum, sum, and average of their weights.
+ *
+ * @implNote This implementation is not thread safe. However, it is safe to use
+ * {@link java.util.stream.Collectors#summarizingDouble(java.util.function.ToDoubleFunction)
+ * Collectors.summarizingDouble()} on a parallel stream, because the parallel
+ * implementation of {@link java.util.stream.Stream#collect Stream.collect()}
+ * provides the necessary partitioning, isolation, and merging of results for
+ * safe and efficient parallel execution.
+ * @since 1.8
+ */
+public class DoubleSummaryStatistics implements DoubleConsumer {
+ private long count;
+ private double sum;
+ private double sumCompensation; // Low order bits of sum
+ private double simpleSum; // Used to compute right sum for non-finite inputs
+ private double min = Double.POSITIVE_INFINITY;
+ private double max = Double.NEGATIVE_INFINITY;
+
+ /**
+ * Construct an empty instance with zero count, zero sum,
+ * {@code Double.POSITIVE_INFINITY} min, {@code Double.NEGATIVE_INFINITY}
+ * max and zero average.
+ */
+ public DoubleSummaryStatistics() { }
+
+ /**
+ * Records another value into the summary information.
+ *
+ * @param value the input value
+ */
+ @Override
+ public void accept(double value) {
+ ++count;
+ simpleSum += value;
+ sumWithCompensation(value);
+ min = Math.min(min, value);
+ max = Math.max(max, value);
+ }
+
+ /**
+ * Combines the state of another {@code DoubleSummaryStatistics} into this
+ * one.
+ *
+ * @param other another {@code DoubleSummaryStatistics}
+ * @throws NullPointerException if {@code other} is null
+ */
+ public void combine(DoubleSummaryStatistics other) {
+ count += other.count;
+ simpleSum += other.simpleSum;
+ sumWithCompensation(other.sum);
+ sumWithCompensation(other.sumCompensation);
+ min = Math.min(min, other.min);
+ max = Math.max(max, other.max);
+ }
+
+ /**
+ * Incorporate a new double value using Kahan summation /
+ * compensated summation.
+ */
+ private void sumWithCompensation(double value) {
+ double tmp = value - sumCompensation;
+ double velvel = sum + tmp; // Little wolf of rounding error
+ sumCompensation = (velvel - sum) - tmp;
+ sum = velvel;
+ }
+
+ /**
+ * Return the count of values recorded.
+ *
+ * @return the count of values
+ */
+ public final long getCount() {
+ return count;
+ }
+
+ /**
+ * Returns the sum of values recorded, or zero if no values have been
+ * recorded.
+ *
+ * The value of a floating-point sum is a function both of the + * input values as well as the order of addition operations. The + * order of addition operations of this method is intentionally + * not defined to allow for implementation flexibility to improve + * the speed and accuracy of the computed result. + * + * In particular, this method may be implemented using compensated + * summation or other technique to reduce the error bound in the + * numerical sum compared to a simple summation of {@code double} + * values. + * + * Because of the unspecified order of operations and the + * possibility of using differing summation schemes, the output of + * this method may vary on the same input values. + * + *
Various conditions can result in a non-finite sum being + * computed. This can occur even if the all the recorded values + * being summed are finite. If any recorded value is non-finite, + * the sum will be non-finite: + * + *
The computed average can vary numerically and have the + * special case behavior as computing the sum; see {@link #getSum} + * for details. + * + * @apiNote Values sorted by increasing absolute magnitude tend to yield + * more accurate results. + * + * @return the arithmetic mean of values, or zero if none + */ + public final double getAverage() { + return getCount() > 0 ? getSum() / getCount() : 0.0d; + } + + /** + * {@inheritDoc} + * + * Returns a non-empty string representation of this object suitable for + * debugging. The exact presentation format is unspecified and may vary + * between implementations and versions. + */ + @Override + public String toString() { + return String.format( + "%s{count=%d, sum=%f, min=%f, average=%f, max=%f}", + this.getClass().getSimpleName(), + getCount(), + getSum(), + getMin(), + getAverage(), + getMax()); + } +}