JDK-8364012 : BigInteger Roots
  • Type: CSR
  • Component: core-libs
  • Sub-Component: java.math
  • Priority: P4
  • Status: Closed
  • Resolution: Approved
  • Fix Versions: 26
  • Submitted: 2025-07-24
  • Updated: 2025-10-24
  • Resolved: 2025-08-29
Related Reports
CSR :  
Causes :  
Relates :  
Description
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 symmetry, 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)


Comments
Moving the CSR to Approved; left a few code review comments on the PR.
29-08-2025

[~fromano] Once you are OK with the current state of the CSR, you can switch it to "Finalized" and set the "Fix Version" to 26.
30-07-2025

[~fromano] I guess you want to follow the simpler one-phase workflow, so the status should really be "Draft". The "Proposed" status is part of the more involved two-phase workflow, which is not necessary in simple cases like this one.
30-07-2025

I'll review it later today.
30-07-2025

[~fromano] A CSR can be finalized [after being reviewed by at least one engineer familiar with that technology area][1]. I switched the status back to Draft. [1]: https://wiki.openjdk.org/display/csr/Main
30-07-2025

[~fromano] The spec of `nthRootAndRemainder()` is repeated twice, while the spec of `nthRoot()` is missing.
29-07-2025