[Issue 1877] Errors in the documentation of std.math.atan2

[Don Clugston]

Bill Baxter wrote:
> d-bugmail at puremagic.com wrote:
>> http://d.puremagic.com/issues/show_bug.cgi?id=1877
>>
>>
>>
>>
>>
>> ------- Comment #1 from clugdbug at yahoo.com.au  2008-02-29 02:15 -------
>> (In reply to comment #0)
>>> First of all, the doc states "Calculates the arc tangent of y / x, 
>>> returning a
>>> value ranging from -π/2 to π/2." which should be "..from -π to π.", 
>>> as is
>>> shown in the table.
>>>
>>> Then, there are a couple of inconsistencies in the "Special Values" 
>>> table:
>>> "±0.0 ±0.0 ±0.0" should be "±0.0 +0.0 ±0.0",
>>> "<0.0 ±0.0 π/2" should be "<0.0 ±0.0 -π/2",
>>> ">0.0 ∞ ±0.0" should be "anything ∞ ±0.0",
>>> ">0.0 -∞ ±π" should be "anything -∞ ±π".
>>>
>>
>> You're correct for the first three, but not for the last two. 
>> atan2(NaN, inf)
>> is NaN, not +-0. Also atan2(inf, inf) is pi/4.
> 
> Who says the atan2(inf,inf) is pi/4?  Is that an IEEE thing?

Yup.

For a sanity check, here's a link to the Java docs:
http://java.sun.com/j2se/1.4.2/docs/api/java/lang/Math.html#atan2(double,%20double)

> Seems odd since that's like saying atan(inf/inf), and inf/inf is NaN, 
> isn't it?

Yes, it's one of the strange IEEE results. There's a couple that are controversial.

> Put another way atan2(inf,inf)
> the limit of any atan2(k*x,x) as x gets big.  Since k could be anything, 
> it seems strange for the value to suddenly change to pi/4 when x becomes 
> inf.
> 
> --bb