root/trunk/docsrc/cppcomplex.dd

Ddoc

$(COMMUNITY D Complex Types and C++ std::complex,

    How do D's complex numbers compare with C++'s std::complex class?

<h3>Syntactical Aesthetics</h3>

    In C++, the complex types are:

$(CCODE
complex&lt;float&gt;
complex&lt;double&gt;
complex&lt;long double&gt;
)

    C++ has no distinct imaginary type. D has 3 complex types and 3
    imaginary types:

------------
cfloat
cdouble
creal
ifloat
idouble
ireal
------------

    A C++ complex number can interact with an arithmetic literal, but
    since there is no imaginary type, imaginary numbers can only be
    created with the constructor syntax:

$(CCODE
complex&lt;long double&gt; a = 5;       // a = 5 + 0i
complex&lt;long double&gt; b(0,7);      // b = 0 + 7i
c = a + b + complex&lt;long double&gt;(0,7);    // c = 5 + 14i
)

    In D, an imaginary numeric literal has the $(SINGLEQUOTE i) suffix.
    The corresponding code would be the more natural:

------------
creal a = 5;        // a = 5 + 0i
ireal b = 7i;       // b = 7i
c = a + b + 7i;     // c = 5 + 14i
------------

    For more involved expressions involving constants:

------------
c = (6 + 2i - 1 + 3i) / 3i;
------------

    In C++, this would be:

$(CCODE
c = (complex&lt;double&gt;(6,2) + complex&lt;double&gt;(-1,3)) / complex&lt;double&gt;(0,3);
)

    or if an imaginary class were added to C++ it might be:

$(CCODE
c = (6 + imaginary&lt;double&gt;(2) - 1 + imaginary&lt;double&gt;(3)) / imaginary&lt;double&gt;(3);
)

    In other words, an imaginary number $(I nn) can be represented with
    just $(I nn)i rather than writing a constructor call
    complex&lt;long double&gt;(0,$(I nn)).

<h3>Efficiency</h3>

    The lack of an imaginary type in C++ means that operations on
    imaginary numbers wind up with a lot of extra computations done
    on the 0 real part. For example, adding two imaginary numbers
    in D is one add:

------------
ireal a, b, c;
c = a + b;
------------

    In C++, it is two adds, as the real parts get added too:

$(CCODE
c.re = a.re + b.re;
c.im = a.im + b.im;
)

    Multiply is worse, as 4 multiplies and two adds are done instead of
    one multiply:

$(CCODE
c.re = a.re * b.re - a.im * b.im;
c.im = a.im * b.re + a.re * b.im;
)

    Divide is the worst - D has one divide, whereas C++ implements
    complex division with typically one comparison, 3 divides,
    3 multiplies and 3 additions:

$(CCODE
if (fabs(b.re) < fabs(b.im))
{
    r = b.re / b.im;
    den = b.im + r * b.re;
    c.re = (a.re * r + a.im) / den;
    c.im = (a.im * r - a.re) / den;
}
else
{
    r = b.im / b.re;
    den = b.re + r * b.im;
    c.re = (a.re + r * a.im) / den;
    c.im = (a.im - r * a.re) / den;
}
)

    To avoid these efficiency concerns in C++, one could simulate
    an imaginary number using a double. For example, given the D:

------------
cdouble c;
idouble im;
c *= im;
------------

    it could be written in C++ as:

$(CCODE
complex&lt;double&gt; c;
double im;
c = complex&lt;double&gt;(-c.imag() * im, c.real() * im);
)

    but then the advantages of complex being a library type integrated
    in with the arithmetic operators have been lost.

<h3>Semantics</h3>

    Worst of all, the lack of an imaginary type can cause the wrong
    answer to be inadvertently produced.
    To quote <a href="http://www.cs.berkeley.edu/~wkahan/">
    Prof. Kahan</a>:

    $(BLOCKQUOTE 
    "A streamline goes astray when the complex functions SQRT and LOG
    are implemented, as is necessary in Fortran and in libraries
    currently distributed with C/C++ compilers, in a way that
    disregards the sign of 0.0 in IEEE 754 arithmetic and consequently
    violates identities like SQRT( CONJ( Z ) ) = CONJ( SQRT( Z ) ) and
    LOG( CONJ( Z ) ) = CONJ( LOG( Z ) ) whenever the COMPLEX variable Z
    takes negative real values. Such anomalies are unavoidable if
    Complex Arithmetic operates on pairs (x, y) instead of notional
    sums x + i*y of real and imaginary
    variables. The language of pairs is $(I incorrect) for Complex
    Arithmetic; it needs the Imaginary type."
    )

    The semantic problems are:

    $(UL 
    $(LI Consider the formula (1 - infinity*$(I i)) * $(I i) which
    should produce (infinity + $(I i)). However, if instead the second
    factor is (0 + $(I i)) rather than just $(I i), the result is
    (infinity + NaN*$(I i)), a spurious NaN was generated.
    )

    $(LI A distinct imaginary type preserves the sign of 0, necessary
    for calculations involving branch cuts.
    )
    )

    Appendix G of the C99 standard has recommendations for dealing
    with this problem. However, those recommendations are not part
    of the C++98 standard, and so cannot be portably relied upon.

<h3>References</h3>

    <a href="http://www.cs.berkeley.edu/~wkahan/JAVAhurt.pdf">
    How Java's Floating-Point Hurts Everyone Everywhere</a>
    Prof. W. Kahan and Joseph D. Darcy
    <p>

    <a href="http://www.cs.berkeley.edu/~wkahan/Curmudge.pdf">
    The Numerical Analyst as Computer Science Curmudgeon</a>
    by Prof. W. Kahan
    <p>

    $(DOUBLEQUOTE Branch Cuts for Complex Elementary Functions,
    or Much Ado About Nothing's Sign Bit) 
    by W. Kahan, ch.<br>
    7 in The State of the Art in Numerical Analysis (1987)
    ed. by M. Powell and A. Iserles for Oxford U.P.

)

Macros:
    TITLE=D Complex Types vs C++ std::complex
    WIKI=CPPcomplex