1 /*
2 * Copyright (c) 2012, 2017, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25 package java.util;
26
27 import java.util.function.DoubleConsumer;
28 import java.util.stream.Collector;
29 import java.util.stream.DoubleStream;
30
31 /**
32 * A state object for collecting statistics such as count, min, max, sum, and
33 * average.
34 *
35 * <p>This class is designed to work with (though does not require)
36 * {@linkplain java.util.stream streams}. For example, you can compute
37 * summary statistics on a stream of doubles with:
38 * <pre> {@code
39 * DoubleSummaryStatistics stats = doubleStream.collect(DoubleSummaryStatistics::new,
40 * DoubleSummaryStatistics::accept,
41 * DoubleSummaryStatistics::combine);
42 * }</pre>
43 *
44 * <p>{@code DoubleSummaryStatistics} can be used as a
45 * {@linkplain java.util.stream.Stream#collect(Collector) reduction}
46 * target for a {@linkplain java.util.stream.Stream stream}. For example:
47 *
48 * <pre> {@code
49 * DoubleSummaryStatistics stats = people.stream()
50 * .collect(Collectors.summarizingDouble(Person::getWeight));
51 *}</pre>
52 *
53 * This computes, in a single pass, the count of people, as well as the minimum,
54 * maximum, sum, and average of their weights.
55 *
56 * @implNote This implementation is not thread safe. However, it is safe to use
57 * {@link java.util.stream.Collectors#summarizingDouble(java.util.function.ToDoubleFunction)
58 * Collectors.summarizingDouble()} on a parallel stream, because the parallel
59 * implementation of {@link java.util.stream.Stream#collect Stream.collect()}
60 * provides the necessary partitioning, isolation, and merging of results for
61 * safe and efficient parallel execution.
62 * @since 1.8
63 */
64 public class DoubleSummaryStatistics implements DoubleConsumer {
65 private long count;
66 private double sum;
67 private double sumCompensation; // Low order bits of sum
68 private double simpleSum; // Used to compute right sum for non-finite inputs
69 private double min = Double.POSITIVE_INFINITY;
70 private double max = Double.NEGATIVE_INFINITY;
71
72 /**
73 * Constructs an empty instance with zero count, zero sum,
74 * {@code Double.POSITIVE_INFINITY} min, {@code Double.NEGATIVE_INFINITY}
75 * max and zero average.
76 */
77 public DoubleSummaryStatistics() { }
78
79 /**
80 * Constructs a non-empty instance with the specified {@code count},
81 * {@code min}, {@code max}, and {@code sum}.
82 *
83 * <p>If {@code count} is zero then the remaining arguments are ignored and
84 * an empty instance is constructed.
85 *
86 * <p>If the arguments are inconsistent then an {@code IllegalArgumentException}
87 * is thrown. The necessary consistent argument conditions are:
88 * <ul>
89 * <li>{@code count >= 0}</li>
90 * <li>{@code (min <= max && !isNaN(sum)) || (isNaN(min) && isNaN(max) && isNaN(sum))}</li>
91 * </ul>
92 * @apiNote
93 * The enforcement of argument correctness means that the retrieved set of
94 * recorded values obtained from a {@code DoubleSummaryStatistics} source
95 * instance may not be a legal set of arguments for this constructor due to
96 * arithmetic overflow of the source's recorded count of values.
97 * The consistent argument conditions are not sufficient to prevent the
98 * creation of an internally inconsistent instance. An example of such a
99 * state would be an instance with: {@code count} = 2, {@code min} = 1,
100 * {@code max} = 2, and {@code sum} = 0.
101 *
102 * @param count the count of values
103 * @param min the minimum value
104 * @param max the maximum value
105 * @param sum the sum of all values
106 * @throws IllegalArgumentException if the arguments are inconsistent
107 * @since 10
108 */
109 public DoubleSummaryStatistics(long count, double min, double max, double sum)
110 throws IllegalArgumentException {
111 if (count < 0L) {
112 throw new IllegalArgumentException("Negative count value");
113 } else if (count > 0L) {
114 if (min > max)
115 throw new IllegalArgumentException("Minimum greater than maximum");
116
117 // All NaN or non NaN
118 var ncount = DoubleStream.of(min, max, sum).filter(Double::isNaN).count();
119 if (ncount > 0 && ncount < 3)
120 throw new IllegalArgumentException("Some, not all, of the minimum, maximum, or sum is NaN");
121
122 this.count = count;
123 this.sum = sum;
124 this.simpleSum = sum;
125 this.sumCompensation = 0.0d;
126 this.min = min;
127 this.max = max;
128 }
129 // Use default field values if count == 0
130 }
131
132 /**
133 * Records another value into the summary information.
134 *
135 * @param value the input value
136 */
137 @Override
138 public void accept(double value) {
139 ++count;
140 simpleSum += value;
141 sumWithCompensation(value);
142 min = Math.min(min, value);
143 max = Math.max(max, value);
144 }
145
146 /**
147 * Combines the state of another {@code DoubleSummaryStatistics} into this
148 * one.
149 *
150 * @param other another {@code DoubleSummaryStatistics}
151 * @throws NullPointerException if {@code other} is null
152 */
153 public void combine(DoubleSummaryStatistics other) {
154 count += other.count;
155 simpleSum += other.simpleSum;
156 sumWithCompensation(other.sum);
157 sumWithCompensation(other.sumCompensation);
158 min = Math.min(min, other.min);
159 max = Math.max(max, other.max);
160 }
161
162 /**
163 * Incorporate a new double value using Kahan summation /
164 * compensated summation.
165 */
166 private void sumWithCompensation(double value) {
167 double tmp = value - sumCompensation;
168 double velvel = sum + tmp; // Little wolf of rounding error
169 sumCompensation = (velvel - sum) - tmp;
170 sum = velvel;
171 }
172
173 /**
174 * Return the count of values recorded.
175 *
176 * @return the count of values
177 */
178 public final long getCount() {
179 return count;
180 }
181
182 /**
183 * Returns the sum of values recorded, or zero if no values have been
184 * recorded.
185 *
186 * <p> The value of a floating-point sum is a function both of the
187 * input values as well as the order of addition operations. The
188 * order of addition operations of this method is intentionally
189 * not defined to allow for implementation flexibility to improve
190 * the speed and accuracy of the computed result.
191 *
192 * In particular, this method may be implemented using compensated
193 * summation or other technique to reduce the error bound in the
194 * numerical sum compared to a simple summation of {@code double}
195 * values.
196 *
197 * Because of the unspecified order of operations and the
198 * possibility of using differing summation schemes, the output of
199 * this method may vary on the same input values.
200 *
201 * <p>Various conditions can result in a non-finite sum being
202 * computed. This can occur even if the all the recorded values
203 * being summed are finite. If any recorded value is non-finite,
204 * the sum will be non-finite:
205 *
206 * <ul>
207 *
208 * <li>If any recorded value is a NaN, then the final sum will be
209 * NaN.
210 *
211 * <li>If the recorded values contain one or more infinities, the
212 * sum will be infinite or NaN.
213 *
214 * <ul>
215 *
216 * <li>If the recorded values contain infinities of opposite sign,
217 * the sum will be NaN.
218 *
219 * <li>If the recorded values contain infinities of one sign and
220 * an intermediate sum overflows to an infinity of the opposite
221 * sign, the sum may be NaN.
222 *
223 * </ul>
224 *
225 * </ul>
226 *
227 * It is possible for intermediate sums of finite values to
228 * overflow into opposite-signed infinities; if that occurs, the
229 * final sum will be NaN even if the recorded values are all
230 * finite.
231 *
232 * If all the recorded values are zero, the sign of zero is
233 * <em>not</em> guaranteed to be preserved in the final sum.
234 *
235 * @apiNote Values sorted by increasing absolute magnitude tend to yield
236 * more accurate results.
237 *
238 * @return the sum of values, or zero if none
239 */
240 public final double getSum() {
241 // Better error bounds to add both terms as the final sum
242 double tmp = sum + sumCompensation;
243 if (Double.isNaN(tmp) && Double.isInfinite(simpleSum))
244 // If the compensated sum is spuriously NaN from
245 // accumulating one or more same-signed infinite values,
246 // return the correctly-signed infinity stored in
247 // simpleSum.
248 return simpleSum;
249 else
250 return tmp;
251 }
252
253 /**
254 * Returns the minimum recorded value, {@code Double.NaN} if any recorded
255 * value was NaN or {@code Double.POSITIVE_INFINITY} if no values were
256 * recorded. Unlike the numerical comparison operators, this method
257 * considers negative zero to be strictly smaller than positive zero.
258 *
259 * @return the minimum recorded value, {@code Double.NaN} if any recorded
260 * value was NaN or {@code Double.POSITIVE_INFINITY} if no values were
261 * recorded
262 */
263 public final double getMin() {
264 return min;
265 }
266
267 /**
268 * Returns the maximum recorded value, {@code Double.NaN} if any recorded
269 * value was NaN or {@code Double.NEGATIVE_INFINITY} if no values were
270 * recorded. Unlike the numerical comparison operators, this method
271 * considers negative zero to be strictly smaller than positive zero.
272 *
273 * @return the maximum recorded value, {@code Double.NaN} if any recorded
274 * value was NaN or {@code Double.NEGATIVE_INFINITY} if no values were
275 * recorded
276 */
277 public final double getMax() {
278 return max;
279 }
280
281 /**
282 * Returns the arithmetic mean of values recorded, or zero if no
283 * values have been recorded.
284 *
285 * <p> The computed average can vary numerically and have the
286 * special case behavior as computing the sum; see {@link #getSum}
287 * for details.
288 *
289 * @apiNote Values sorted by increasing absolute magnitude tend to yield
290 * more accurate results.
291 *
292 * @return the arithmetic mean of values, or zero if none
293 */
294 public final double getAverage() {
295 return getCount() > 0 ? getSum() / getCount() : 0.0d;
296 }
297
298 /**
299 * Returns a non-empty string representation of this object suitable for
300 * debugging. The exact presentation format is unspecified and may vary
301 * between implementations and versions.
302 */
303 @Override
304 public String toString() {
305 return String.format(
306 "%s{count=%d, sum=%f, min=%f, average=%f, max=%f}",
307 this.getClass().getSimpleName(),
308 getCount(),
309 getSum(),
310 getMin(),
311 getAverage(),
312 getMax());
313 }
314 }