> In response to previous feedback, I propose this revised change to the
> specification:
>
+1
Paul.
> --- a/src/share/classes/java/util/DoubleSummaryStatistics.java Sat Jul 19
> 11:22:08 2014 +0800
> +++ b/src/share/classes/java/util/DoubleSummaryStatistics.java Mon Jul 21
> 18:02:54 2014 -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 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 @@
> * 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.
> + *
> + * <p>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:
> + *
> + * <ul>
> + *
> + * <li>If any recorded value is a NaN, then the final sum will be
> + * NaN.
> + *
> + * <li>If the recorded values contain one or more infinities, the
> + * sum will be infinite or NaN.
> + *
> + * <ul>
> + *
> + * <li>If the recorded values contain infinities of opposite sign,
> + * the sum will be NaN.
> + *
> + * <li>If the recorded values contain infinities of one sign and
> + * an intermediate sum overflows to an infinity of the opposite
> + * sign, the sum may be NaN.
> + *
> + * </ul>
> + *
> + * </ul>
> + *
> + * 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 recorded values are all
> + * finite.
> + *
> + * 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,15 +228,9 @@
> * 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.
> - *
> - * 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.
> + * <p> 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.
>
> (With analogous changes in java/util/stream/DoubleStream.java.)
>
> Thanks,
>
> -Joe
