This seems to contradict the main documentation for these methods. Perhaps
instead we should remove the "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." into an @implNote?
I also suspect that having this documentation only in DoubleSummaryStatistics
may be too hidden away. Perhaps similar docs on DoubleStream sum() and
average() methods as well?
Mike
On Oct 8 2013, at 18:56 , Joe Darcy wrote:
> Hello,
>
> Please review the patch below which addresses
>
> JDK-8024354 Explicitly permit DoubleStream.sum()/average()
> implementations to use higher precision summation
>
> Thanks,
>
> -Joe
>
> diff -r f1e31376f419 src/share/classes/java/util/DoubleSummaryStatistics.java
> --- a/src/share/classes/java/util/DoubleSummaryStatistics.java Wed Oct 09
> 00:10:02 2013 +0100
> +++ b/src/share/classes/java/util/DoubleSummaryStatistics.java Tue Oct 08
> 18:54:55 2013 -0700
> @@ -118,6 +118,11 @@
> * value is a {@code NaN} or the sum is at any point a {@code NaN} then
> the
> * sum will be {@code NaN}.
> *
> + * @implNote 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.
> + *
> * @return the sum of values, or zero if none
> */
> public final double getSum() {
> @@ -161,6 +166,10 @@
> * value is a {@code NaN} or the sum is at any point a {@code NaN} then
> the
> * average will be {@code NaN}.
> *
> + * @implNote This method may be implemented using compensated
> + * summation or other technique to reduce the error bound in the
> + * numerical sum used to compute the average.
> + *
> * @return the arithmetic mean of values, or zero if none
> */
> public final double getAverage() {
>
