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#reduce(java.util.function.BinaryOperator) reduction} + * target for a {@linkplain java.util.stream.Stream stream}. For example: + * + *
{@code
+ * DoubleSummaryStatistics stats = people.stream()
+ * .collect(Collectors.toDoubleSummaryStatistics(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#toDoubleSummaryStatistics(java.util.function.ToDoubleFunction)
+ * Collectors.toDoubleStatistics()} 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 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;
+ sum += 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;
+ sum += other.sum;
+ min = Math.min(min, other.min);
+ max = Math.max(max, other.max);
+ }
+
+ /**
+ * 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 sum returned can vary depending upon the order in which
+ * values are recorded. This is due to accumulated rounding error in
+ * addition of values of differing magnitudes. Values sorted by increasing
+ * absolute magnitude tend to yield more accurate results. If any recorded
+ * value is a {@code NaN} or the sum is at any point a {@code NaN} then the
+ * sum will be {@code NaN}.
+ *
+ * @return the sum of values, or zero if none
+ */
+ public final double getSum() {
+ return sum;
+ }
+
+ /**
+ * Returns the minimum recorded value, {@code Double.NaN} if any recorded
+ * value was NaN or {@code Double.POSITIVE_INFINITY} if no values were
+ * recorded. Unlike the numerical comparison operators, this method
+ * considers negative zero to be strictly smaller than positive zero.
+ *
+ * @return the minimum recorded value, {@code Double.NaN} if any recorded
+ * value was NaN or {@code Double.POSITIVE_INFINITY} if no values were
+ * recorded
+ */
+ public final double getMin() {
+ return min;
+ }
+
+ /**
+ * Returns the maximum recorded value, {@code Double.NaN} if any recorded
+ * value was NaN or {@code Double.NEGATIVE_INFINITY} if no values were
+ * recorded. Unlike the numerical comparison operators, this method
+ * considers negative zero to be strictly smaller than positive zero.
+ *
+ * @return the maximum recorded value, {@code Double.NaN} if any recorded
+ * value was NaN or {@code Double.NEGATIVE_INFINITY} if no values were
+ * recorded
+ */
+ public final double getMax() {
+ return max;
+ }
+
+ /**
+ * Returns the average of values recorded, or zero if no values have been
+ * recorded. The average returned can vary depending upon the order in
+ * which values are recorded. This is due to accumulated rounding error in
+ * addition of values of differing magnitudes. Values sorted by increasing
+ * absolute magnitude tend to yield more accurate results. If any recorded
+ * value is a {@code NaN} or the sum is at any point a {@code NaN} then the
+ * average will be {@code NaN}.
+ *
+ * @return the average 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());
+ }
+}
diff --git a/jdk/src/share/classes/java/util/IntSummaryStatistics.java b/jdk/src/share/classes/java/util/IntSummaryStatistics.java
new file mode 100644
index 00000000000..f179e67478b
--- /dev/null
+++ b/jdk/src/share/classes/java/util/IntSummaryStatistics.java
@@ -0,0 +1,170 @@
+/*
+ * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+package java.util;
+
+import java.util.function.IntConsumer;
+
+/**
+ * A state object for collecting statistics such as count, min, max, sum, and
+ * average.
+ *
+ * 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 ints with: + *
{@code
+ * IntSummaryStatistics stats = intStream.collect(IntSummaryStatistics::new,
+ * IntSummaryStatistics::accept,
+ * IntSummaryStatistics::combine);
+ * }
+ *
+ * {@code IntSummaryStatistics} can be used as a + * {@linkplain java.util.stream.Stream#reduce(java.util.function.BinaryOperator) reduction} + * target for a {@linkplain java.util.stream.Stream stream}. For example: + * + *
{@code
+ * IntSummaryStatistics stats = people.stream()
+ * .collect(Collectors.toIntSummaryStatistics(Person::getDependents));
+ *}
+ *
+ * This computes, in a single pass, the count of people, as well as the minimum,
+ * maximum, sum, and average of their number of dependents.
+ *
+ * @implNote This implementation is not thread safe. However, it is safe to use
+ * {@link java.util.stream.Collectors#toIntSummaryStatistics(java.util.function.ToIntFunction)
+ * Collectors.toIntStatistics()} 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.
+ *
+ * This implementation does not check for overflow of the sum. + * @since 1.8 + */ +public class IntSummaryStatistics implements IntConsumer { + private long count; + private long sum; + private int min = Integer.MAX_VALUE; + private int max = Integer.MIN_VALUE; + + /** + * Construct an empty instance with zero count, zero sum, + * {@code Integer.MAX_VALUE} min, {@code Integer.MIN_VALUE} max and zero + * average. + */ + public IntSummaryStatistics() { } + + /** + * Records a new value into the summary information + * + * @param value the input value + */ + @Override + public void accept(int value) { + ++count; + sum += value; + min = Math.min(min, value); + max = Math.max(max, value); + } + + /** + * Combines the state of another {@code IntSummaryStatistics} into this one. + * + * @param other another {@code IntSummaryStatistics} + * @throws NullPointerException if {@code other} is null + */ + public void combine(IntSummaryStatistics other) { + count += other.count; + sum += other.sum; + min = Math.min(min, other.min); + max = Math.max(max, other.max); + } + + /** + * Returns 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. + * + * @return the sum of values, or zero if none + */ + public final long getSum() { + return sum; + } + + /** + * Returns the minimum value recorded, or {@code Integer.MAX_VALUE} if no + * values have been recorded. + * + * @return the minimum value, or {@code Integer.MAX_VALUE} if none + */ + public final int getMin() { + return min; + } + + /** + * Returns the maximum value recorded, or {@code Integer.MIN_VALUE} if no + * values have been recorded. + * + * @return the maximum value, or {@code Integer.MIN_VALUE} if none + */ + public final int getMax() { + return max; + } + + /** + * Returns the average of values recorded, or zero if no values have been + * recorded. + * + * @return the average of values, or zero if none + */ + public final double getAverage() { + return getCount() > 0 ? (double) getSum() / getCount() : 0.0d; + } + + @Override + /** + * {@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. + */ + public String toString() { + return String.format( + "%s{count=%d, sum=%d, min=%d, average=%d, max=%d}", + this.getClass().getSimpleName(), + getCount(), + getSum(), + getMin(), + getAverage(), + getMax()); + } +} diff --git a/jdk/src/share/classes/java/util/LongSummaryStatistics.java b/jdk/src/share/classes/java/util/LongSummaryStatistics.java new file mode 100644 index 00000000000..3c7b7aee561 --- /dev/null +++ b/jdk/src/share/classes/java/util/LongSummaryStatistics.java @@ -0,0 +1,182 @@ +/* + * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ +package java.util; + +import java.util.function.IntConsumer; +import java.util.function.LongConsumer; + +/** + * A state object for collecting statistics such as count, min, max, sum, and + * average. + * + *
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 longs with: + *
{@code
+ * LongSummaryStatistics stats = longStream.collect(LongSummaryStatistics::new,
+ * LongSummaryStatistics::accept,
+ * LongSummaryStatistics::combine);
+ * }
+ *
+ * {@code LongSummaryStatistics} can be used as a + * {@linkplain java.util.stream.Stream#reduce(java.util.function.BinaryOperator) reduction} + * target for a {@linkplain java.util.stream.Stream stream}. For example: + * + *
{@code
+ * LongSummaryStatistics stats = people.stream()
+ * .collect(Collectors.toLongSummaryStatistics(Person::getAge));
+ *}
+ *
+ * This computes, in a single pass, the count of people, as well as the minimum,
+ * maximum, sum, and average of their ages in milliseconds.
+ *
+ * @implNote This implementation is not thread safe. However, it is safe to use
+ * {@link java.util.stream.Collectors#toLongSummaryStatistics(java.util.function.ToLongFunction)
+ * Collectors.toLongStatistics()} 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.
+ *
+ * This implementation does not check for overflow of the sum. + * @since 1.8 + */ +public class LongSummaryStatistics implements LongConsumer, IntConsumer { + private long count; + private long sum; + private long min = Long.MAX_VALUE; + private long max = Long.MIN_VALUE; + + /** + * Construct an empty instance with zero count, zero sum, + * {@code Long.MAX_VALUE} min, {@code Long.MIN_VALUE} max and zero + * average. + */ + public LongSummaryStatistics() { } + + /** + * Records a new {@code int} value into the summary information. + * + * @param value the input value + */ + @Override + public void accept(int value) { + accept((long) value); + } + + /** + * Records a new {@code long} value into the summary information. + * + * @param value the input value + */ + @Override + public void accept(long value) { + ++count; + sum += value; + min = Math.min(min, value); + max = Math.max(max, value); + } + + /** + * Combines the state of another {@code LongSummaryStatistics} into this + * one. + * + * @param other another {@code LongSummaryStatistics} + * @throws NullPointerException if {@code other} is null + */ + public void combine(LongSummaryStatistics other) { + count += other.count; + sum += other.sum; + min = Math.min(min, other.min); + max = Math.max(max, other.max); + } + + /** + * Returns 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. + * + * @return the sum of values, or zero if none + */ + public final long getSum() { + return sum; + } + + /** + * Returns the minimum value recorded, or {@code Long.MAX_VALUE} if no + * values have been recorded. + * + * @return the minimum value, or {@code Long.MAX_VALUE} if none + */ + public final long getMin() { + return min; + } + + /** + * Returns the maximum value recorded, or {@code Long.MIN_VALUE} if no + * values have been recorded + * + * @return the maximum value, or {@code Long.MIN_VALUE} if none + */ + public final long getMax() { + return max; + } + + /** + * Returns the average of values recorded, or zero if no values have been + * recorded. + * + * @return The average of values, or zero if none + */ + public final double getAverage() { + return getCount() > 0 ? (double) getSum() / getCount() : 0.0d; + } + + @Override + /** + * {@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. + */ + public String toString() { + return String.format( + "%s{count=%d, sum=%d, min=%d, average=%d, max=%d}", + this.getClass().getSimpleName(), + getCount(), + getSum(), + getMin(), + getAverage(), + getMax()); + } +}