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

Wed Jul 16 00:29:46 UTC 2014

JDK-8030942: Explicitly state floating-point summation requirements 
* 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
* If any recorded value is a NaN or the intermediate sum is at
* any point a NaN, then the final sum will be NaN.
*
* If the recorded values contain infinities of opposite sign, the
* final sum will be NaN.
*
* 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 the exact sum is infinite, a properly-signed infinity is
* returned.
*
* 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 can return a NaN or infinite result in the same
* kind of numerical situations as {@linkplain #getSum() the sum}
* can be NaN or infinite, respectively.
*
 * @apiNote Values sorted by increasing absolute magnitude tend to
* 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
* If any stream element is a NaN or the intermediate sum is at
* any point a NaN, then the final sum will be NaN.
*
* If the stream elements contain infinities of opposite sign, the
* final sum will be NaN.
*
* 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 stream elements are all
* finite.
*
* If the exact sum is infinite, a properly-signed infinity is
* returned.
*
* If all the stream elements are zero, the sign of zero is
* not guaranteed to be preserved in the final sum.
*
 * This is a <a href="package-summary.html#StreamOps">terminal
 * operation</a>.
 *
* If any recorded value is a NaN or the sum is at any point a NaN
* then the average will be NaN.
*
 * The average returned can vary depending upon the order in
 * which values are recorded.
 *
* This method can return a NaN or infinite result in the same
* kind of numerical situations as {@linkplain #sum() the sum} can
* be NaN or infinite, respectively.
*
 * The average is a special case of a <a
 * href="package-summary.html#Reduction">reduction</a>.
 *