From cae2a845fa465261cdbaa1604e1f839d6e89bbbc Mon Sep 17 00:00:00 2001
From: Gilles Sadowski <erans@apache.org>
Date: Fri, 5 Aug 2011 22:07:31 +0000
Subject: [PATCH] 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
---
 .../apache/commons/math/complex/Complex.java  | 28 +++++++++++--------
 .../commons/math/complex/ComplexTest.java     | 14 ----------
 2 files changed, 17 insertions(+), 25 deletions(-)

diff --git a/src/main/java/org/apache/commons/math/complex/Complex.java b/src/main/java/org/apache/commons/math/complex/Complex.java
index eb9f3a22a..ac31e4b1b 100644
--- a/src/main/java/org/apache/commons/math/complex/Complex.java
+++ b/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$
diff --git a/src/test/java/org/apache/commons/math/complex/ComplexTest.java b/src/test/java/org/apache/commons/math/complex/ComplexTest.java
index fe8ef6951..4bc85b8f7 100644
--- a/src/test/java/org/apache/commons/math/complex/ComplexTest.java
+++ b/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