Summary

Add a family of Math::to*Exact([long|double]) methods, as described in JDK-8279986: methods Math::asXExact for safely checked primitive casts

This also applies to StrictMath.

Specification

Both java.lang.Math and java.lang.StrictMath are extended with the new API points below.

Note that the spec for toIntExact(long) has not changed, except for minor typographical corrections.

    /**
     * Returns the value of the {@code long} argument,
     * throwing an exception if the value overflows an {@code int}.
     *
     * @param value the {@code long} value
     * @return the argument as an {@code int}
     * @throws ArithmeticException if the argument overflows an {@code int}
     * @since 1.8
     */
    public static int toIntExact(long value) {

    /**
     * Returns the value of the {@code double} argument,
     * throwing an exception if the conversion is inexact.
     * The method returns if and only if the argument and the result
     * are mathematically equal.
     *
     * <p>Special cases:
     * <ul>
     * <li>If the argument is {@link Double#NEGATIVE_INFINITY},
     * {@link Double#POSITIVE_INFINITY} or {@link Double#NaN},
     * the method throws.
     * <li>If the argument is {@code -0.0} or {@code 0.0},
     * the method returns {@code 0}.
     * </ul>
     *
     * @param value the {@code double} value
     * @return the argument as a {@code int}
     * @throws ArithmeticException if the conversion is inexact
     * @see Math#rint(double)
     * @see Math#round(double)
     * @since 19
     */
    public static int toIntExact(double value) {

    /**
     * Returns the value of the {@code long} argument,
     * throwing an exception if the value overflows a {@code short}.
     *
     * @param value the {@code long} value
     * @return the argument as a {@code short}
     * @throws ArithmeticException if the argument overflows a {@code short}
     * @since 19
     */
    public static short toShortExact(long value) {

    /**
     * Returns the value of the {@code long} argument,
     * throwing an exception if the value overflows a {@code byte}.
     *
     * @param value the {@code long} value
     * @return the argument as a {@code byte}
     * @throws ArithmeticException if the argument overflows a {@code byte}
     * @since 19
     */
    public static byte toByteExact(long value) {

    /**
     * Returns the value of the {@code long} argument,
     * throwing an exception if the conversion is inexact.
     * The method returns if and only if the argument and the result
     * are mathematically equal.
     *
     * <p>Special case:
     * <ul>
     * <li>If the argument is {@code 0L}, the method returns {@code 0.0f}.
     * </ul>
     *
     * @param value the {@code long} value
     * @return the argument as a {@code float}
     * @throws ArithmeticException if the conversion is inexact
     * @since 19
     */
    public static float toFloatExact(long value) {

    /**
     * Returns the value of the {@code double} argument,
     * throwing an exception if the conversion is inexact.
     * The method returns if and only if the argument and the result
     * are mathematically equal.
     *
     * <p>Special cases:
     * <ul>
     * <li>If the argument is {@link Double#NEGATIVE_INFINITY},
     * {@link Double#POSITIVE_INFINITY}, {@link Double#NaN},
     * {@code -0.0} or {@code 0.0},
     * the method returns {@link Float#NEGATIVE_INFINITY},
     * {@link Float#POSITIVE_INFINITY}, {@link Float#NaN},
     * {@code -0.0f} or {@code 0.0f}, respectively.
     * </ul>
     *
     * @param value the {@code double} value
     * @return the argument as a {@code float}
     * @throws ArithmeticException if the conversion is inexact
     * @since 19
     */
    public static float toFloatExact(double value) {

    /**
     * Returns the value of the {@code long} argument,
     * throwing an exception if the conversion is inexact.
     * The method returns if and only if the argument and the result
     * are mathematically equal.
     *
     * <p>Special case:
     * <ul>
     * <li>If the argument is {@code 0L}, the method returns {@code 0.0}.
     * </ul>
     *
     * @param value the {@code long} value
     * @return the argument as a {@code double}
     * @throws ArithmeticException if the conversion is inexact
     * @since 19
     */
    public static double toDoubleExact(long value) {

    /**
     * Returns the value of the {@code double} argument,
     * throwing an exception if the conversion is inexact.
     * The method returns if and only if the argument and the result
     * are mathematically equal.
     *
     * <p>Special cases:
     * <ul>
     * <li>If the argument is {@link Double#NEGATIVE_INFINITY},
     * {@link Double#POSITIVE_INFINITY} or {@link Double#NaN},
     * the method throws.
     * <li>If the argument is {@code -0.0} or {@code 0.0},
     * the method returns {@code 0L}.
     * </ul>
     *
     * @param value the {@code double} value
     * @return the argument as a {@code long}
     * @throws ArithmeticException if the conversion is inexact
     * @see Math#rint(double)
     * @see Math#round(double)
     * @since 19
     */
    public static long toLongExact(double value) {

    /**
     * Returns the value of the {@code long} argument,
     * throwing an exception if the value overflows the range
     * [0, 2<sup>{@link Integer#SIZE}</sup>) of an unsigned int.
     *
     * @param value the {@code long} value
     * @return the argument as an unsigned int
     * @throws ArithmeticException if the argument overflows an unsigned int
     * @since 19
     */
    public static long toUnsignedIntRangeExact(long value) {

    /**
     * Returns the value of the {@code long} argument,
     * throwing an exception if the value overflows the range
     * [0, 2<sup>{@link Short#SIZE}</sup>) of an unsigned short.
     *
     * @param value the {@code long} value
     * @return the argument as an unsigned short
     * @throws ArithmeticException if the argument overflows an unsigned short
     * @since 19
     */
    public static int toUnsignedShortRangeExact(long value) {

    /**
     * Returns the value of the {@code long} argument,
     * throwing an exception if the value overflows the range
     * [0, 2<sup>{@link Byte#SIZE}</sup>) of an unsigned byte.
     *
     * @param value the {@code long} value
     * @return the argument as an unsigned byte
     * @throws ArithmeticException if the argument overflows an unsigned byte
     * @since 19
     */
    public static int toUnsignedByteRangeExact(long value) {