Details

CSR

Resolution: Approved

P4

behavioral

minimal

Java API

SE
Description
Summary
Update the floatingpoint sum and average methods for streams to explicitly state how nonfinite values are handled.
Problem
The floatingpoint sum and average methods for streams don't explicitly state how nonfinite values are handled.
Solution
Amend the relevant specifications to cover these cases.
Specification
FYI, full webrev: http://cr.openjdk.java.net/~darcy/8030942.0/
Patch below:
 old/src/share/classes/java/util/DoubleSummaryStatistics.java 20140715 17:26:41.000000000 0700
+++ new/src/share/classes/java/util/DoubleSummaryStatistics.java 20140715 17:26:41.000000000 0700
@@ 1,5 +1,5 @@
/*
 * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2014, 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
@@ 129,9 +129,6 @@
* Returns the sum of values recorded, or zero if no values have been
* recorded.
*
 * If any recorded value is a NaN or the sum is at any point a NaN
 * then the sum will be NaN.
 *
* <p> The value of a floatingpoint 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
@@ 143,6 +140,23 @@
* numerical sum compared to a simple summation of {@code double}
* values.
*
+ * <p>If any recorded value is a NaN or the intermediate sum is at
+ * any point a NaN, then the final sum will be NaN.
+ *
+ * If the recorded values contain infinities of opposite sign, the
+ * final sum will be NaN.
+ *
+ * It is possible for intermediate sums of finite values to
+ * overflow into oppositesigned infinities; if that occurs, the
+ * final sum will be NaN even if the recorded values are all
+ * finite.
+ *
+ * If the exact sum is infinite, a properlysigned infinity is
+ * returned.
+ *
+ * If all the recorded values are zero, the sign of zero is
+ * <em>not</em> guaranteed to be preserved in the final sum.
+ *
* @apiNote Values sorted by increasing absolute magnitude tend to yield
* more accurate results.
*
@@ 193,9 +207,6 @@
* Returns the arithmetic mean of values recorded, or zero if no
* values have been recorded.
*
 * If any recorded value is a NaN or the sum is at any point a NaN
 * then the average will be code NaN.
 *
* <p>The average returned can vary depending upon the order in
* which values are recorded.
*
@@ 203,6 +214,10 @@
* other technique to reduce the error bound in the {@link #getSum
* numerical sum} used to compute the average.
*
+ * <p>This method can return a NaN or infinite result in the same
+ * kind of numerical situations as {@linkplain #getSum() the sum}
+ * can be NaN or infinite, respectively.
+ *
* @apiNote Values sorted by increasing absolute magnitude tend to yield
* more accurate results.
*
 old/src/share/classes/java/util/stream/DoubleStream.java 20140715 17:26:42.000000000 0700
+++ new/src/share/classes/java/util/stream/DoubleStream.java 20140715 17:26:42.000000000 0700
@@ 1,5 +1,5 @@
/*
 * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2014, 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
@@ 470,10 +470,7 @@
* code is not necessarily equivalent to the summation computation
* done by this method.
*
 * <p>If any stream element is a NaN or the sum is at any point a NaN
 * then the sum will be NaN.
 *
 * The value of a floatingpoint sum is a function both
+ * <p>The value of a floatingpoint 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
@@ 485,6 +482,23 @@
* numerical sum compared to a simple summation of {@code double}
* values.
*
+ * <p>If any stream element is a NaN or the intermediate sum is at
+ * any point a NaN, then the final sum will be NaN.
+ *
+ * If the stream elements contain infinities of opposite sign, the
+ * final sum will be NaN.
+ *
+ * It is possible for intermediate sums of finite values to
+ * overflow into oppositesigned infinities; if that occurs, the
+ * final sum will be NaN even if the stream elements are all
+ * finite.
+ *
+ * If the exact sum is infinite, a properlysigned infinity is
+ * returned.
+ *
+ * If all the stream elements are zero, the sign of zero is
+ * <em>not</em> guaranteed to be preserved in the final sum.
+ *
* <p>This is a <a href="packagesummary.html#StreamOps">terminal
* operation</a>.
*
@@ 555,9 +569,6 @@
* mean of elements of this stream, or an empty optional if this
* stream is empty.
*
 * If any recorded value is a NaN or the sum is at any point a NaN
 * then the average will be NaN.
 *
* <p>The average returned can vary depending upon the order in
* which values are recorded.
*
@@ 565,6 +576,10 @@
* other technique to reduce the error bound in the {@link #sum
* numerical sum} used to compute the average.
*
+ * <p>This method can return a NaN or infinite result in the same
+ * kind of numerical situations as {@linkplain #sum() the sum} can
+ * be NaN or infinite, respectively.
+ *
* <p>The average is a special case of a <a
* href="packagesummary.html#Reduction">reduction</a>.
*
Attachments
Issue Links
 csr for

JDK8030942 Explicitly state floatingpoint summation requirements on nonfinite inputs
 Resolved