infernap12/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2026-05-23 03:48:13 +00:00
Code Issues Packages Projects Releases Wiki Activity

8024354: Explicitly permit DoubleStream.sum()/average() implementations to use higher precision summation

Browse Source 
Reviewed-by: mduigou, briangoetz
This commit is contained in:
Joe Darcy 2013-10-09 18:31:51 -07:00
parent 5edd3cbdfe
commit e9ef833478
2 changed files with 80 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
jdk/src/share/classes/java/util/DoubleSummaryStatistics.java
View File

@ -111,12 +111,24 @@ public class DoubleSummaryStatistics implements DoubleConsumer {
/**
* 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 @@ public class DoubleSummaryStatistics implements DoubleConsumer {
}
/**
* 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
*/

64
jdk/src/share/classes/java/util/stream/DoubleStream.java
View File

@ -502,22 +502,42 @@ public interface DoubleStream extends BaseStream<Double, DoubleStream> {
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 @@ public interface DoubleStream extends BaseStream<Double, DoubleStream> {
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
*/