Uploaded image for project: 'CCC Migration Project'
  1. CCC Migration Project
  2. CCC-8030942

Explicitly state floating-point summation requirements on non-finite inputs

    XMLWordPrintable

    Details

    • Subcomponent:
    • Compatibility Kind:
      behavioral
    • Compatibility Risk:
      minimal
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      Summary

      Update the floating-point sum and average methods for streams to explicitly state how non-finite values are handled.

      Problem

      The floating-point sum and average methods for streams don't explicitly state how non-finite values are handled.

      Solution

      Amend the relevant specifications to cover these cases.

      Specification

      FYI, full webrev: http://cr.openjdk.java.net/~darcy/8030942.0/
      
      Patch below:
      
      --- old/src/share/classes/java/util/DoubleSummaryStatistics.java        2014-07-15 17:26:41.000000000 -0700
      +++ new/src/share/classes/java/util/DoubleSummaryStatistics.java        2014-07-15 17:26:41.000000000 -0700
      @@ -1,5 +1,5 @@
       /*
      - * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
      + * 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
      @@ -129,9 +129,6 @@
            * Returns the sum 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 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
      @@ -143,6 +140,23 @@
            * numerical sum compared to a simple summation of {@code double}
            * values.
            *
      +     * <p>If any recorded value is a NaN or the intermediate sum is at
      +     * any point a NaN, then the final sum will be NaN.
      +     *
      +     * If the recorded values 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 recorded values are all
      +     * finite.
      +     *
      +     * If the exact sum is infinite, a properly-signed infinity is
      +     * returned.
      +     *
      +     * If all the recorded values are zero, the sign of zero is
      +     * <em>not</em> guaranteed to be preserved in the final sum.
      +     *
            * @apiNote Values sorted by increasing absolute magnitude tend to yield
            * more accurate results.
            *
      @@ -193,9 +207,6 @@
            * 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.
            *
      @@ -203,6 +214,10 @@
            * other technique to reduce the error bound in the {@link #getSum
            * 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 #getSum() the sum}
      +     * can be NaN or infinite, respectively.
      +     *
            * @apiNote Values sorted by increasing absolute magnitude tend to yield
            * more accurate results.
            *
      --- old/src/share/classes/java/util/stream/DoubleStream.java    2014-07-15 17:26:42.000000000 -0700
      +++ new/src/share/classes/java/util/stream/DoubleStream.java    2014-07-15 17:26:42.000000000 -0700
      @@ -1,5 +1,5 @@
       /*
      - * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
      + * 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
      @@ -470,10 +470,7 @@
            * 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
      +     * <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
      @@ -485,6 +482,23 @@
            * 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>.
            *
      @@ -555,9 +569,6 @@
            * 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.
            *
      @@ -565,6 +576,10 @@
            * 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>.
            *

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              darcy Joe Darcy
              Reporter:
              darcy Joe Darcy
              Reviewed By:
              Georgiy Rakov (Inactive)
              Votes:
              0 Vote for this issue
              Watchers:
              0 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: