Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8229473

java.lang.Math class doc should be adjusted regarding -Exact methods

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Approved
    • Fix Version/s: 14
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Kind:
      behavioral
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      No behavioral change. Minor consistency fix of the class-level documentation.
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      Summary

      Clarify the javadoc class summary for java.lang.Math class to indicate that the methods decrementExact(), incrementExact() and negateExact() throw an ArithmeticException when the results overflow.

      Problem

      The java.lang.Math class doc says:

       * In cases where the size is {@code int} or {@code long} and
       * overflow errors need to be detected, the methods {@code addExact},
       * {@code subtractExact}, {@code multiplyExact}, and {@code toIntExact}
       * throw an {@code ArithmeticException} when the results overflow.
       * For other arithmetic operations such as divide, absolute value,
       * increment by one, decrement by one, and negation, overflow occurs only with
       * a specific minimum or maximum value and should be checked against
       * the minimum or maximum as appropriate.

      There are methods decrementExact(), incrementExact(), and negateExact() that throw exceptions on overflow. These should be included in the list of operations that can detect overflow. The advice about checking specific values still applies to divide and absolute value operations, though.

      Solution

      Add the three methods mentioned to the list of methods that can detect an overflow.

      Specification

      --- old/src/java.base/share/classes/java/lang/Math.java 2019-08-13 10:02:14.000000000 +0100
      +++ new/src/java.base/share/classes/java/lang/Math.java 2019-08-13 10:02:14.000000000 +0100
      @@ -92,12 +92,12 @@
        * The best practice is to choose the primitive type and algorithm to avoid
        * overflow. In cases where the size is {@code int} or {@code long} and
        * overflow errors need to be detected, the methods {@code addExact},
      - * {@code subtractExact}, {@code multiplyExact}, and {@code toIntExact}
      + * {@code subtractExact}, {@code multiplyExact}, {@code toIntExact},
      + * {@code incrementExact}, {@code decrementExact} and {@code negateExact}
        * throw an {@code ArithmeticException} when the results overflow.
      - * For other arithmetic operations such as divide, absolute value,
      - * increment by one, decrement by one, and negation, overflow occurs only with
      - * a specific minimum or maximum value and should be checked against
      - * the minimum or maximum as appropriate.
      + * For the arithmetic operations divide and absolute value, overflow
      + * occurs only with a specific minimum or maximum value and
      + * should be checked against the minimum or maximum as appropriate.
        *
        * @author  unascribed
        * @author  Joseph D. Darcy

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              jboes Julia Boes
              Reporter:
              smarks Stuart Marks
              Reviewed By:
              Brian Burkhalter, Daniel Fuchs, Lance Andersen, Roger Riggs
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: