I noticed that when working with double complex numbers in C, when a real number with a negative 0 imaginary part is passed to carg() –M_PI is returned rather than 0 or M_PI. Why is that? I found this out because another function that used carg() returned the wrong sign for the imaginary part (the function that gets broken by this behavior of carg() is newlibs cpow).
Here is a MWE to show the behavior:
#include <stdio.h>
#include <complex.h>
#include <math.h>
int main(void) {
double complex a = 2;
printf("creal(a): %fn", creal(a));
printf("cimag(a): %fn", cimag(a));
printf("carg(a): %fn", carg(a));
printf("n");
printf("creal(-a): %fn", creal(-a));
printf("cimag(-a): %fn", cimag(-a));
printf("carg(-a): %fn", carg(-a));
printf("n");
a = 0;
printf("creal(-a): %fn", creal(-a));
printf("cimag(-a): %fn", cimag(-a));
printf("carg(-a): %fn", carg(-a));
}
and here is the result after compiling with gcc 14.2.0:
creal(a): 2.000000
cimag(a): 0.000000
carg(a): 0.000000
creal(-a): -2.000000
cimag(-a): -0.000000
carg(-a): -3.141593
creal(-a): -0.000000
cimag(-a): -0.000000
carg(-a): -3.141593
1
The phase angle of a complex number x + yi, which is what carg calculates, is defined as atan y/x.
Because of this, the C standard defines carg(x + yi) as atan2(y,x) in section G.6p3.
Section F.10.1.4 of the C standard dictates that atan2 returns the following values for certain edge cases:
atan2(±0, −0)returns ± πatan2(±0, +0)returns ±0.atan2(±0, x)returns ± π for x < 0.atan2(±0, x)returns ±0 for x > 0.atan2(y, ±0)returns − π /2 for y < 0.atan2(y, ±0)returns π /2 for y > 0.atan2(±y, − ∞)returns ± π for finite y > 0.atan2(±y, + ∞)returns ±0 for finite y > 0.atan2(± ∞, x)returns ± π /2 for finite x.atan2(± ∞, − ∞)returns ±3 π /4.atan2(± ∞, + ∞)returns ± π /4.
This is consistent with the output you see.
Section 7.3.3p1 goes into more detail on this:
Some of the functions below have branch cuts, across which the
function is discontinuous. For implementations with a signed zero
(including all IEC 60559 implementations) that follow the
specifications of annex G, the sign of zero distinguishes one side of
a cut from another so the function is continuous (except for format
limitations) as the cut is approached from either side. For example,
for the square root function, which has a branch cut along the
negative real axis, the top of the cut, with imaginary part +0, maps
to the positive imaginary axis, and the bottom of the cut, with
imaginary part −0, maps to the negative imaginary axis
1
It helps astute floating-point users squeeze a little extra information out of floating-point computation. If you have carg(x + iy) for a negative x and a very small negative y, the exact result is near −π. If you calculate y using some expression whose result is negative but smaller in magnitude than the smallest negative floating-point number (and too small to round to it), then −0 is produced. If you calculated this using infinite precision arithmetic instead of finite-precision floating-point, you would have an x + iy whose carg is very near −π. When we do this in floating-point, carg producing -M_PI is as close as we can get to the result you would get with infinite precision arithmetic. In other words, in cases like this, calculating carg(x + iy) with infinite precision arithmetic would produce a result near −π, and this feature of carg causes floating-point arithmetic to mimic the ideal arithmetic and also produce a result near −π. So it is a good result, better than producing +M_PI.
Using floating-point this way is complicated and requires careful design of the software with attention to these issues. −0 can arise in other ways, so it does not always serve as an indication that a small negative number near zero would have been the desired result. Nonetheless, these features are there for users who want them.
(The above glosses over some issues, like the fact that, in some floating-point formats, the floating-point number closest to −π might be less than π, so, in order to stay in the bounds [−π, +π], carg should produce the next representable number greater than −π rather than the nearest representable number.)
This behavior for carg is specified in the C standard, in optional annexes. C 2024 Annex G specifies in G.6.1 that carg(x + iy) = atan2(y, x) and that carg’s special cases behave like atan2’s special cases. Annex F specifies in F.10.2.4 that atan2(±0, x) returns ±π for x < 0. (F.10.1 specifies that “Unless otherwise specified, where the symbol “±” occurs in both an argument and the result, the result has the same sign as the argument,” so this means that atan2(+0, x) for x < 0 returns +π and atan2(−0, x) for x < 0 returns −π.)
IEEE 754-2019 specifies the same thing for atan2 in clause 9.2.1.