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. + * + * @apiNote Sorting values by increasing absolute magnitude tends to yield + * more accurate results. * * @return the sum of values, or zero if none */ @@ -153,13 +165,21 @@ } /** - * Returns the arithmetic mean 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}. + * 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. + * + *
The average returned can vary depending upon the order in
+ * which values are recorded.
+ *
+ * This method may be implemented using compensated summation or
+ * other technique to reduce the error bound in the {@link #getSum
+ * numerical sum} used to compute the average.
+ *
+ * @apiNote Values sorted by increasing absolute magnitude tend to yield
+ * more accurate results.
*
* @return the arithmetic mean of values, or zero if none
*/
diff -r 1e9f01f43f5c -r d8845d3fb428 jdk/src/share/classes/java/util/stream/DoubleStream.java
--- a/jdk/src/share/classes/java/util/stream/DoubleStream.java Wed Oct 09 12:13:31 2013 -0700
+++ b/jdk/src/share/classes/java/util/stream/DoubleStream.java Wed Oct 09 18:31:51 2013 -0700
@@ -502,22 +502,42 @@
BiConsumer 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 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.
+ *
* This is a terminal
* operation.
*
+ * @apiNote Sorting values by increasing absolute magnitude tends to yield
+ * more accurate results.
+ *
* @return the sum of elements in this stream
*/
double sum();
@@ -578,19 +598,29 @@
long count();
/**
- * Returns an {@code OptionalDouble} describing the arithmetic mean of elements of
- * this stream, or an empty optional if this stream is empty. The average
- * returned can vary depending upon the order in which elements are
- * encountered. This is due to accumulated rounding error in addition of
- * elements of differing magnitudes. Elements 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}. This is a special case of a
- * reduction.
+ * Returns an {@code OptionalDouble} describing the arithmetic
+ * 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.
+ *
+ * The average returned can vary depending upon the order in
+ * which values are recorded.
+ *
+ * This method may be implemented using compensated summation or
+ * other technique to reduce the error bound in the {@link #sum
+ * numerical sum} used to compute the average.
+ *
+ * The average is a special case of a reduction.
*
* This is a terminal
* operation.
*
+ * @apiNote Elements sorted by increasing absolute magnitude tend
+ * to yield more accurate results.
+ *
* @return an {@code OptionalDouble} containing the average element of this
* stream, or an empty optional if the stream is empty
*/
{@code
* return reduce(0, Double::sum);
* }
*
+ * However, since floating-point summation is not exact, the above
+ * code is not necessarily equivalent to the summation computation
+ * done by this method.
+ *
+ *