changeset 7777:ed04983cbf86

More javadoc about NaN conditions and overflow.
author mduigou
date Fri, 29 Mar 2013 12:04:58 -0700
parents 9335e621253a
children 7e60beae75ad
files src/share/classes/java/util/DoubleSummaryStatistics.java src/share/classes/java/util/IntSummaryStatistics.java src/share/classes/java/util/LongSummaryStatistics.java
diffstat 3 files changed, 17 insertions(+), 8 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/java/util/DoubleSummaryStatistics.java	Fri Mar 29 21:57:00 2013 +0100
+++ b/src/share/classes/java/util/DoubleSummaryStatistics.java	Fri Mar 29 12:04:58 2013 -0700
@@ -83,7 +83,9 @@
      * 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.
+     * 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}.
      *
      * @return The sum of values, or zero if none
      */
@@ -96,7 +98,9 @@
      * 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.
+     * 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 of squares will be {@code NaN}.
      *
      * @return The sum of the squares of the values, or zero if none
      */
@@ -122,9 +126,9 @@
     /**
      * Returns the recorded value closest to {@code Double.POSITIVE_INFINITY},
      * {@code Double.NEGATIVE_INFINITY} if no values have been recorded or if
-     * any recorded value is NaN, then the result is NaN.  Unlike the numerical
-     * comparison operators, this method considers negative zero to be strictly
-     * smaller than positive zero.
+     * any recorded value is {@code NaN}, then the result is {@code NaN}.
+     * Unlike the numerical comparison operators, this method considers negative
+     * zero to be strictly smaller than positive zero.
      *
      * @return The maximal recorded value, {@code Double.NaN} if any recorded
      * value was NaN or {@code Double.NEGATIVE_INFINITY} if no values were
@@ -139,7 +143,9 @@
      * 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.
+     * 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}.
      *
      * @return The average of values, or zero if none
      */
--- a/src/share/classes/java/util/IntSummaryStatistics.java	Fri Mar 29 21:57:00 2013 +0100
+++ b/src/share/classes/java/util/IntSummaryStatistics.java	Fri Mar 29 12:04:58 2013 -0700
@@ -32,7 +32,9 @@
  * internally for count, sum and sum of squares which reduces the chance of
  * overflow.
  *
- * @implNote This implementation is not thread safe.
+ * @implNote This implementation is not thread safe. This implementation does
+ * not check for overflow of the sum or sum of squares.
+ *
  * @since 1.8
  */
 public class IntSummaryStatistics implements IntConsumer {
--- a/src/share/classes/java/util/LongSummaryStatistics.java	Fri Mar 29 21:57:00 2013 +0100
+++ b/src/share/classes/java/util/LongSummaryStatistics.java	Fri Mar 29 12:04:58 2013 -0700
@@ -31,7 +31,8 @@
  * A state object for collecting statistics such as count, min, max, sum, sum of
  * squares, and average for {@code long} values.
  *
- * @implNote This implementation is not thread safe.
+ * @implNote This implementation is not thread safe.  This implementation does
+ * not check for overflow of the sum or sum of squares.
  * @since 1.8
  */
 public class LongSummaryStatistics implements LongConsumer, IntConsumer {