Merge branch 'NUMBERS-40__Matt'
Closes #74.
diff --git a/commons-numbers-arrays/src/main/java/org/apache/commons/numbers/arrays/CosAngle.java b/commons-numbers-arrays/src/main/java/org/apache/commons/numbers/arrays/CosAngle.java
index dbddbbc..e728d21 100644
--- a/commons-numbers-arrays/src/main/java/org/apache/commons/numbers/arrays/CosAngle.java
+++ b/commons-numbers-arrays/src/main/java/org/apache/commons/numbers/arrays/CosAngle.java
@@ -32,6 +32,7 @@
* @param v1 Cartesian coordinates of the first vector.
* @param v2 Cartesian coordinates of the second vector.
* @return the cosine of the angle between the vectors.
+ * @throws IllegalArgumentException if the sizes of the input arrays are different
*/
public static double value(double[] v1,
double[] v2) {
diff --git a/commons-numbers-arrays/src/test/java/org/apache/commons/numbers/arrays/CosAngleTest.java b/commons-numbers-arrays/src/test/java/org/apache/commons/numbers/arrays/CosAngleTest.java
index ffef55c..758ee3f 100644
--- a/commons-numbers-arrays/src/test/java/org/apache/commons/numbers/arrays/CosAngleTest.java
+++ b/commons-numbers-arrays/src/test/java/org/apache/commons/numbers/arrays/CosAngleTest.java
@@ -23,6 +23,7 @@
* Test cases for the {@link CosAngle} class.
*/
public class CosAngleTest {
+
@Test
public void testCosAngle2D() {
double expected;
@@ -77,4 +78,14 @@
expected = 0;
Assertions.assertEquals(expected, CosAngle.value(v1, v3), 1e-15);
}
+
+ @Test
+ public void testCosAngle_dimensionMismatch() {
+ final double[] a = {1.0};
+ final double[] b = {1.0, 2.0};
+
+ Assertions.assertThrows(IllegalArgumentException.class, () -> {
+ CosAngle.value(a, b);
+ });
+ }
}
diff --git a/commons-numbers-combinatorics/src/main/java/org/apache/commons/numbers/combinatorics/BinomialCoefficient.java b/commons-numbers-combinatorics/src/main/java/org/apache/commons/numbers/combinatorics/BinomialCoefficient.java
index 801669e..d19f592 100644
--- a/commons-numbers-combinatorics/src/main/java/org/apache/commons/numbers/combinatorics/BinomialCoefficient.java
+++ b/commons-numbers-combinatorics/src/main/java/org/apache/commons/numbers/combinatorics/BinomialCoefficient.java
@@ -33,7 +33,7 @@
}
/**
- * Computes de binomial coefficient.
+ * Computes the binomial coefficient.
* The largest value of {@code n} for which all coefficients can
* fit into a {@code long} is 66.
*
diff --git a/commons-numbers-combinatorics/src/main/java/org/apache/commons/numbers/combinatorics/BinomialCoefficientDouble.java b/commons-numbers-combinatorics/src/main/java/org/apache/commons/numbers/combinatorics/BinomialCoefficientDouble.java
index b0b276e..bd95280 100644
--- a/commons-numbers-combinatorics/src/main/java/org/apache/commons/numbers/combinatorics/BinomialCoefficientDouble.java
+++ b/commons-numbers-combinatorics/src/main/java/org/apache/commons/numbers/combinatorics/BinomialCoefficientDouble.java
@@ -31,7 +31,7 @@
}
/**
- * Computes de binomial coefficient.
+ * Computes the binomial coefficient.
* The largest value of {@code n} for which all coefficients can
* fit into a {@code long} is 66.
*
@@ -40,8 +40,6 @@
* @return {@code n choose k}.
* @throws IllegalArgumentException if {@code n < 0}.
* @throws IllegalArgumentException if {@code k > n}.
- * @throws IllegalArgumentException if the result is too large to be
- * represented by a {@code long}.
*/
public static double value(int n, int k) {
BinomialCoefficient.checkBinomial(n, k);
diff --git a/commons-numbers-combinatorics/src/main/java/org/apache/commons/numbers/combinatorics/LogBinomialCoefficient.java b/commons-numbers-combinatorics/src/main/java/org/apache/commons/numbers/combinatorics/LogBinomialCoefficient.java
index d8464e4..dad945c 100644
--- a/commons-numbers-combinatorics/src/main/java/org/apache/commons/numbers/combinatorics/LogBinomialCoefficient.java
+++ b/commons-numbers-combinatorics/src/main/java/org/apache/commons/numbers/combinatorics/LogBinomialCoefficient.java
@@ -40,8 +40,6 @@
* @return {@code log(n choose k)}.
* @throws IllegalArgumentException if {@code n < 0}.
* @throws IllegalArgumentException if {@code k > n}.
- * @throws IllegalArgumentException if the result is too large to be
- * represented by a {@code long}.
*/
public static double value(int n, int k) {
BinomialCoefficient.checkBinomial(n, k);
diff --git a/commons-numbers-complex-streams/src/main/java/org/apache/commons/numbers/complex/streams/ComplexUtils.java b/commons-numbers-complex-streams/src/main/java/org/apache/commons/numbers/complex/streams/ComplexUtils.java
index fb1ea4c..fcd1975 100644
--- a/commons-numbers-complex-streams/src/main/java/org/apache/commons/numbers/complex/streams/ComplexUtils.java
+++ b/commons-numbers-complex-streams/src/main/java/org/apache/commons/numbers/complex/streams/ComplexUtils.java
@@ -57,6 +57,7 @@
* @param r the modulus of the complex number to create
* @param theta the argument of the complex number to create
* @return {@code Complex}
+ * @throws IllegalArgumentException if {@code r} is negative
*/
public static Complex polar2Complex(double r, double theta) {
if (r < 0) {
@@ -72,6 +73,7 @@
* @param r {@code double[]} of moduli
* @param theta {@code double[]} of arguments
* @return {@code Complex[]}
+ * @throws IllegalArgumentException if any element in {@code r} is negative
*/
public static Complex[] polar2Complex(double[] r, double[] theta) {
final int length = r.length;
@@ -92,6 +94,7 @@
* @param r {@code double[]} of moduli
* @param theta {@code double[]} of arguments
* @return {@code Complex[][]}
+ * @throws IllegalArgumentException if any element in {@code r} is negative
*/
public static Complex[][] polar2Complex(double[][] r, double[][] theta) {
final int length = r.length;
@@ -109,6 +112,7 @@
* @param r array of moduli
* @param theta array of arguments
* @return {@code Complex}
+ * @throws IllegalArgumentException if any element in {@code r} is negative
*/
public static Complex[][][] polar2Complex(double[][][] r, double[][][] theta) {
final int length = r.length;
@@ -220,7 +224,8 @@
* {@code index}.
*
* @param d array of interleaved complex numbers alternating real and imaginary values
- * @param index location in the array This is the location by complex number, e.g. index number 5 in the array will return {@code Complex.ofCartesian(d[10], d[11])}
+ * @param index location in the array This is the location by complex number, e.g. index number 5 in the
+ * array will return {@code Complex.ofCartesian(d[10], d[11])}
* @return {@code Complex}.
*/
public static Complex extractComplexFromInterleavedArray(double[] d, int index) {
@@ -232,7 +237,8 @@
* {@code index}.
*
* @param f float array of interleaved complex numbers alternating real and imaginary values
- * @param index location in the array This is the location by complex number, e.g. index number 5 in the {@code float[]} array will return new {@code Complex(d[10], d[11])}
+ * @param index location in the array This is the location by complex number, e.g. index number 5
+ * in the {@code float[]} array will return new {@code Complex(d[10], d[11])}
* @return {@code Complex}.
*/
public static Complex extractComplexFromInterleavedArray(float[] f, int index) {
@@ -800,6 +806,7 @@
* @param interleavedDim Depth level of the array to interleave
* @return complex interleaved array alternating real and
* imaginary values
+ * @throws IllegalArgumentException if {@code interleavedDim} is not 0 or 1
*/
public static double[][] complex2Interleaved(Complex[][] c, int interleavedDim) {
if (interleavedDim > 1 || interleavedDim < 0) {
@@ -849,6 +856,7 @@
* @param interleavedDim Depth level of the array to interleave
* @return complex interleaved array alternating real and
* imaginary values
+ * @throws IllegalArgumentException if {@code interleavedDim} is not 0, 1, or 2
*/
public static double[][][] complex2Interleaved(Complex[][][] c, int interleavedDim) {
if (interleavedDim > 2 || interleavedDim < 0) {
@@ -900,6 +908,7 @@
* @param interleavedDim Depth level of the array to interleave
* @return complex interleaved array alternating real and
* imaginary values
+ * @throws IllegalArgumentException if {@code interleavedDim} is not in the range {@code [0, 3]}
*/
public static double[][][][] complex2Interleaved(Complex[][][][] c, int interleavedDim) {
if (interleavedDim > 3 || interleavedDim < 0) {
@@ -996,6 +1005,7 @@
* @param interleavedDim Depth level of the array to interleave
* @return complex interleaved {@code float[][]} alternating real and
* imaginary values
+ * @throws IllegalArgumentException if {@code interleavedDim} is not 0 or 1
*/
public static float[][] complex2InterleavedFloat(Complex[][] c, int interleavedDim) {
if (interleavedDim > 1 || interleavedDim < 0) {
@@ -1046,6 +1056,7 @@
* @param interleavedDim Depth level of the array to interleave
* @return complex interleaved {@code float[][][]} alternating real and
* imaginary values
+ * @throws IllegalArgumentException if {@code interleavedDim} is not 0, 1, or 2
*/
public static float[][][] complex2InterleavedFloat(Complex[][][] c, int interleavedDim) {
if (interleavedDim > 2 || interleavedDim < 0) {
@@ -1110,6 +1121,7 @@
* @param i 2D complex interleaved array
* @param interleavedDim Depth level of the array to interleave
* @return 2D {@code Complex} array
+ * @throws IllegalArgumentException if {@code interleavedDim} is not 0 or 1
*/
public static Complex[][] interleaved2Complex(double[][] i, int interleavedDim) {
if (interleavedDim > 1 || interleavedDim < 0) {
@@ -1155,6 +1167,7 @@
* @param i 3D complex interleaved array
* @param interleavedDim Depth level of the array to interleave
* @return 3D {@code Complex} array
+ * @throws IllegalArgumentException if {@code interleavedDim} is not 0, 1, or 2
*/
public static Complex[][][] interleaved2Complex(double[][][] i, int interleavedDim) {
if (interleavedDim > 2 || interleavedDim < 0) {
@@ -1202,6 +1215,7 @@
* @param i 4D complex interleaved array
* @param interleavedDim Depth level of the array to interleave
* @return 4D {@code Complex} array
+ * @throws IllegalArgumentException if {@code interleavedDim} is not in the range {@code [0, 3]}
*/
public static Complex[][][][] interleaved2Complex(double[][][][] i, int interleavedDim) {
if (interleavedDim > 3 || interleavedDim < 0) {
@@ -1279,6 +1293,7 @@
* @param i 2D complex interleaved float array
* @param interleavedDim Depth level of the array to interleave
* @return 2D {@code Complex} array
+ * @throws IllegalArgumentException if {@code interleavedDim} is not 0 or 1
*/
public static Complex[][] interleaved2Complex(float[][] i, int interleavedDim) {
if (interleavedDim > 1 || interleavedDim < 0) {
@@ -1324,6 +1339,7 @@
* @param i 3D complex interleaved float array
* @param interleavedDim Depth level of the array to interleave
* @return 3D {@code Complex} array
+ * @throws IllegalArgumentException if {@code interleavedDim} is not 0, 1, or 2
*/
public static Complex[][][] interleaved2Complex(float[][][] i, int interleavedDim) {
if (interleavedDim > 2 || interleavedDim < 0) {
diff --git a/commons-numbers-fraction/src/main/java/org/apache/commons/numbers/fraction/BigFraction.java b/commons-numbers-fraction/src/main/java/org/apache/commons/numbers/fraction/BigFraction.java
index 3821496..2f9c1d0 100644
--- a/commons-numbers-fraction/src/main/java/org/apache/commons/numbers/fraction/BigFraction.java
+++ b/commons-numbers-fraction/src/main/java/org/apache/commons/numbers/fraction/BigFraction.java
@@ -337,6 +337,7 @@
* @param num the numerator.
* @param den the denominator.
* @return a new instance.
+ * @throws ArithmeticException if {@code den} is zero.
*/
public static BigFraction of(final int num, final int den) {
return new BigFraction(BigInteger.valueOf(num), BigInteger.valueOf(den));
@@ -363,6 +364,7 @@
* @param num the numerator.
* @param den the denominator.
* @return a new instance.
+ * @throws ArithmeticException if {@code den} is zero.
*/
public static BigFraction of(final long num, final long den) {
return new BigFraction(BigInteger.valueOf(num), BigInteger.valueOf(den));
@@ -511,6 +513,8 @@
* see {@link BigDecimal} for more information.
* @param roundingMode Rounding mode to apply.
* @return the fraction as a <code>BigDecimal</code>.
+ * @throws ArithmeticException if {@code roundingMode} == {@link RoundingMode#UNNECESSARY} and
+ * the specified scale is insufficient to represent the result of the division exactly.
* @see BigDecimal
*/
public BigDecimal bigDecimalValue(final int scale, RoundingMode roundingMode) {
@@ -553,7 +557,7 @@
*
* @param bg the {@code BigInteger} to divide by, must not be {@code null}
* @return a {@link BigFraction} instance with the resulting values
- * @throws ArithmeticException if the fraction to divide by is zero
+ * @throws ArithmeticException if the value to divide by is zero
*/
public BigFraction divide(final BigInteger bg) {
if (bg.signum() == 0) {
@@ -573,7 +577,7 @@
*
* @param i the {@code int} to divide by
* @return a {@link BigFraction} instance with the resulting values
- * @throws ArithmeticException if the fraction to divide by is zero
+ * @throws ArithmeticException if the value to divide by is zero
*/
public BigFraction divide(final int i) {
return divide(BigInteger.valueOf(i));
@@ -587,7 +591,7 @@
*
* @param l the {@code long} to divide by
* @return a {@link BigFraction} instance with the resulting values
- * @throws ArithmeticException if the fraction to divide by is zero
+ * @throws ArithmeticException if the value to divide by is zero
*/
public BigFraction divide(final long l) {
return divide(BigInteger.valueOf(l));
diff --git a/commons-numbers-fraction/src/main/java/org/apache/commons/numbers/fraction/Fraction.java b/commons-numbers-fraction/src/main/java/org/apache/commons/numbers/fraction/Fraction.java
index 13df694..bdc39f5 100644
--- a/commons-numbers-fraction/src/main/java/org/apache/commons/numbers/fraction/Fraction.java
+++ b/commons-numbers-fraction/src/main/java/org/apache/commons/numbers/fraction/Fraction.java
@@ -68,7 +68,7 @@
* within {@code epsilon} of {@code value}, in absolute terms.
* @param maxDenominator maximum denominator value allowed.
* @param maxIterations maximum number of convergents
- * @throws IllegalArgumentException if the continued fraction failed
+ * @throws ArithmeticException if the continued fraction failed
* to converge.
*/
private Fraction(double value, double epsilon, int maxDenominator, int maxIterations) {
@@ -183,7 +183,7 @@
* Creates an instance.
*
* @param value Value to convert to a fraction.
- * @throws IllegalArgumentException if the continued fraction failed to
+ * @throws ArithmeticException if the continued fraction failed to
* converge.
* @return a new instance.
*/
@@ -205,7 +205,7 @@
* @param epsilon maximum error allowed. The resulting fraction is within
* {@code epsilon} of {@code value}, in absolute terms.
* @param maxIterations maximum number of convergents
- * @throws IllegalArgumentException if the continued fraction failed to
+ * @throws ArithmeticException if the continued fraction failed to
* converge.
* @return a new instance.
*/
@@ -225,7 +225,7 @@
*
* @param value the double value to convert to a fraction.
* @param maxDenominator The maximum allowed value for denominator
- * @throws IllegalArgumentException if the continued fraction failed to
+ * @throws ArithmeticException if the continued fraction failed to
* converge.
* @return a new instance.
*/
@@ -422,7 +422,7 @@
* @param fraction Fraction to add.
* @return a new instance.
* @throws ArithmeticException if the resulting numerator or denominator
- * exceeds {@code Integer.MAX_VALUE}
+ * cannot be represented in an {@code int}.
*/
@Override
public Fraction add(Fraction fraction) {
@@ -522,7 +522,7 @@
* @param fraction Fraction to multiply by.
* @return a new instance.
* @throws ArithmeticException if the resulting numerator or denominator
- * exceeds {@code Integer.MAX_VALUE}
+ * cannot be represented in an {@code int}.
*/
@Override
public Fraction multiply(Fraction fraction) {
@@ -556,8 +556,8 @@
* @param fraction Fraction to divide by.
* @return a new instance.
* @throws ArithmeticException if the fraction to divide by is zero
- * or if the resulting numerator or denominator exceeds
- * {@code Integer.MAX_VALUE}
+ * or if the resulting numerator or denominator cannot be represented
+ * by an {@code int}.
*/
@Override
public Fraction divide(Fraction fraction) {
diff --git a/commons-numbers-gamma/src/main/java/org/apache/commons/numbers/gamma/ErfDifference.java b/commons-numbers-gamma/src/main/java/org/apache/commons/numbers/gamma/ErfDifference.java
index 1fbd36f..157beed 100644
--- a/commons-numbers-gamma/src/main/java/org/apache/commons/numbers/gamma/ErfDifference.java
+++ b/commons-numbers-gamma/src/main/java/org/apache/commons/numbers/gamma/ErfDifference.java
@@ -45,6 +45,7 @@
* @param x1 First value.
* @param x2 Second value.
* @return {@link Erf#value(double) Erf.value(x2) - Erf.value(x1)}.
+ * @throws ArithmeticException if the algorithm fails to converge.
*/
public static double value(double x1,
double x2) {
diff --git a/commons-numbers-gamma/src/main/java/org/apache/commons/numbers/gamma/GammaException.java b/commons-numbers-gamma/src/main/java/org/apache/commons/numbers/gamma/GammaException.java
index 13e9276..9c0eae1 100644
--- a/commons-numbers-gamma/src/main/java/org/apache/commons/numbers/gamma/GammaException.java
+++ b/commons-numbers-gamma/src/main/java/org/apache/commons/numbers/gamma/GammaException.java
@@ -24,8 +24,6 @@
class GammaException extends IllegalArgumentException {
/** Error message for "out of range" condition. */
static final String OUT_OF_RANGE = "Number {0} is out of range [{1}, {2}]";
- /** Error message for convergence failure. */
- static final String CONVERGENCE = "Failed to converge within {0} iterations";
/** Serializable version identifier. */
private static final long serialVersionUID = 20170505L;
diff --git a/commons-numbers-gamma/src/main/java/org/apache/commons/numbers/gamma/RegularizedGamma.java b/commons-numbers-gamma/src/main/java/org/apache/commons/numbers/gamma/RegularizedGamma.java
index 031cb59..bfefa50 100644
--- a/commons-numbers-gamma/src/main/java/org/apache/commons/numbers/gamma/RegularizedGamma.java
+++ b/commons-numbers-gamma/src/main/java/org/apache/commons/numbers/gamma/RegularizedGamma.java
@@ -16,6 +16,8 @@
*/
package org.apache.commons.numbers.gamma;
+import java.text.MessageFormat;
+
import org.apache.commons.numbers.fraction.ContinuedFraction;
/**
@@ -49,6 +51,7 @@
* @param a Argument.
* @param x Argument.
* @return \( P(a, x) \).
+ * @throws ArithmeticException if the continued fraction fails to converge.
*/
public static double value(double a,
double x) {
@@ -79,6 +82,7 @@
* @param epsilon Tolerance in continued fraction evaluation.
* @param maxIterations Maximum number of iterations in continued fraction evaluation.
* @return \( P(a, x) \).
+ * @throws ArithmeticException if the continued fraction fails to converge.
*/
public static double value(double a,
double x,
@@ -110,7 +114,8 @@
sum += an;
}
if (n >= maxIterations) {
- throw new GammaException(GammaException.CONVERGENCE, maxIterations);
+ throw new ArithmeticException(
+ MessageFormat.format("Failed to converge within {0} iterations", maxIterations));
} else if (Double.isInfinite(sum)) {
return 1;
} else {
@@ -136,6 +141,7 @@
* @param a Argument.
* @param x Argument.
* @return \( Q(a, x) \).
+ * @throws ArithmeticException if the continued fraction fails to converge.
*/
public static double value(double a,
double x) {
@@ -162,6 +168,7 @@
* @param x Argument.
* @param epsilon Tolerance in continued fraction evaluation.
* @param maxIterations Maximum number of iterations in continued fraction evaluation.
+ * @throws ArithmeticException if the continued fraction fails to converge.
* @return \( Q(a, x) \).
*/
public static double value(final double a,
diff --git a/commons-numbers-quaternion/src/main/java/org/apache/commons/numbers/quaternion/Slerp.java b/commons-numbers-quaternion/src/main/java/org/apache/commons/numbers/quaternion/Slerp.java
index 0d7b724..dcabaa7 100644
--- a/commons-numbers-quaternion/src/main/java/org/apache/commons/numbers/quaternion/Slerp.java
+++ b/commons-numbers-quaternion/src/main/java/org/apache/commons/numbers/quaternion/Slerp.java
@@ -110,7 +110,7 @@
}
/**
- * Spherical interpolation, used whe the quaternions are too closely aligned.
+ * Spherical interpolation, used when the quaternions are too closely aligned.
* When we may end up dividing by zero (cf. 1/sin(theta) term below).
* {@link Linear} interpolation must be used.
*/
diff --git a/commons-numbers-rootfinder/src/main/java/org/apache/commons/numbers/rootfinder/BrentSolver.java b/commons-numbers-rootfinder/src/main/java/org/apache/commons/numbers/rootfinder/BrentSolver.java
index 39a2b49..4b7c3c3 100644
--- a/commons-numbers-rootfinder/src/main/java/org/apache/commons/numbers/rootfinder/BrentSolver.java
+++ b/commons-numbers-rootfinder/src/main/java/org/apache/commons/numbers/rootfinder/BrentSolver.java
@@ -66,6 +66,9 @@
* @param min Lower bound.
* @param max Upper bound.
* @return the root.
+ * @throws IllegalArgumentException if {@code min > max}.
+ * @throws IllegalArgumentException if the given interval does
+ * not bracket the root.
*/
public double findRoot(DoubleUnaryOperator func,
double min,
@@ -82,6 +85,10 @@
* @param initial Initial guess.
* @param max Upper bound.
* @return the root.
+ * @throws IllegalArgumentException if {@code min > max} or
+ * {@code initial} is not in the {@code [min, max]} interval.
+ * @throws IllegalArgumentException if the given interval does
+ * not bracket the root.
*/
public double findRoot(DoubleUnaryOperator func,
double min,
