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

Add decrementExact(), incrementExact(), and negateExact() to java.lang.StrictMath

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Approved
    • Fix Version/s: 14
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      There is no compatibility risk as this proposal adds new static methods to java.lang.StrictMath.
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      Summary

      Retroactively add decrementExact(), incrementExact(), and negateExact() to java.lang.StrictMath.

      Problem

      The methods decrementExact(), incrementExact(), and negateExact() were previously added to java.lang.Math, see JDK-8022109. For consistency, they should have been added to java.lang.StrictMath as well. The class-level javadoc will also need to be adjusted as per JDK-8229337.

      Solution

      1. Add the three methods mentioned to java.lang.StrictMath.
      2. Add the methods to the list of methods that can detect overflow in the class-level javadoc.

      Specification

      src/java.base/share/classes/java/lang/StrictMath.java:
      
        * 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.
      
      ...
      
      +    /**
      +     * Returns the argument incremented by one,
      +     * throwing an exception if the result overflows an {@code int}.
      +     *
      +     * @param a the value to increment
      +     * @return the result
      +     * @throws ArithmeticException if the result overflows an int
      +     * @see Math#incrementExact(int)
      +     * @since 14
      +     */
      +    public static int incrementExact(int a) {
      +        return Math.incrementExact(a);
      +    }
      +
      +    /**
      +     * Returns the argument incremented by one,
      +     * throwing an exception if the result overflows a {@code long}.
      +     *
      +     * @param a the value to increment
      +     * @return the result
      +     * @throws ArithmeticException if the result overflows a long
      +     * @see Math#incrementExact(long)
      +     * @since 14
      +     */
      +    public static long incrementExact(long a) {
      +        return Math.incrementExact(a);
      +    }
      +
      +    /**
      +     * Returns the argument decremented by one,
      +     * throwing an exception if the result overflows an {@code int}.
      +     *
      +     * @param a the value to decrement
      +     * @return the result
      +     * @throws ArithmeticException if the result overflows an int
      +     * @see Math#decrementExact(int)
      +     * @since 14
      +     */
      +    public static int decrementExact(int a) {
      +        return Math.decrementExact(a);
      +    }
      +
      +    /**
      +     * Returns the argument decremented by one,
      +     * throwing an exception if the result overflows a {@code long}.
      +     *
      +     * @param a the value to decrement
      +     * @return the result
      +     * @throws ArithmeticException if the result overflows a long
      +     * @see Math#decrementExact(long)
      +     * @since 14
      +     */
      +    public static long decrementExact(long a) {
      +        return Math.decrementExact(a);
      +    }
      +
      +    /**
      +     * Returns the negation of the argument,
      +     * throwing an exception if the result overflows an {@code int}.
      +     *
      +     * @param a the value to negate
      +     * @return the result
      +     * @throws ArithmeticException if the result overflows an int
      +     * @see Math#negateExact(int)
      +     * @since 14
      +     */
      +    public static int negateExact(int a) {
      +        return Math.negateExact(a);
      +    }
      +
      +    /**
      +     * Returns the negation of the argument,
      +     * throwing an exception if the result overflows a {@code long}.
      +     *
      +     * @param a the value to negate
      +     * @return the result
      +     * @throws ArithmeticException if the result overflows a long
      +     * @see Math#negateExact(long)
      +     * @since 14
      +     */
      +    public static long negateExact(long a) {
      +        return Math.negateExact(a);
      +    }
      +
           /**
      -     * Returns the value of the {@code long} argument;
      -     * throwing an exception if the value overflows an {@code int}.
      +     * Returns the value of the {@code long} argument, throwing an exception
      +     * if the value overflows an {@code int}.

        Attachments

          Issue Links

            Activity

              People

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

                Dates

                Created:
                Updated:
                Resolved: