diff --git a/jdk/src/share/classes/java/util/DoubleSummaryStatistics.java b/jdk/src/share/classes/java/util/DoubleSummaryStatistics.java index 569c35899bc..ab5f59d8a65 100644 --- a/jdk/src/share/classes/java/util/DoubleSummaryStatistics.java +++ b/jdk/src/share/classes/java/util/DoubleSummaryStatistics.java @@ -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 @@ public class DoubleSummaryStatistics implements DoubleConsumer { * 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. - * *
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 @@ -143,6 +140,44 @@ public class DoubleSummaryStatistics implements DoubleConsumer { * numerical sum compared to a simple summation of {@code double} * values. * + * Because of the unspecified order of operations and the + * possibility of using differing summation schemes, the output of + * this method may vary on the same input values. + * + *
Various conditions can result in a non-finite sum being + * computed. This can occur even if the all the recorded values + * being summed are finite. If any recorded value is non-finite, + * the sum will be non-finite: + * + *
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. + *
The computed average can vary numerically and have the
+ * special case behavior as computing the sum; see {@link #getSum}
+ * for details.
*
* @apiNote Values sorted by increasing absolute magnitude tend to yield
* more accurate results.
diff --git a/jdk/src/share/classes/java/util/stream/DoubleStream.java b/jdk/src/share/classes/java/util/stream/DoubleStream.java
index cfc12ffde28..08b4eeda304 100644
--- a/jdk/src/share/classes/java/util/stream/DoubleStream.java
+++ b/jdk/src/share/classes/java/util/stream/DoubleStream.java
@@ -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 @@ public interface DoubleStream extends BaseStream 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
+ * 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
@@ -485,6 +482,44 @@ public interface DoubleStream extends BaseStream Various conditions can result in a non-finite sum being
+ * computed. This can occur even if the all the elements
+ * being summed are finite. If any element is non-finite,
+ * the sum will be non-finite:
+ *
+ * This is a terminal
* operation.
*
@@ -555,15 +590,9 @@ public interface DoubleStream extends BaseStream 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 computed average can vary numerically and have the
+ * special case behavior as computing the sum; see {@link #sum}
+ * for details.
*
* The average is a special case of a reduction.
+ *
+ *
+ *
+ * It is possible for intermediate sums of finite values to
+ * overflow into opposite-signed infinities; if that occurs, the
+ * final sum will be NaN even if the elements are all
+ * finite.
+ *
+ * If all the elements are zero, the sign of zero is
+ * not guaranteed to be preserved in the final sum.
+ *
*
+ *
+ *
+ *
+ *