src/share/classes/java/util/stream/DoubleStream.java

*** 500,525 ****
      <R> R collect(Supplier<R> supplier,
                    ObjDoubleConsumer<R> accumulator,
                    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
       * equivalent to:
       * <pre>{@code
       *     return reduce(0, Double::sum);
       * }</pre>
       *
       * <p>This is a <a href="package-summary.html#StreamOps">terminal
       * operation</a>.
       *
       * @return the sum of elements in this stream
       */
      double sum();
  
      /**
--- 500,545 ----
      <R> R collect(Supplier<R> supplier,
                    ObjDoubleConsumer<R> accumulator,
                    BiConsumer<R, R> combiner);
  
      /**
!      * 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();
  
      /**
*** 576,598 ****
       * @return the count of elements in this stream
       */
      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>.
       *
       * <p>This is a <a href="package-summary.html#StreamOps">terminal
       * operation</a>.
       *
       * @return an {@code OptionalDouble} containing the average element of this
       * stream, or an empty optional if the stream is empty
       */
      OptionalDouble average();
  
--- 596,628 ----
       * @return the count of elements in this stream
       */
      long count();
  
      /**
!      * 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
       */
      OptionalDouble average();