Summary
-------
Add a family of Math::to*Exact([long|double]) methods, as described in [JDK-8279986: methods Math::asXExact for safely checked primitive casts][1]
This also applies to StrictMath.
[1]: https://bugs.openjdk.java.net/browse/JDK-8279986
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) {
```