Summary

CSR 8364012 introduced two new API methods to BigInteger, with names nthRoot and nthRootAndRemainder.

For the nth root and for fixed sized numeric types, IEEE 754-2019 recommends a similar function named rootn instead.

It would be helpful to adhere to the IEEE 754 naming.

Problem

Even though BigInteger is not a floating-point numeric type, it would be less confusing for users accustomed to the IEEE 754 standard if the nthRoot* methods were instead named rootn*.

Solution

Since JDK 26 has not yet been officially released (there are EA builds, though), there's still time to proceed with the renaming.

Specification

/**
 * Returns the integer {@code n}th root of this BigInteger. The integer
 * {@code n}th root {@code r} of the corresponding mathematical integer {@code x}
 * is defined as follows:
 * <ul>
 *   <li>if {@code x} &ge; 0, then {@code r} &ge; 0 is the largest integer such that
 *   {@code r}<sup>{@code n}</sup> &le; {@code x};
 *   <li>if {@code x} &lt; 0, then {@code r} &le; 0 is the smallest integer such that
 *   {@code r}<sup>{@code n}</sup> &ge; {@code x}.
 * </ul>
 * If the root is defined, it is equal to the value of
 * {@code x.signum()}&sdot; &lfloor;{@code |nthRoot(x, n)|}&rfloor;,
 * where {@code nthRoot(x, n)} denotes the real {@code n}th root of {@code x}
 * treated as a real.
 * Otherwise, the method throws an {@code ArithmeticException}.
 *
 * <p>Note that the magnitude of the integer {@code n}th root will be less than
 * the magnitude of the real {@code n}th root if the latter is not representable
 * as an integral value.
 *
 * @param n the root degree
 * @return the integer {@code n}th root of {@code this}
 * @throws ArithmeticException if {@code n <= 0}.
 * @throws ArithmeticException if {@code n} is even and {@code this} is negative.
 * @see #sqrt()
 * @since 26
 * @apiNote Note that calling {@code rootn(2)} is equivalent to calling {@code sqrt()}.
 */
public BigInteger rootn(int n)

/**
 * Returns an array of two BigIntegers containing the integer {@code n}th root
 * {@code r} of {@code this} and its remainder {@code this - r}<sup>{@code n}</sup>,
 * respectively.
 *
 * @param n the root degree
 * @return an array of two BigIntegers with the integer {@code n}th root at
 *         offset 0 and the remainder at offset 1
 * @throws ArithmeticException if {@code n <= 0}.
 * @throws ArithmeticException if {@code n} is even and {@code this} is negative.
 * @see #sqrt()
 * @see #sqrtAndRemainder()
 * @see #rootn(int)
 * @since 26
 * @apiNote Note that calling {@code rootnAndRemainder(2)} is equivalent to calling
 *          {@code sqrtAndRemainder()}.
 */
public BigInteger[] rootnAndRemainder(int n)