OpenJDK / type-annotations / type-annotations / jdk
changeset 7011:d9f9040554d6
8010953: Add primitive summary statistics utils
Reviewed-by: mduigou, dholmes, chegar, darcy
Contributed-by: Brian Goetz <brian.goetz@oracle.com>
author | mduigou |
---|---|
date | Wed, 17 Apr 2013 11:39:52 -0700 |
parents | 7ded74ffea36 |
children | 73e3b474125e |
files | src/share/classes/java/util/DoubleSummaryStatistics.java src/share/classes/java/util/IntSummaryStatistics.java src/share/classes/java/util/LongSummaryStatistics.java |
diffstat | 3 files changed, 539 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/share/classes/java/util/DoubleSummaryStatistics.java Wed Apr 17 11:39:52 2013 -0700 @@ -0,0 +1,187 @@ +/* + * 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.DoubleConsumer; + +/** + * A state object for collecting statistics such as count, min, max, sum, and + * average. + * + * <p>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: + * <pre> {@code + * DoubleSummaryStatistics stats = doubleStream.collect(DoubleSummaryStatistics::new, + * DoubleSummaryStatistics::accept, + * DoubleSummaryStatistics::combine); + * }</pre> + * + * <p>{@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: + * + * <pre> {@code + * DoubleSummaryStatistics stats = people.stream() + * .collect(Collectors.toDoubleSummaryStatistics(Person::getWeight)); + *}</pre> + * + * 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()); + } +}
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/share/classes/java/util/IntSummaryStatistics.java Wed Apr 17 11:39:52 2013 -0700 @@ -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. + * + * <p>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: + * <pre> {@code + * IntSummaryStatistics stats = intStream.collect(IntSummaryStatistics::new, + * IntSummaryStatistics::accept, + * IntSummaryStatistics::combine); + * }</pre> + * + * <p>{@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: + * + * <pre> {@code + * IntSummaryStatistics stats = people.stream() + * .collect(Collectors.toIntSummaryStatistics(Person::getDependents)); + *}</pre> + * + * 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. + * + * <p>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()); + } +}
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/share/classes/java/util/LongSummaryStatistics.java Wed Apr 17 11:39:52 2013 -0700 @@ -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. + * + * <p>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: + * <pre> {@code + * LongSummaryStatistics stats = longStream.collect(LongSummaryStatistics::new, + * LongSummaryStatistics::accept, + * LongSummaryStatistics::combine); + * }</pre> + * + * <p>{@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: + * + * <pre> {@code + * LongSummaryStatistics stats = people.stream() + * .collect(Collectors.toLongSummaryStatistics(Person::getAge)); + *}</pre> + * + * 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. + * + * <p>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()); + } +}