Summary
Add unsignedMultiplyExact
, powExact()
, and unsignedPowExact()
methods that operate on integer valued arguments to classes Math and StrictMath, and that throw on overflow.
Problem
Class Math (and StrictMath) do not expose powExact()
and unsignedPowExact()
methods that operate on integer valued arguments.
Similar methods are often implemented in ad-hoc ways, without checking for overflows. Thus, they silently return incorrect values, leading to the usual issues associated with overflowing arithmetic.
The proposed methods provide a safe alternative.
The implementation of the unsignedPowExact()
methods would benefit from the presence of unsignedMultiplyExact
methods.
Solution
Implement efficient powExact()
and unsignedPowExact()
methods.
In addition, implement unsignedMultiplyExact
methods that mimic the existing signed multiplyExact
methods.
Specification
+ /**
+ * Returns the product of the unsigned arguments,
+ * throwing an exception if the result overflows an unsigned {@code int}.
+ *
+ * @param x the first unsigned value
+ * @param y the second unsigned value
+ * @return the result
+ * @throws ArithmeticException if the result overflows an unsigned int
+ * @since 25
+ */
+ public static int unsignedMultiplyExact(int x, int y) {
+
+ /**
+ * Returns the product of the unsigned arguments,
+ * throwing an exception if the result overflows an unsigned {@code long}.
+ *
+ * @param x the first unsigned value
+ * @param y the second unsigned value
+ * @return the result
+ * @throws ArithmeticException if the result overflows an unsigned long
+ * @since 25
+ */
+ public static long unsignedMultiplyExact(long x, int y) {
+
+ /**
+ * Returns the product of the unsigned arguments,
+ * throwing an exception if the result overflows an unsigned {@code long}.
+ *
+ * @param x the first unsigned value
+ * @param y the second unsigned value
+ * @return the result
+ * @throws ArithmeticException if the result overflows an unsigned long
+ * @since 25
+ */
+ public static long unsignedMultiplyExact(long x, long y) {
+
+ /**
+ * Returns {@code x} raised to the power of {@code n},
+ * throwing an exception if the result overflows an {@code int}.
+ * When {@code n} is 0, the returned value is 1.
+ *
+ * @param x the base.
+ * @param n the exponent.
+ * @return {@code x} raised to the power of {@code n}.
+ * @throws ArithmeticException when {@code n} is negative,
+ * or when the result overflows an int.
+ * @since 25
+ */
+ public static int powExact(int x, int n) {
+
+ /**
+ * Returns unsigned {@code x} raised to the power of {@code n},
+ * throwing an exception if the result overflows an unsigned {@code int}.
+ * When {@code n} is 0, the returned value is 1.
+ *
+ * @param x the unsigned base.
+ * @param n the exponent.
+ * @return {@code x} raised to the power of {@code n}.
+ * @throws ArithmeticException when {@code n} is negative,
+ * or when the result overflows an unsigned int.
+ * @since 25
+ */
+ public static int unsignedPowExact(int x, int n) {
+
+ /**
+ * Returns {@code x} raised to the power of {@code n},
+ * throwing an exception if the result overflows a {@code long}.
+ * When {@code n} is 0, the returned value is 1.
+ *
+ * @param x the base.
+ * @param n the exponent.
+ * @return {@code x} raised to the power of {@code n}.
+ * @throws ArithmeticException when {@code n} is negative,
+ * or when the result overflows a long.
+ * @since 25
+ */
+ public static long powExact(long x, int n) {
+
+ /**
+ * Returns unsigned {@code x} raised to the power of {@code n},
+ * throwing an exception if the result overflows an unsigned {@code long}.
+ * When {@code n} is 0, the returned value is 1.
+ *
+ * @param x the unsigned base.
+ * @param n the exponent.
+ * @return {@code x} raised to the power of {@code n}.
+ * @throws ArithmeticException when {@code n} is negative,
+ * or when the result overflows an unsigned long.
+ * @since 25
+ */
+ public static long unsignedPowExact(long x, int n) {
- csr of
-
JDK-8355992 Add unsignedMultiplyExact and *powExact methods to Math and StrictMath
-
- In Progress
-