To: J3                                                     J3/19-222
Subject: ATAN2 result value description is incomplete and confusing
From: Van Snyder
Date: 2019-September-29

1. Discussion
-------------

The description of ATAN2(Y,X) in paragraph 5 of subclause 16.9.18
specifies that the value "lies in the range -pi <= ATAN2(Y,X) <= pi" --
but pi is not representable as a floating-point number, so <= is not
precisely correct.

When Y = 0 and X < 0 it uses the clumsy circumlocution "the result is
approximately pi if Y is positive real zero or the processor does not
distinguish between positive and negative real zero, and approximately
-pi if Y is negative real zero."  The SIGN intrinsic function already
has this description.

If uses the confusing description "If Y = 0 and X > 0, the result is Y."
One must realize that Y might be negative zero to make sense of this.
The SIGN intrinsic function already has this description.

It specifies that the absolute value of the result is approximately
+/- pi/2 if X is zero -- but pi/2 is not representable as a floating-
point number.  It does not specify the sign if Y = 0 and X = 0.  The
sign should be negative if Y is negative real zero.  The result should
be an angle in the right half of the (X,Y) plane if SIGN(1.0,X) > 0, and
in the left half plane otherwise.

The description could be simplified by referring to the SIGN intrinsic
function.

2. Edits
--------

[345:21-27 16.9.18p5 ATAN2] Replace the Result Value paragraph with:

  "Result Value. If X /= 0, the absolute value of the result is a
  processor-dependent approximation to the value of |arctan(Y/X)|. If
  X = 0, the absolute value of the result is approximately pi/2.  The
  result is expressed in radians. If SIGN(1.0,X) > 0, the absolute
  value of the result lies in the range 0 <= ABS( ATAN2(Y,X) ) < pi/2.
  If SIGN(1.0,X) < 0, the absolute value of the result lies in the range
  pi/2 < ABS( ATAN2(Y,X) ) < pi.  The result has the same sign as
  SIGN(1.0,Y)."

{This specifies the absolute values of the results for both cases first.

It specifies the quadrant of the result, and the sign of the result, in
one place, for all results, instead of specifying the sign in separate
places for the positive and negative result value cases, and does not
omit to specify the sign of the ATAN2(-0.0,0.0) case.

It indirectly specifies which floating-point approximation of pi/2 to
use, depending upon the sign of X, by way of specifying the quadrant of
the result.

It does not require the reader to understand "the principal value of the
argument of the complex number (X,Y)," or to wonder "what are the
principal values of the arguments of the complex numbers
(+/-0.0,+/-0.0)?"

It does not require the reader to understand that the result of the
Y = 0 and X > 0 case being Y means the result might be a signed zero.

It does not require to specify the results of the Y = +/-0 and X < 0
cases explicitly.

It does not depend upon any circumlocutions whether the processor can or
cannot distinguish positive zero from negative zero, because this is
already done in the description of the SIGN intrinsic function.
}

3. Alternative edits
--------------------

[345:21-27 16.9.18p5 ATAN2] Replace the Result Value paragraph with:

  "Result value.

  case(i)  If X /= 0, the absolute value of the result is a processor-
           dependent approximation to the value of |arctan(Y/X)|.

  case(ii) If X = 0, the absolute value of the result is approximately
           pi/2.

  The result is expressed in radians. If SIGN(1.0,X) > 0, the absolute
  value of the result lies in the range 0 <= ABS( ATAN2(Y,X) ) < pi/2.
  If SIGN(1.0,X) < 0, the absolute value of the result lies in the range
  pi/2 < ABS( ATAN2(Y,X) ) < pi.  The result has the same sign as
  SIGN(1.0,Y)."

{This uses the same words as above, but having itemized cases makes it
even clearer that the specifications of the quadrant and sign apply to
both cases.}