changeset 25753:b73bd85f9068

8030942: Explicitly state floating-point summation requirements on non-finite inputs Reviewed-by: psandoz
author darcy
date Mon, 28 Jul 2014 23:46:03 -0700
parents 8df7ddac1cb3
children 2fc68d1b7c03
files jdk/src/share/classes/java/util/DoubleSummaryStatistics.java jdk/src/share/classes/java/util/stream/DoubleStream.java
diffstat 2 files changed, 85 insertions(+), 27 deletions(-) [+]
line wrap: on
line diff
--- a/jdk/src/share/classes/java/util/DoubleSummaryStatistics.java	Mon Jul 28 16:24:38 2014 +0100
+++ b/jdk/src/share/classes/java/util/DoubleSummaryStatistics.java	Mon Jul 28 23:46:03 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.
--- a/jdk/src/share/classes/java/util/stream/DoubleStream.java	Mon Jul 28 16:24:38 2014 +0100
+++ b/jdk/src/share/classes/java/util/stream/DoubleStream.java	Mon Jul 28 23:46:03 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
@@ -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 floating-point sum is a function both
+     * <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 not defined to allow for implementation
@@ -485,6 +482,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 elements.
+     *
+     * <p>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:
+     *
+     * <ul>
+     *
+     * <li>If any element is a NaN, then the final sum will be
+     * NaN.
+     *
+     * <li>If the elements contain one or more infinities, the
+     * sum will be infinite or NaN.
+     *
+     * <ul>
+     *
+     * <li>If the elements contain infinities of opposite sign,
+     * the sum will be NaN.
+     *
+     * <li>If the elements 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 elements are all
+     * finite.
+     *
+     * If all the 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="package-summary.html#StreamOps">terminal
      * operation</a>.
      *
@@ -555,15 +590,9 @@
      * 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.
-     *
-     * 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.
+     * <p>The computed average can vary numerically and have the
+     * special case behavior as computing the sum; see {@link #sum}
+     * for details.
      *
      *  <p>The average is a special case of a <a
      *  href="package-summary.html#Reduction">reduction</a>.