SC22/WG14 N820 Splitting Annex G Clive D.W. Feather clive@demon.net 1998-04-15 Abstract ======== In the UK response to CD1 the UK suggested splitting Annex G into two parts. Annex G currently gives a specification for IEC 559 compatible complex types *and* for imaginary types, all conflated. These are separate concepts which can each be useful, and should be separated. This paper proposes new wording to this end. Conceptual changes ================== Annex G is split into two annexes, GI and GC. The former consists of the old G.2, G.3, and G.6, while the latter consists of G.5 (except one paragraph). G.1 and G.4 are divided between the two. Both annexes are normative. Wherever text appears here without a change bar, it is taken directly from CD1. Other references to Annex G are as follows: FN28 and FN186 should refer to GI. 6.8.8 and 7.8.2.1 should refer to GC. K.1 should refer to GC.3. New wording =========== | Annex GI | (normative) | Imaginary Types GI.1 Introduction | [#1] This annex specifies imaginary types. An implementation shall | either conform to all the requirements of this annex, and shall define | the macro _Imaginary_I in <complex.h>, or it shall not provide such | types and shall not define _Imaginary_I. GI.2 Types [#1] There are three imaginary types, designated as float | _Imaginary, double _Imaginary, and long double _Imaginary. The imaginary types (along with the real floating and complex types) are floating types. [#2] For imaginary types, the corresponding real type is given by | deleting the keyword _Imaginary from the type name. [#3] Each imaginary type has the same representation and alignment requirements as the corresponding real type. The value of an object of imaginary type is the value of the real representation times the imaginary unit. [#4] The imaginary type-domain comprises the imaginary types. GI.3 Conversions GI.3.1 Imaginary types [#1] Conversions among imaginary types follow rules analogous to those for real floating types. GI.3.2 Real and imaginary [#1] When a value of imaginary type is converted to a real type, the result is a positive zero. [#2] When a value of real type is converted to an imaginary type, the result is a positive imaginary zero. GI.3.3 Imaginary and complex [#1] When a value of imaginary type is converted to a complex type, the real part of the complex result value is a positive zero and the imaginary part of the complex result value is determined by the conversion rules for the corresponding real types. [#2] When a value of complex type is converted to an imaginary type, the real part of the complex value is discarded and the value of the imaginary part is converted according to the conversion rules for the corresponding real types. GI.4 Binary operators [#1] The following subclauses supplement 6.3 in order to specify the type of the result for an operation with an imaginary operand. | [#2] For the multiplicative operators, if one operand has real type and the other operand has imaginary type, then the result has imaginary type. If both operands have imaginary type, then the result has real type. (If either operand has complex type, then the result has complex type.) | [#3] For the additive operators, if one operand has real type and the other operand has imaginary type, then the result has complex type. If both operands have imaginary type, then the result has imaginary type. (If either operand has complex type, then the result has complex type.) GI.5 <complex.h> [#1] The macro _Imaginary_I is defined, and the macro I is defined to be _Imaginary_I (7.8). GI.6 <tgmath.h> [#1] Type-generic macros that accept complex arguments also accept imaginary arguments. If an argument is imaginary, the macro expands to an expression whose type is real, imaginary, or complex, as appropriate for the particular function: if the argument is imaginary, then the types of cos, cosh, fabs, carg, cimag, and creal are real; the types of sin, tan, sinh, tanh, asin, atan, asinh, and atanh are imaginary; and the types of the others are complex. [#2] Given an imaginary argument, each of the type-generic macros cos, sin, tan, cosh, sinh, tanh, asin, atan, asinh, atanh is specified by a formula in terms of real functions: cos(i*y) = cosh(y) sin(i*y) = i*sinh(y) tan(i*y) = i*tanh(y) cosh(i*y) = cos(y) sinh(i*y) = i*sin(y) tanh(i*y) = i*tan(y) asin(i*y) = i*asinh(y) atan(i*y) = i*atanh(y) asinh(i*y) = i*asin(y) atanh(i*y) = i*atan(y) | Annex GC | (normative) | IEC 559-compatible complex arithmetic GC.1 Introduction | [#1] This annex supplements Annex F to specify complex arithmetic | for compatibility with IEC 559 real floating-point arithmetic. | An implementation that defines __STDC_IEC_559_COMPLEX__ conforms to the | specification in this annex. Where a binding between the C language and | IEC 559 is indicated, the IEC 559-specified behavior is adopted by | reference, unless stated otherwise. GC.2 Binary operators [#1] For most operand types, the value of the result of a binary operator with an imaginary or complex operand is completely determined, with reference to real arithmetic, by the usual mathematical formula. For some operand types, the usual mathematical formula is problematic because of its treatment of infinities and because of undue overflow or underflow; in these cases the result satisfies certain properties (specified in this subclause), but is not completely determined. GC.2.1 Multiplicative operators Semantics [#1] If the operands are not both complex, then the result and exception behavior of the * operator is defined by the usual mathematical formula: [[table omitted]] [#2] If the second operand is not complex, then the result and exception behavior of the / operator is defined by the usual mathematical formula: [[table omitted]] [#3] A complex or imaginary value with at least one infinite part is regarded as an infinity (even if its other part is a NaN). A complex or imaginary value is a finite number if each of its parts is a finite number (neither infinite nor NaN). A complex or imaginary value is a zero if each of its parts is a zero. The * and / operators satisfy the following infinity properties for all real, imaginary, and complex operands:289 - if one operand is an infinity and the other operand is a nonzero finite number or an infinity, then the result of the * operator is an infinity; - if the first operand is an infinity and the second operand is a finite number, then the result of the / operator is an infinity; - if the first operand is a finite number and the second operand is an infinity, then the result of the / operator is a zero; - if the first operand is a nonzero finite number or an infinity and the second operand is a zero, then the result of the / operator is an infinity. [#4] If both operands of the * operator are complex or if the second operand of the / operator is complex, the operator raises exceptions if appropriate for the calculation of the parts of the result, and may raise spurious exceptions. Examples [#5] 1. Multiplication of double complex operands could be implemented as follows. Note that the imaginary unit I has imaginary type (see GC.3). #include <math.h> #include <complex.h> /* Multiply z * w ... */ double complex _Cmultd(double complex z, double complex w) { #pragma STDC FP_CONTRACT OFF double a, b, c, d, ac, bd, ad, bc, x, y; a = creal(z); b = cimag(z) c = creal(w); d = cimag(w); ac = a * c; bd = b * d; ad = a * d; bc = b * c; x = ac - bd; y = ad + bc; /* Recover infinities that computed as NaN+iNaN ... */ if (isnan(x) && isnan(y)) { int recalc = 0; if ( isinf(a) || isinf(b) ) { /* z is infinite */ /* "Box" the infinity ... */ a = copysign(isinf(a) ? 1.0 : 0.0, a); b = copysign(isinf(b) ? 1.0 : 0.0, b); /* Change NaNs in the other factor to 0 ... */ if (isnan(c)) c = copysign(0.0, c); if (isnan(d)) d = copysign(0.0, d); recalc = 1; } if ( isinf(c) || isinf(d) ) { /* w is infinite */ /* "Box" the infinity ... */ c = copysign(isinf(c) ? 1.0 : 0.0, c); d = copysign(isinf(d) ? 1.0 : 0.0, d); /* Change NaNs in the other factor to 0 ... */ if (isnan(a)) a = copysign(0.0, a); if (isnan(b)) b = copysign(0.0, b); recalc = 1; } if (!recalc) { /* *Recover infinities from overflow cases ... */ if (isinf(ac) || isinf(bd) || isinf(ad) || isinf(bc)) { /* Change all NaNs to 0 ... */ if (isnan(a)) a = copysign(0.0, a); if (isnan(b)) b = copysign(0.0, b); if (isnan(c)) c = copysign(0.0, c); if (isnan(d)) d = copysign(0.0, d); recalc = 1; } } if (recalc) { x = INFINITY * ( a * c - b * d ); y = INFINITY * ( a * d + b * c ); } } return x + I * y; } In ordinary (finite) cases, the cost to satisfy the infinity property for the * operator is only one isnan test. This implementation opts for performance over guarding against undue overflow and underflow. 2. Division of two double complex operands could be implemented as follows. #include <math.h> #include <complex.h> /* Divide z / w ... */ double complex _Cdivd(double complex z, double complex w) { #pragma STDC FP_CONTRACT OFF double a, b, c, d, logbw, denom, x, y; int ilogbw = 0; a = creal(z); b = cimag(z); c = creal(w); d = cimag(w); logbw = logb(fmax(fabs(c), fabs(d))); if (isfinite(logbw)) { ilogbw = (int)logbw; c = scalbn(c, -ilogbw); d = scalbn(d, -ilogbw); } denom = c * c + d * d; x = scalbn((a * c + b * d) / denom, -ilogbw); y = scalbn((b * c - a * d) / denom, -ilogbw); /* * Recover infinities and zeros that computed * as NaN+iNaN; the only cases are non-zero/zero, * infinite/finite, and finite/infinite, ... */ if (isnan(x) && isnan(y)) { if ((denom == 0.0) && (!isnan(a) || !isnan(b))) { x = copysign(INFINITY, c) * a; y = copysign(INFINITY, c) * b; } else if ((isinf(a) || isinf(b)) && isfinite(c) && isfinite(d)) { a = copysign(isinf(a) ? 1.0 : 0.0, a); b = copysign(isinf(b) ? 1.0 : 0.0, b); x = INFINITY * ( a * c + b * d ); y = INFINITY * ( b * c - a * d ); } else if (isinf(logbw) && isfinite(a) && isfinite(b)) { c = copysign(isinf(c) ? 1.0 : 0.0, c); d = copysign(isinf(d) ? 1.0 : 0.0, d); x = 0.0 * ( a * c + b * d ); y = 0.0 * ( b * c - a * d ); } } return x + I * y; } [#6] Scaling the denominator alleviates the main overflow and underflow problem, which is more serious than for multiplication. In the spirit of the multiplication example above, this code does not defend against overflow and underflow in the calculation of the numerator. Scaling with the scalbn function, instead of with division, provides better roundoff characteristics. GC.2.2 Additive operators Semantics [#1] In all cases the result and exception behavior of a + or - operator is defined by the usual mathematical formula: [[table omitted]] GC.3 <complex.h> [#1] This subclause contains specification for the <complex.h> functions that is particularly suited to IEC 559 implementations. [#2] The functions are continuous onto both sides of their branch cuts, taking into account the sign of zero. For example, csqrt( -2 _ 0*I) == _sqrt(2)*I. [#3] Since complex and imaginary values are composed of real values, each function may be regarded as computing real values from real values. Except as noted, the functions treat real infinities, NaNs, signed zeros, subnormals, and the exception flags in a manner consistent with the specification for real functions in F.9. [#4] The functions conj, cimag, cproj, and creal are fully specified for all implementations, including IEC 559 ones, in 7.9.2. These functions raise no exceptions. [#5] Each of the functions cabs and carg is specified by a formula in terms of a real function (whose special cases are covered in annex F): cabs(x + i*y) = hypot(x, y) carg(x + i*y) = atan2(y, x) [#6] Each of the functions casin, catan, ccos, csin, ctan, and cpow is specified implicitly by a formula in terms of other complex functions (whose special cases are specified below): casin(z) = -i*casinh(i*z) catan(z) = -i*catanh(i*z) ccos(z) = ccosh(i*z) csin(z) = -i*csinh(i*z) ctan(z) = -i*ctanh(i*z) cpow(z, c) = cexp(c * clog(z)) [#7] For the other functions, the following subclauses specify behavior for special cases, including treatment of the invalid and divide-by-zero exceptions. For a function f satisfying f(conj(z)) = conj(f(z)), the specification for the upper half- plane implies the specification for the lower half-plane; if also the function f is either even, f(-z) = f(z), or odd, f(-z) = -f(z), then the specification for the first quadrant implies the specification for the other three quadrants. GC.3.1 The cacos function [#1] - cacos(conj(z)) = conj(cacos(z)). - cacos(_0+i0) returns pi/2-i0. - cacos(-oo+ioo) returns 3pi/4-ioo. - cacos(+oo+ioo) returns pi/4-ioo. - cacos(x+ioo) returns pi/2-ioo, for finite x. - cacos(-oo+iy) returns pi-ioo, for positive-signed finite y. - cacos(+oo+iy) returns +0-ioo, for positive-signed finite y. - cacos(_oo+iNAN) returns NaN_i oo (where the sign of the imaginary part of the result is unspecified). - cacos(_0+iNAN) returns pi/2+iNaN. - cacos(NAN+ioo) returns NaN-ioo. - cacos(x+iNAN) returns NaN+iNaN and optionally raises the invalid exception, for nonzero finite x. - cacos(NAN+iy) returns NaN+iNaN and optionally raises the invalid exception, for finite y. - cacos(NAN+iNAN) returns NaN+iNaN. GC.3.2 The cacosh function [#1] - cacosh(conj(z)) = conj(cacosh(z)). - cacosh(_0+i0) returns +0+ipi/2. - cacosh(-oo+ioo) returns +oo+i3pi/4. - cacosh(+oo+ioo) returns +oo+ipi/4. - cacosh(x+ioo) returns +oo+ipi/2, for finite x. - cacosh(-oo+iy) returns +oo+ipi, for positive-signed finite y. - cacosh(+oo+iy) returns +oo+i0, for positive-signed finite y. - cacosh(NAN+ioo) returns +oo+iNaN. - cacosh(_oo+iNAN) returns +oo+iNaN. - cacosh(x+iNAN) returns NaN+iNaN and optionally raises the invalid exception, for finite x. - cacosh(NAN+iy) returns NaN+iNaN and optionally raises the invalid exception, for finite y. - cacosh(NAN+iNAN) returns NaN+iNaN. GC.3.3 The casinh function - casinh(conj(z)) = conj(casinh(z)) and casinh is odd. - casinh(+0+i0) returns 0+i0. - casinh(oo+ioo) returns +oo+ipi/4. - casinh(x+ioo) returns +oo+ipi/2 for positive-signed finite x. - casinh(+oo+iy) returns +oo+i0 for positive-signed finite y. - casinh(NAN+ioo) returns _oo+iNaN (where the sign of the real part of the result is unspecified). - casinh(+oo+iNAN) returns +oo+iNaN. - casinh(NAN+i0) returns NaN+i0. - casinh(NAN+iy) returns NaN+iNaN and optionally raises the invalid exception, for finite nonzero y. - casinh(x+iNAN) returns NaN+iNaN and optionally raises the invalid exception, for finite x. - casinh(NAN+iNAN) returns NaN+iNaN. GC.3.4 The catanh function [#1] - catanh(conj(z)) = conj(catanh(z))and catanh is odd. - catanh(+0+i0) returns +0+i0. - catanh(+oo+ioo) returns +0+ipi/2. - catanh(+oo+iy) returns +0+ipi/2, for finite positive-signed y. - catanh(x+ioo) returns +0+ipi/2, for finite positive-signed x. - catanh(+0+iNAN) returns +0+iNaN. - catanh(NAN+ioo) returns _0+ipi/2 (where the sign of the real part of the result is unspecified). - catanh(+oo+iNAN) returns +0+iNaN. - catanh(NAN+iy) returns NaN+iNaN and optionally raises the invalid exception, for finite y. - catanh(x+iNAN) returns NAN+iNAN and optionally raises the invalid exception for nonzero finite x. - catanh(NAN+iNAN) returns NaN+iNaN. GC.3.5 The ccosh function [#1] - ccosh(conj(z)) = conj(ccosh(z)) and ccosh is even. - ccosh(+0+i0) returns 1+i0. - ccosh(+0+ioo) returns NaN _ i0 (where the sign of the imaginary part of the result is unspecified) and raises the invalid exception. - ccosh(+oo+i0) returns +oo+i0. - ccosh(+oo+ioo) returns +oo + iNaN and raises the invalid exception. - ccosh(x+ioo) returns NaN + iNaN and raises the invalid exception, for finite nonzero x. - ccosh(+oo+iy) returns (+oo)*cis(y), for finite nonzero y.290 - ccosh(+0+iNaN) returns NaN _ i0 (where the sign of the imaginary part of the result is unspecified). - ccosh(+oo+iNaN) returns +oo+iNaN. - ccosh(x+iNAN) returns NaN+iNaN and optionally raises the invalid exception, for finite nonzero x. - ccosh(NAN+i0) returns NaN _ i0 (where the sign of the imaginary part of the result is unspecified). - ccosh(NAN+iy) returns NAN+iNAN and optionally raises the invalid exception, for all nonzero numbers y. - ccosh(NAN+iNAN) returns NaN+iNaN. GC.3.6 The csinh function [#1] - csinh(conj(z)) = conj(csinh(z)) and csinh is odd. - csinh(+0+i0) returns +0+i0. - csinh(+0+ioo) returns _0+iNaN (where the sign of the real part of the result is unspecified) and raises the invalid exception. - csinh(+oo+i0) returns +oo+i0. - csinh(+oo+ioo) returns _oo+iNaN (where the sign of the real part of the result is unspecified) and raises the invalid exception. - csinh(+oo+iy) returns (+oo)*cis(y), for positive finite y. - csinh(x+ioo) returns NaN + iNaN and raises the invalid exception, for positive finite x. - csinh(+0+iNAN) returns _0+iNaN (where the sign of the real part of the result is unspecified). - csinh(+oo+iNAN) returns _oo+iNaN (where the sign of the real part of the result is unspecified). - csinh(x+iNAN) returns NaN+iNaN and optionally raises the invalid exception, for finite nonzero x. - csinh(NAN+i0) returns NaN+i0. - csinh(NAN+iy) returns NaN+iNaN and optionally raises the invalid exception, for all nonzero numbers y. - csinh(NAN+iNAN) returns NaN+iNaN. GC.3.7 The ctanh function [#1] - ctanh(conj(z)) = conj(ctanh(z))and ctanh is odd. - ctanh(+0+i0) returns +0+i0. - ctanh(+oo+iy) returns 1+i0, for all positive-signed numbers y. - ctanh(x+ioo) returns NaN + iNaN and raises the invalid exception, for finite x. - ctanh(+oo+iNAN) returns 1 _ i0 (where the sign of the imaginary part of the result is unspecified). - ctanh(NAN+i0) returns NaN+i0. - ctanh(NAN+iy) returns NaN+iNaN and optionally raises the invalid exception, for all nonzero numbers y. - ctanh(x+iNAN) returns NaN+iNaN and optionally raises the invalid exception, for finite x. - ctanh(NAN+iNAN) returns NaN+iNaN. GC.3.8 The cexp function [#1] - cexp(conj(z)) = conj(cexp(z)). - cexp(_0+i0) returns 1+i0. - cexp(+oo+i0) returns +oo+i0. - cexp(-oo+ioo) returns _0_i0 (where the signs of the real and imaginary parts of the result are unspecified). - cexp(+oo+ioo) returns _ oo + iNaN and raises the invalid exception (where the sign of the real part of the result is unspecified). - cexp(x+ioo ) returns NaN + iNaN and raises the invalid exception, for finite x. - cexp(-oo+iy) returns +0*cis(y), for finite y. - cexp(+oo+iy) returns +oo*cis(y), for finite nonzero y. - cexp(-oo+iNAN) returns _0_i0 (where the signs of the real and imaginary parts of the result are unspecified). - cexp(+oo+iNAN) returns _oo+iNaN (where the sign of the real part of the result is unspecified). - cexp(NAN+i0) returns NaN+i0. - cexp(NAN+iy) returns NaN+ iNaN and optionally raises the invalid exception, for all non-zero numbers y. - cexp(x+iNAN) returns NaN+ iNaN and optionally raises the invalid exception, for finite x. - cexp(NAN+iNAN) returns NaN+iNaN. GC.3.9 The clog function [#1] - clog(conj(z)) = conj(clog(z)). - clog(-0+i0) returns -oo+ipi and raises the divide-by-zero exception. - clog(+0+i0) returns -oo+i0 and raises the divide-by-zero exception. - clog(-oo+ioo) returns +oo+i3pi/4. - clog(+oo+ioo) returns +oo+ipi/4. - clog(x+ioo) returns +oo+ipi/2, for finite x. - clog(-oo+iy) returns +oo+ipi, for finite positive-signed y. - clog(+oo+iy) returns +oo+i0, for finite positive-signed y. - clog(_oo+iNAN) returns +oo+iNaN. - clog(NAN+ioo) returns +oo+iNaN. - clog(x+iNAN) returns NaN+ iNaN and optionally raises the invalid exception, for finite x. - clog(NAN+iy) returns NaN+ iNaN and optionally raises the invalid exception, for finite y. - clog(NAN+iNAN) returns NaN+iNaN. GC.3.10 The csqrt function [#1] - csqrt(conj(z)) = conj(csqrt(z)). - csqrt(_0+i0) returns +0+i0. - csqrt(-oo+iy) returns +0+ioo, for finite positive-signed y. - csqrt(+oo+iy) returns +oo+i0, for finite positive-signed y. - csqrt(x+ioo) returns +oo+ioo, for all x (including NaN). - csqrt(-oo+iNAN) returns NaN_i oo (where the sign of the imaginary part of the result is unspecified). - csqrt(+oo+iNAN) returns +oo+iNaN. - csqrt(x+iNAN) returns NaN+iNaN and optionally raises the invalid exception, for finite x. - csqrt(NAN+iy) returns NaN+iNaN and optionally raises the invalid exception, for finite y. - csqrt(NAN+iNAN) returns NaN+iNaN. __________ 289. These properties are already implied for those cases covered in the tables, but are required for all cases (at least where the state for CX_LIMITED_RANGE is off). 290. cis(y) is defined by cos(y)+i*sin(y).