OpenJDK / portola / portola
changeset 20758:d8845d3fb428
8024354: Explicitly permit DoubleStream.sum()/average() implementations to use higher precision summation
Reviewed-by: mduigou, briangoetz
author | darcy |
---|---|
date | Wed, 09 Oct 2013 18:31:51 -0700 |
parents | 1e9f01f43f5c |
children | 4e48d082f720 |
files | jdk/src/share/classes/java/util/DoubleSummaryStatistics.java jdk/src/share/classes/java/util/stream/DoubleStream.java |
diffstat | 2 files changed, 80 insertions(+), 30 deletions(-) [+] |
line wrap: on
line diff
--- a/jdk/src/share/classes/java/util/DoubleSummaryStatistics.java Wed Oct 09 12:13:31 2013 -0700 +++ b/jdk/src/share/classes/java/util/DoubleSummaryStatistics.java Wed Oct 09 18:31:51 2013 -0700 @@ -111,12 +111,24 @@ /** * Returns the sum of values recorded, or zero if no values have been - * recorded. The sum 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. If any recorded - * value is a {@code NaN} or the sum is at any point a {@code NaN} then the - * sum will be {@code NaN}. + * 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 + * not defined to allow for implementation flexibility to improve + * the speed and accuracy of the computed result. + * + * In particular, 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. + * + * @apiNote Sorting values by increasing absolute magnitude tends to yield + * more accurate results. * * @return the sum of values, or zero if none */ @@ -153,13 +165,21 @@ } /** - * Returns the arithmetic mean of values recorded, or zero if no values have been - * recorded. 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. If any recorded - * value is a {@code NaN} or the sum is at any point a {@code NaN} then the - * average will be {@code NaN}. + * 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. + * + * @apiNote Values sorted by increasing absolute magnitude tend to yield + * more accurate results. * * @return the arithmetic mean of values, or zero if none */
--- a/jdk/src/share/classes/java/util/stream/DoubleStream.java Wed Oct 09 12:13:31 2013 -0700 +++ b/jdk/src/share/classes/java/util/stream/DoubleStream.java Wed Oct 09 18:31:51 2013 -0700 @@ -502,22 +502,42 @@ BiConsumer<R, R> combiner); /** - * Returns the sum of elements in this stream. The sum returned can vary - * depending upon the order in which elements are encountered. This is due - * to accumulated rounding error in addition of values of differing - * magnitudes. Elements sorted by increasing absolute magnitude tend to - * yield more accurate results. If any stream element is a {@code NaN} or - * the sum is at any point a {@code NaN} then the sum will be {@code NaN}. - * This is a special case of a - * <a href="package-summary.html#Reduction">reduction</a> and is + * Returns the sum of elements in this stream. + * + * Summation is a special case of a <a + * href="package-summary.html#Reduction">reduction</a>. If + * floating-point summation were exact, this method would be * equivalent to: + * * <pre>{@code * return reduce(0, Double::sum); * }</pre> * + * However, since floating-point summation is not exact, the above + * 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 + * 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 + * flexibility to improve the speed and accuracy of the computed + * result. + * + * In particular, 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. + * * <p>This is a <a href="package-summary.html#StreamOps">terminal * operation</a>. * + * @apiNote Sorting values by increasing absolute magnitude tends to yield + * more accurate results. + * * @return the sum of elements in this stream */ double sum(); @@ -578,19 +598,29 @@ long count(); /** - * Returns an {@code OptionalDouble} describing the arithmetic mean of elements of - * this stream, or an empty optional if this stream is empty. The average - * returned can vary depending upon the order in which elements are - * encountered. This is due to accumulated rounding error in addition of - * elements of differing magnitudes. Elements sorted by increasing absolute - * magnitude tend to yield more accurate results. If any recorded value is - * a {@code NaN} or the sum is at any point a {@code NaN} then the average - * will be {@code NaN}. This is a special case of a - * <a href="package-summary.html#Reduction">reduction</a>. + * Returns an {@code OptionalDouble} describing the arithmetic + * 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 average is a special case of a <a + * href="package-summary.html#Reduction">reduction</a>. * * <p>This is a <a href="package-summary.html#StreamOps">terminal * operation</a>. * + * @apiNote Elements sorted by increasing absolute magnitude tend + * to yield more accurate results. + * * @return an {@code OptionalDouble} containing the average element of this * stream, or an empty optional if the stream is empty */