MATH-632

Added explicit note on the different behaviors for NaN values between
Java and IEEE-754.


git-svn-id: https://svn.apache.org/repos/asf/commons/proper/math/trunk@1154392 13f79535-47bb-0310-9956-ffa450edef68

src/main/java/org/apache/commons/math/complex/Complex.java

@@ -31,18 +31,24 @@ import org.apache.commons.math.util.FastMath;
 /**
  * Representation of a Complex number, i.e. a number which has both a
  * real and imaginary part.
- * Implementations of arithmetic operations handle {@code NaN} and
- * infinite values according to the rules for {@link java.lang.Double}
- * arithmetic, applying definitional formulas and returning {@code NaN} or
- * infinite values in real or imaginary parts as these arise in computation.
- * See individual method javadocs for details.
  * <br/>
- * {@link #equals} identifies all values with {@code NaN} in either real
- * or imaginary part, e.g.
- * <pre>
- *  {@code 1 + NaNi  == NaN + i == NaN + NaNi.}
- * </pre>
- *
+ * Implementations of arithmetic operations handle {@code NaN} and
+ * infinite values according to the rules for {@link java.lang.Double}, i.e.
+ * {@link #equals} is an equivalence relation for all instances that have
+ * a {@code NaN} in either real or imaginary part, e.g. the following are
+ * considered equal:
+ * <ul>
+ *  <li>{@code 1 + NaNi}</li>
+ *  <li>{@code NaN + i}</li>
+ *  <li>{@code NaN + NaNi}</li>
+ * </ul>
+ * Note that this is in contradiction with the IEEE-754 standard for floating
+ * point numbers (according to which the test {@code x == x} must fail if
+ * {@code x} is {@code NaN}). The method
+ * {@link MathUtils#equals(double,double,int) equals for primitive double} in
+ * {@link MathUtils} conforms with IEEE-754 while this class conforms with
+ * the standard behavior for Java object types.
+ * <br/>
  * Implements Serializable since 2.0
  *
  * @version $Id$

src/test/java/org/apache/commons/math/complex/ComplexTest.java

@@ -479,20 +479,6 @@ public class ComplexTest {
         Assert.assertTrue(realNaN.equals(imaginaryNaN));
         Assert.assertTrue(imaginaryNaN.equals(complexNaN));
         Assert.assertTrue(realNaN.equals(complexNaN));
-
-        final double a = Double.NaN;
-        final double b = Double.NaN;
-        Assert.assertFalse("a == b", a == b);
-        Assert.assertEquals("a != b", a, b, Double.MIN_VALUE);
-        Assert.assertFalse("a == b", MathUtils.equals(a, b));
-        Assert.assertFalse("a == b", MathUtils.equals(a, b, Double.MIN_VALUE));
-        final Double dA = Double.valueOf(a);
-        final Double dB = Double.valueOf(b);
-        Assert.assertFalse("dA == dB", dA.doubleValue() == dB.doubleValue());
-        Assert.assertTrue("!dA.equals(dB)", dA.equals(dB));
-        final Complex cA = new Complex(a, 0);
-        final Complex cB = new Complex(b, 0);
-        Assert.assertTrue("!cA.equals(cB)", cA.equals(cB));
     }
 
     @Test