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

*** 1,7 ****
  /*
!  * Copyright (c) 2012, 2013, 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
   * under the terms of the GNU General Public License version 2 only, as
   * published by the Free Software Foundation.  Oracle designates this
--- 1,7 ----
  /*
!  * 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
   * under the terms of the GNU General Public License version 2 only, as
   * published by the Free Software Foundation.  Oracle designates this
*** 468,481 ****
       *
       * 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.
--- 468,478 ----
       *
       * However, since floating-point summation is not exact, the above
       * code is not necessarily equivalent to the summation computation
       * done by this method.
       *
!      * <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.
*** 483,492 ****
--- 480,506 ----
       * 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>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
+      * <em>not</em> guaranteed to be preserved in the final sum.
+      *
       * <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.
*** 553,572 ****
      /**
       * 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>.
--- 567,587 ----
      /**
       * Returns an {@code OptionalDouble} describing the arithmetic
       * mean of elements of this stream, or an empty optional if this
       * stream is empty.
       *
       * <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>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.
+      *
       *  <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>.