OpenJDK / portola / portola
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>.