Summary

Add nthRoot() and nthRootAndRemainder() methods in class BigInteger.

Problem

The class BigInteger already provides methods pow(), sqrt() and sqrtAndRemainder() for power and square root calculation, so, for simmetry, it would be useful introducing methods to compute integer nth roots too. This feature can then be used to implement also a possible method BigDecimal.nthRoot() in a future release.

Solution

Implement nthRoot() and nthRootAndRemainder() methods in class BigInteger.

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
 */
public BigInteger nthRoot(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 #nthRoot(int)
 * @since 26
 */
public BigInteger[] nthRootAndRemainder(int n)