[Cfp-interest 3096] Annex F and Annex G - primarily about special cases

[Damian McGuckin]

I am reworking these two Annexes. Most of the changes I will suggest apply 
to the special cases and how they are written/described with a view to
making them more clear.

This can be regarded as a summary of emails over the last few weeks.

Special Cases are handled inconsistently both between Annex F and Annex G, 
and within Annex F itself (sometimes), and Annex G itself (often). That
inconsistency makes these sections difficult reading.

I will note what I perceive as the problem, and then follow that text by 
a suggested solution marked '->'

In the following discussion. I will use INF to imply +INFINITY

In G.6.1, Clause 10 introduces the 'cis(y)' function, Euler's formula. 
Because the existing 'cexp' function from the C standard itself with a 
purely imaginary argument provides the same mathematics, I suggest we
use that instead.

-> the use of 'cis(y)' will be replaced by 'cexp(iy)'.

Annex F uses a mathematical relationship such as 0 < x < INF to qualify the
domain of a function's argument for which a special case holds. On the other
hand, Annex G uses mathematical words like positive finite 'x' for the same
domain, wording which is less succinct and is sometimes inconsistently used

-> Mathematical relationships are now used to qualify domains for special cases

Mention of whether or not a floating-point exception is raised for a special
case currently appears after the result but before the domain qualification
inequality or words.  In such clauses, I would suggest that

* the domain is the most important part of the qualification but it gets
   lost visually in the words talking about the floating-point exception,

* the domain is no longer seen in roughly the same location on a line
   compared to other clauses where no exception is raised.

-> Any floating-point exception now appears AFTER the domain qualification.

Note that the approaches of mathematical relationships (inequalities 
mostly) and ensuring the domain qualification immediately follows the 
result make

* a domain qualification, clear, far more obvious, and more readable;

* it easier to check these domains for accuracy and consistency.

For some special cases, the domain qualification 'runs on' immediately after
the complex 'number' which is result, i.e.

 	<function> ( <argument> ) returns <result> for +0 < y < INF

Elsewhere, a comma separates the two:

 	<function> <argument> ) returns <result> , for +0 < y < INF

The former is consistent with most of Annex F and is hence the chosen style.

-> No comma now appears before the domain qualification for a special case

Given a pair of functions 'cf()' and its inverse 'caf()', e.g. ccosh() and
cacosh(), where both accept a complex argument and return a complex result,
if

 	cf ( NaN + i 0 ) = NaN + i  0 .........(1)

and does not raise a floating-point exception, then, by definition, the inverse

 	caf ( NaN + i 0 ) = NaN + i 0 .........(2)

and by assumption, it too does not raise a floating-point exception.

Annex G forgot this mathematical definition and returns NaN + i NaN for
both 'cacosh' and 'catanh'.  It also chose to raise the floating-point
exception for these cases which is inconsistent.

-> A 'NaN + i 0' argument will be correctly and consistently handled

The above scenario also happens for an argument of '+0 + i NAN' passed
to 'casinh'.  The same solution applies.

-> A '0 + i NaN' argument will be correctly and consistently handled

For functions which satisfy:

 	f(conj(z))  = conj(f(z))

Annex G says it only provides special case specifications for such functions
in the upper half of the complex half-plane because any cases in the lower
half of the complex half-plane are implied by that conjugate rule.  Not all
special cases are consistent with this approach.

-> Complex half plane special cases are now handled consistently

If anybody has any comments, suggestions or objections to those '->' 
approaches, please let me know.

I will post the changes subsequently after a bit more QA on the extensive 
list by Jerome and Jim.

Thanks - Damian