|
CSR :
|
|
|
Causes :
|
|
|
Relates :
|
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} ≥ 0, then {@code r} ≥ 0 is the largest integer such that
* {@code r}<sup>{@code n}</sup> ≤ {@code x};
* <li>if {@code x} < 0, then {@code r} ≤ 0 is the smallest integer such that
* {@code r}<sup>{@code n}</sup> ≥ {@code x}.
* </ul>
* If the root is defined, it is equal to the value of
* {@code x.signum()}⋅ ⌊{@code |nthRoot(x, n)|}⌋,
* 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)
|