From 142fa7bbc51a6010f0b7e8ec1648b6d79b182f7d Mon Sep 17 00:00:00 2001 From: Sumanth Rajkumar Date: Tue, 19 Jul 2022 16:28:17 -0400 Subject: [PATCH] NUMBERS-188 javadoc edits --- .../numbers/complex/ComplexFunctions.java | 10 +- .../commons/numbers/complex/ComplexSink.java | 2 +- .../numbers/complex/CReferenceTest.java | 20 ++- .../numbers/complex/CStandardTest.java | 134 +++++++++--------- .../numbers/complex/ComplexEdgeCaseTest.java | 18 +-- .../numbers/complex/ComplexNumber.java | 4 +- .../commons/numbers/complex/TestUtils.java | 37 ++--- 7 files changed, 102 insertions(+), 123 deletions(-) diff --git a/commons-numbers-complex/src/main/java/org/apache/commons/numbers/complex/ComplexFunctions.java b/commons-numbers-complex/src/main/java/org/apache/commons/numbers/complex/ComplexFunctions.java index e92a9929d..4cecc36ed 100644 --- a/commons-numbers-complex/src/main/java/org/apache/commons/numbers/complex/ComplexFunctions.java +++ b/commons-numbers-complex/src/main/java/org/apache/commons/numbers/complex/ComplexFunctions.java @@ -209,7 +209,7 @@ public static boolean isInfinite(double real, double imaginary) { * @param real Real part \( a \) of the complex number \( (a +ib \). * @param imaginary Imaginary part \( b \) of the complex number \( (a +ib \). * @param action Consumer for the natural logarithm of the complex number. - * @param the object taken by the supplied action. + * @param the return type of the supplied action. * @return the object returned by the supplied action. * @see Math#log(double) * @see Log @@ -237,7 +237,7 @@ public static R log(double real, double imaginary, ComplexSink action) { * @param real Real part \( a \) of the complex number \( (a +ib \). * @param imaginary Imaginary part \( b \) of the complex number \( (a +ib \). * @param action Consumer for the natural logarithm of the complex number. - * @param the object taken by the supplied action. + * @param the return type of the supplied action. * @return the object returned by the supplied action. * @see Math#log10(double) */ @@ -263,7 +263,7 @@ public static R log10(double real, double imaginary, ComplexSink action) * @param real Real part \( a \) of the complex number \( (a +ib \). * @param imaginary Imaginary part \( b \) of the complex number \( (a +ib \). * @param action Consumer for the natural logarithm of the complex number. - * @param the object taken by the supplied action. + * @param the return type of the supplied action. * @return the object returned by the supplied action. */ private static R log(DoubleUnaryOperator log, @@ -666,7 +666,7 @@ static double x2y2m1(double x, double y) { * @see * Dekker (1971) A floating-point technique for extending the available precision */ - static double splitHigh(double a) { + private static double splitHigh(double a) { final double c = MULTIPLIER * a; return c - (c - a); } @@ -687,7 +687,7 @@ static double splitHigh(double a) { * @see * Shewchuk (1997) Theorum 18 */ - static double squareLow(double low, double high, double square) { + private static double squareLow(double low, double high, double square) { final double lh = low * high; return low * low - (((square - high * high) - lh) - lh); } diff --git a/commons-numbers-complex/src/main/java/org/apache/commons/numbers/complex/ComplexSink.java b/commons-numbers-complex/src/main/java/org/apache/commons/numbers/complex/ComplexSink.java index 6e3c0759a..1c78d1884 100644 --- a/commons-numbers-complex/src/main/java/org/apache/commons/numbers/complex/ComplexSink.java +++ b/commons-numbers-complex/src/main/java/org/apache/commons/numbers/complex/ComplexSink.java @@ -18,7 +18,7 @@ package org.apache.commons.numbers.complex; /** - * Represents a data sink for a complex number \( (a + i b) \) + * Represents a data sink for a complex number \( (a + i b) \). * Operations return a result of type {@code R}. * *

This is a functional interface whose functional method is diff --git a/commons-numbers-complex/src/test/java/org/apache/commons/numbers/complex/CReferenceTest.java b/commons-numbers-complex/src/test/java/org/apache/commons/numbers/complex/CReferenceTest.java index 898a46e9a..dd283af37 100644 --- a/commons-numbers-complex/src/test/java/org/apache/commons/numbers/complex/CReferenceTest.java +++ b/commons-numbers-complex/src/test/java/org/apache/commons/numbers/complex/CReferenceTest.java @@ -157,10 +157,10 @@ static void assertEquals(Supplier msg, double expected, double actual, l * Assert the operation on the complex number is exactly equal to the operation on * complex real and imaginary parts. * - * @param c Input number. - * @param name the operation name - * @param operation1 the operation on the Complex object - * @param operation2 the operation on the complex real and imaginary parts + * @param c Input complex number. + * @param name Operation name. + * @param operation1 Operation on the Complex object. + * @param operation2 Operation on the complex real and imaginary parts. * @param expected Expected result. */ static void assertComplex(Complex c, @@ -169,12 +169,10 @@ static void assertComplex(Complex c, ComplexUnaryOperator operation2, Complex expected, long maxUlps) { - final Complex z = operation1.apply(c); + final Complex z = TestUtils.assertSame(c, operation1, operation2, name); assertEquals(() -> "UnaryOperator " + name + "(" + c + "): real", expected.real(), z.real(), maxUlps); assertEquals(() -> "UnaryOperator " + name + "(" + c + "): imaginary", expected.imag(), z.imag(), maxUlps); - - TestUtils.assertSame(c, operation1, operation2, name); } /** @@ -259,10 +257,10 @@ private static void assertBiOperation(String name, /** * Assert the operation using the data loaded from test resources. * - * @param name the operation name - * @param operation1 the operation on the Complex object - * @param operation2 the operation on the complex real and imaginary parts - * @param maxUlps the maximum units of least precision between the two values + * @param name Operation name + * @param operation1 Operation on the Complex object. + * @param operation2 Operation on the complex real and imaginary parts. + * @param maxUlps Maximum units of least precision between the two values. */ private static void assertOperation(String name, UnaryOperator operation1, diff --git a/commons-numbers-complex/src/test/java/org/apache/commons/numbers/complex/CStandardTest.java b/commons-numbers-complex/src/test/java/org/apache/commons/numbers/complex/CStandardTest.java index d7feae589..edd3c435c 100644 --- a/commons-numbers-complex/src/test/java/org/apache/commons/numbers/complex/CStandardTest.java +++ b/commons-numbers-complex/src/test/java/org/apache/commons/numbers/complex/CStandardTest.java @@ -309,7 +309,7 @@ private static void assertConjugateEquality(Complex z, * *

The results must be binary equal. This includes the sign of zero. * - * Assert the operation on the complex number is exactly equal to the operation on + *

Assert the operation on the complex number is exactly equal to the operation on * complex real and imaginary parts. * *

ISO C99 equalities

@@ -330,10 +330,13 @@ private static void assertConjugateEquality(Complex z, *
  • sinh(inf, nan) * * - * @param operation the operation + * @param operation1 Operation on the Complex object. + * @param operation2 Operation on the complex real and imaginary parts. + * @param name Operation name. */ - private static void assertConjugateEquality(UnaryOperator operation, - ComplexUnaryOperator operation2) { + private static void assertConjugateEquality(UnaryOperator operation1, + ComplexUnaryOperator operation2, + String name) { // Edge cases. Inf/NaN are specifically handled in the C99 test cases // but are repeated here to enforce the conjugate equality even when the C99 // standard does not specify a sign. This may be revised in the future. @@ -343,7 +346,7 @@ private static void assertConjugateEquality(UnaryOperator operation, for (final double y : parts) { // No conjugate for imaginary NaN if (!Double.isNaN(y)) { - assertConjugateEquality(complex(x, y), operation, operation2, UnspecifiedSign.NONE); + assertConjugateEquality(complex(x, y), operation1, operation2, UnspecifiedSign.NONE, name); } } } @@ -352,7 +355,7 @@ private static void assertConjugateEquality(UnaryOperator operation, for (int i = 0; i < 100; i++) { final double x = next(rng); final double y = next(rng); - assertConjugateEquality(complex(x, y), operation, operation2, UnspecifiedSign.NONE); + assertConjugateEquality(complex(x, y), operation1, operation2, UnspecifiedSign.NONE, name); } } @@ -366,25 +369,23 @@ private static void assertConjugateEquality(UnaryOperator operation, *

    The results must be binary equal; the sign of the complex number is first processed * using the provided sign specification. * - * Assert the operation on the complex number is exactly equal to the operation on + *

    Assert the operation on the complex number is exactly equal to the operation on * complex real and imaginary parts. * - * @param z the complex number - * @param operation1 the operation on the Complex object - * @param operation2 the operation on the complex real and imaginary parts + * @param z Input complex number. + * @param operation1 Operation on the Complex object. + * @param operation2 Operation on the complex real and imaginary parts. * @param sign the sign specification + * @param name Operation name. */ private static void assertConjugateEquality(Complex z, UnaryOperator operation1, ComplexUnaryOperator operation2, - UnspecifiedSign sign) { + UnspecifiedSign sign, String name) { final Complex zConj = z.conj(); - final Complex c1 = operation1.apply(zConj); - final Complex c2 = operation1.apply(z).conj(); - - final ComplexNumber cn1 = operation2.apply(zConj.getReal(), zConj.getImaginary(), ComplexNumber::new); - final ComplexNumber cn2 = operation2.apply(z.getReal(), z.getImaginary(), ComplexNumber::conj); + final Complex c1 = TestUtils.assertSame(zConj, operation1, operation2, name); + final Complex c2 = TestUtils.assertSame(z, operation1, operation2, name).conj(); final Complex t1 = sign.removeSign(c1); final Complex t2 = sign.removeSign(c2); @@ -396,9 +397,6 @@ private static void assertConjugateEquality(Complex z, String.format("Conjugate equality failed (z=%s). Expected: %s but was: %s (Unspecified sign = %s)", z, c1, c2, sign)); } - - TestUtils.assertSame(c1, cn1); - TestUtils.assertSame(c2, cn2); } /** @@ -619,19 +617,20 @@ private static void assertComplex(Complex z, * *

    The results must be binary equal. This includes the sign of zero. * - * Assert the operation on the complex number is exactly equal to the operation on + *

    Assert the operation on the complex number is exactly equal to the operation on * complex real and imaginary parts. * - * @param z the complex - * @param operation1 the operation on the Complex object - * @param operation2 the operation on the complex real and imaginary parts - * @param expected the expected + * @param z Input complex number. + * @param operation1 Operation on the Complex object. + * @param operation2 Operation on the complex real and imaginary parts. + * @param expected Expected complex number. + * @param name Operation name. */ private static void assertComplex(Complex z, UnaryOperator operation1, ComplexUnaryOperator operation2, - Complex expected) { - assertComplex(z, operation1, operation2, expected, FunctionType.NONE, UnspecifiedSign.NONE); + Complex expected, String name) { + assertComplex(z, operation1, operation2, expected, FunctionType.NONE, UnspecifiedSign.NONE, name); } /** @@ -655,22 +654,24 @@ private static void assertComplex(Complex z, *

    The results must be binary equal; the sign of the complex number is first processed * using the provided sign specification. * - * Assert the operation on the complex number is exactly equal to the operation on + *

    Assert the operation on the complex number is exactly equal to the operation on * complex real and imaginary parts. * - * @param z the complex - * @param operation the operation on the Complex object - * @param operation2 the operation on the complex real and imaginary parts - * @param expected the expected + * @param z Input complex number. + * @param operation1 Operation on the Complex object. + * @param operation2 Operation on the complex real and imaginary parts. + * @param expected Expected complex number. * @param type the type * @param sign the sign specification + * @param name Operation name. */ private static void assertComplex(Complex z, - UnaryOperator operation, + UnaryOperator operation1, ComplexUnaryOperator operation2, Complex expected, FunctionType type, - UnspecifiedSign sign) { + UnspecifiedSign sign, + String name) { // Developer note: Set the sign specification to UnspecifiedSign.NONE // to see which equalities fail. They should be for input defined @@ -678,8 +679,7 @@ private static void assertComplex(Complex z, // sign = UnspecifiedSign.NONE // Test the operation - final Complex c = operation.apply(z); - final ComplexNumber c1 = operation2.apply(z.getReal(), z.getImaginary(), ComplexNumber::new); + final Complex c = TestUtils.assertSame(z, operation1, operation2, name); final Complex t1 = sign.removeSign(c); final Complex t2 = sign.removeSign(expected); @@ -691,11 +691,11 @@ private static void assertComplex(Complex z, } if (!Double.isNaN(z.getImaginary())) { - assertConjugateEquality(z, operation, operation2, sign); + assertConjugateEquality(z, operation1, operation2, sign, name); } if (type != FunctionType.NONE) { - assertFunctionType(z, operation, type, sign); + assertFunctionType(z, operation1, type, sign); // An odd/even function should satisfy the conjugate equality // on the negated complex. This ensures testing the equalities @@ -705,11 +705,9 @@ private static void assertComplex(Complex z, // = -(-re, -im) (odd) // (-re, -im) = (-re, im) if (!Double.isNaN(z.getImaginary())) { - assertConjugateEquality(z.negate(), operation, operation2, sign); + assertConjugateEquality(z.negate(), operation1, operation2, sign, name); } } - - TestUtils.assertSame(c, c1); } /** @@ -1443,30 +1441,30 @@ void testLog() { final UnaryOperator operation1 = Complex::log; final ComplexUnaryOperator operation2 = ComplexFunctions::log; - assertConjugateEquality(operation1, operation2); - assertComplex(negZeroZero, operation1, operation2, negInfPi); - assertComplex(Complex.ZERO, operation1, operation2, negInfZero); + assertConjugateEquality(operation1, operation2, "log"); + assertComplex(negZeroZero, operation1, operation2, negInfPi, "log"); + assertComplex(Complex.ZERO, operation1, operation2, negInfZero, "log"); for (double x : finite) { - assertComplex(complex(x, inf), operation1, operation2, infPiTwo); + assertComplex(complex(x, inf), operation1, operation2, infPiTwo, "log"); } for (double x : finite) { - assertComplex(complex(x, nan), operation1, operation2, NAN); + assertComplex(complex(x, nan), operation1, operation2, NAN, "log"); } for (double y : positiveFinite) { - assertComplex(complex(-inf, y), operation1, operation2, infPi); + assertComplex(complex(-inf, y), operation1, operation2, infPi, "log"); } for (double y : positiveFinite) { - assertComplex(complex(inf, y), operation1, operation2, infZero); + assertComplex(complex(inf, y), operation1, operation2, infZero, "log"); } - assertComplex(negInfInf, operation1, operation2, infThreePiFour); - assertComplex(infInf, operation1, operation2, infPiFour); - assertComplex(negInfNaN, operation1, operation2, infNaN); - assertComplex(infNaN, operation1, operation2, infNaN); + assertComplex(negInfInf, operation1, operation2, infThreePiFour, "log"); + assertComplex(infInf, operation1, operation2, infPiFour, "log"); + assertComplex(negInfNaN, operation1, operation2, infNaN, "log"); + assertComplex(infNaN, operation1, operation2, infNaN, "log"); for (double y : finite) { - assertComplex(complex(nan, y), operation1, operation2, NAN); + assertComplex(complex(nan, y), operation1, operation2, NAN, "log"); } - assertComplex(nanInf, operation1, operation2, infNaN); - assertComplex(NAN, operation1, operation2, NAN); + assertComplex(nanInf, operation1, operation2, infNaN, "log"); + assertComplex(NAN, operation1, operation2, NAN, "log"); } /** @@ -1478,30 +1476,30 @@ void testLog10() { final UnaryOperator operation1 = Complex::log10; final ComplexUnaryOperator operation2 = ComplexFunctions::log10; - assertConjugateEquality(operation1, operation2); - assertComplex(negZeroZero, operation1, operation2, negInfPi); - assertComplex(Complex.ZERO, operation1, operation2, negInfZero); + assertConjugateEquality(operation1, operation2, "log10"); + assertComplex(negZeroZero, operation1, operation2, negInfPi, "log10"); + assertComplex(Complex.ZERO, operation1, operation2, negInfZero, "log10"); for (double x : finite) { - assertComplex(complex(x, inf), operation1, operation2, infPiTwo); + assertComplex(complex(x, inf), operation1, operation2, infPiTwo, "log10"); } for (double x : finite) { - assertComplex(complex(x, nan), operation1, operation2, NAN); + assertComplex(complex(x, nan), operation1, operation2, NAN, "log10"); } for (double y : positiveFinite) { - assertComplex(complex(-inf, y), operation1, operation2, infPi); + assertComplex(complex(-inf, y), operation1, operation2, infPi, "log10"); } for (double y : positiveFinite) { - assertComplex(complex(inf, y), operation1, operation2, infZero); + assertComplex(complex(inf, y), operation1, operation2, infZero, "log10"); } - assertComplex(negInfInf, operation1, operation2, infThreePiFour); - assertComplex(infInf, operation1, operation2, infPiFour); - assertComplex(negInfNaN, operation1, operation2, infNaN); - assertComplex(infNaN, operation1, operation2, infNaN); + assertComplex(negInfInf, operation1, operation2, infThreePiFour, "log10"); + assertComplex(infInf, operation1, operation2, infPiFour, "log10"); + assertComplex(negInfNaN, operation1, operation2, infNaN, "log10"); + assertComplex(infNaN, operation1, operation2, infNaN, "log10"); for (double y : finite) { - assertComplex(complex(nan, y), operation1, operation2, NAN); + assertComplex(complex(nan, y), operation1, operation2, NAN, "log10"); } - assertComplex(nanInf, operation1, operation2, infNaN); - assertComplex(NAN, operation1, operation2, NAN); + assertComplex(nanInf, operation1, operation2, infNaN, "log10"); + assertComplex(NAN, operation1, operation2, NAN, "log10"); } /** diff --git a/commons-numbers-complex/src/test/java/org/apache/commons/numbers/complex/ComplexEdgeCaseTest.java b/commons-numbers-complex/src/test/java/org/apache/commons/numbers/complex/ComplexEdgeCaseTest.java index 5056ebe31..c0e31008c 100644 --- a/commons-numbers-complex/src/test/java/org/apache/commons/numbers/complex/ComplexEdgeCaseTest.java +++ b/commons-numbers-complex/src/test/java/org/apache/commons/numbers/complex/ComplexEdgeCaseTest.java @@ -86,14 +86,14 @@ private static void assertComplex(double a, double b, * *

    The results are considered equal if there are no floating-point values between them. * - * Assert the operation on the complex number is exactly equal to the operation on + *

    Assert the operation on the complex number is exactly equal to the operation on * complex real and imaginary parts. * * @param a Real part. * @param b Imaginary part. - * @param name The operation name. - * @param operation1 the operation on the Complex object. - * @param operation2 the operation on the complex real and imaginary parts + * @param name Operation name. + * @param operation1 Operation on the Complex object. + * @param operation2 Operation on the complex real and imaginary parts. * @param x Expected real part. * @param y Expected imaginary part. */ @@ -111,17 +111,17 @@ private static void assertComplex(double a, double b, * precision. The maximum count of numbers allowed between the two values is * {@code maxUlps - 1}. * - * Assert the operation on the complex number is exactly equal to the operation on + *

    Assert the operation on the complex number is exactly equal to the operation on * complex real and imaginary parts. * * @param a Real part. * @param b Imaginary part. - * @param name The operation name. - * @param operation1 the operation on the Complex object. - * @param operation2 the operation on the complex real and imaginary parts + * @param name Operation name. + * @param operation1 Operation on the Complex object. + * @param operation2 Operation on the complex real and imaginary parts. * @param x Expected real part. * @param y Expected imaginary part. - * @param maxUlps the maximum units of least precision between the two values + * @param maxUlps Maximum units of least precision between the two values. */ private static void assertComplex(double a, double b, String name, UnaryOperator operation1, diff --git a/commons-numbers-complex/src/test/java/org/apache/commons/numbers/complex/ComplexNumber.java b/commons-numbers-complex/src/test/java/org/apache/commons/numbers/complex/ComplexNumber.java index 9f0eb35c6..4e90c89d2 100644 --- a/commons-numbers-complex/src/test/java/org/apache/commons/numbers/complex/ComplexNumber.java +++ b/commons-numbers-complex/src/test/java/org/apache/commons/numbers/complex/ComplexNumber.java @@ -33,11 +33,9 @@ class ComplexNumber { /** * Constructor representing a complex number by its real and imaginary parts. - * Takes in real and imaginary and sets it to this complex number's real and imaginary * * @param real Real part \( a \) of the complex number \( (a +ib \). * @param imaginary Imaginary part \( b \) of the complex number \( (a +ib \). - * */ ComplexNumber(double real, double imaginary) { this.real = real; @@ -50,7 +48,7 @@ class ComplexNumber { * * @param real Real part \( a \) of the complex number \( (a +ib \). * @param imaginary Imaginary part \( b \) of the complex number \( (a +ib \). - * @return {@code ComplexNumber} object. + * @return conjugated complex number. */ public static ComplexNumber conj(double real, double imaginary) { return new ComplexNumber(real, -imaginary); diff --git a/commons-numbers-complex/src/test/java/org/apache/commons/numbers/complex/TestUtils.java b/commons-numbers-complex/src/test/java/org/apache/commons/numbers/complex/TestUtils.java index b8c99b1d0..6efd2b369 100644 --- a/commons-numbers-complex/src/test/java/org/apache/commons/numbers/complex/TestUtils.java +++ b/commons-numbers-complex/src/test/java/org/apache/commons/numbers/complex/TestUtils.java @@ -68,19 +68,6 @@ public static void assertSame(Complex expected, Complex actual) { Assertions.assertEquals(expected.getImaginary(), actual.getImaginary()); } - /** - * Verifies that real and imaginary parts of the Complex and ComplexNumber arguments are - * exactly the same as defined by {@link Double#compare(double, double)}. Also - * ensures that NaN / infinite components match. - * - * @param expected the expected value - * @param actual the actual value - */ - public static void assertSame(Complex expected, ComplexNumber actual) { - Assertions.assertEquals(expected.getReal(), actual.getReal()); - Assertions.assertEquals(expected.getImaginary(), actual.getImaginary()); - } - /** * Verifies that real and imaginary parts of the two complex arguments differ by * at most delta. Also ensures that NaN / infinite components match. @@ -406,23 +393,21 @@ private static String preprocessTestData(String line, TestDataFlagOption option, * Assert the operation on the complex number is exactly equal to the operation on * complex real and imaginary parts. * - * @param c The input complex number. - * @param operation1 the operation on the Complex object - * @param operation2 the operation on the complex real and imaginary parts - * @param name the operation name - * @return the resulting complex number from the given operation + * @param c Input complex number. + * @param operation1 Operation on the Complex object. + * @param operation2 Operation on the complex real and imaginary parts. + * @param name Operation name. + * @return Resulting complex number from the given operation. */ static Complex assertSame(Complex c, - UnaryOperator operation1, - ComplexUnaryOperator operation2, - String name) { + UnaryOperator operation1, + ComplexUnaryOperator operation2, + String name) { final Complex z = operation1.apply(c); // Test operation2 produces the exact same result - operation2.apply(c.real(), c.imag(), (x, y) -> { - Assertions.assertEquals(z.real(), x, () -> name + " real"); - Assertions.assertEquals(z.imag(), y, () -> name + " imaginary"); - return null; - }); + final ComplexNumber z2 = operation2.apply(c.real(), c.imag(), ComplexNumber::new); + Assertions.assertEquals(z.real(), z2.getReal(), () -> name + " real"); + Assertions.assertEquals(z.imag(), z2.getImaginary(), () -> name + " imaginary"); return z; } }