Fwd: JDK 9 RFR of JDK-8030942: Explicitly state floating-point summation requirements on non-finite inputs (original) (raw)

Tue Jul 22 03:33:23 UTC 2014

* 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
* 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:
*
* <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
* not guaranteed to be preserved in the final sum.
*
 * @apiNote Values sorted by increasing absolute magnitude tend to
* 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.
* 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