1<tgmath.h>(P) POSIX Programmer's Manual <tgmath.h>(P)
2
6 tgmath.h - type-generic macros
7
9 #include <tgmath.h>
10
12 The <tgmath.h> header shall include the headers <math.h> and <com‐
13 plex.h> and shall define several type-generic macros.
14 Of the functions contained within the <math.h> and <complex.h> headers
16 without an f ( float) or l ( long double) suffix, several have one or
17 more parameters whose corresponding real type is double. For each such
18 function, except modf(), there shall be a corresponding type-generic
19 macro. The parameters whose corresponding real type is double in the
20 function synopsis are generic parameters. Use of the macro invokes a
21 function whose corresponding real type and type domain are determined
22 by the arguments for the generic parameters.
23 Use of the macro invokes a function whose generic parameters have the
25 corresponding real type determined as follows:
26 * First, if any argument for generic parameters has type long double,
28 the type determined is long double.
29 * Otherwise, if any argument for generic parameters has type double or
31 is of integer type, the type determined is double.
32 * Otherwise, the type determined is float.
34 For each unsuffixed function in the <math.h> header for which there is
36 a function in the <complex.h> header with the same name except for a c
37 prefix, the corresponding type-generic macro (for both functions) has
38 the same name as the function in the <math.h> header. The corresponding
39 type-generic macro for fabs() and cabs() is fabs().
40 <math.h> <complex.h> Type-Generic
42 Function Function Macro
43 acos() cacos() acos()
44 asin() casin() asin()
45 atan() catan() atan()
46 acosh() cacosh() acosh()
47 asinh() casinh() asinh()
48 atanh() catanh() atanh()
49 cos() ccos() cos()
50 sin() csin() sin()
51 tan() ctan() tan()
52 cosh() ccosh() cosh()
53 sinh() csinh() sinh()
54 tanh() ctanh() tanh()
55 exp() cexp() exp()
56 log() clog() log()
57 pow() cpow() pow()
58 sqrt() csqrt() sqrt()
59 fabs() cabs() fabs()
60 If at least one argument for a generic parameter is complex, then use
62 of the macro invokes a complex function; otherwise, use of the macro
63 invokes a real function.
64 For each unsuffixed function in the <math.h> header without a c-pre‐
66 fixed counterpart in the <complex.h> header, the corresponding type-
67 generic macro has the same name as the function. These type-generic
68 macros are:
69
80 If all arguments for generic parameters are real, then use of the macro
83 invokes a real function; otherwise, use of the macro results in unde‐
84 fined behavior.
85 For each unsuffixed function in the <complex.h> header that is not a c-
87 prefixed counterpart to a function in the <math.h> header, the corre‐
88 sponding type-generic macro has the same name as the function. These
89 type-generic macros are:
90 carg()
93 cimag()
94 conj()
95 cproj()
96 creal()
97 Use of the macro with any real or complex argument invokes a complex
99 function.
100 The following sections are informative.
102
104 With the declarations:
105 #include <tgmath.h>
108 int n;
109 float f;
110 double d;
111 long double ld;
112 float complex fc;
113 double complex dc;
114 long double complex ldc;
115 functions invoked by use of type-generic macros are shown in the fol‐
117 lowing table:
118 Macro Use Invokes
120 exp(n) exp(n), the function
121 acosh(f) acoshf(f)
122 sin(d) sin(d), the function
123 atan(ld) atanl(ld)
124 log(fc) clogf(fc)
125 sqrt(dc) csqrt(dc)
126 pow(ldc,f) cpowl(ldc, f)
127 remainder(n,n) remainder(n, n), the function
128 nextafter(d,f) nextafter(d, f), the function
129 nexttoward(f,ld) nexttowardf(f, ld)
130 copysign(n,ld) copysignl(n, ld)
131 ceil(fc) Undefined behavior
132 rint(dc) Undefined behavior
134 fmax(ldc,ld) Undefined behavior
135 carg(n) carg(n), the function
136 cproj(f) cprojf(f)
137 creal(d) creal(d), the function
138 cimag(ld) cimagl(ld)
139 cabs(fc) cabsf(fc)
140 carg(dc) carg(dc), the function
141 cproj(ldc) cprojl(ldc)
142
144 Type-generic macros allow calling a function whose type is determined
145 by the argument type, as is the case for C operators such as '+' and
146 '*' . For example, with a type-generic cos() macro, the expression
147 cos(( float) x) will have type float. This feature enables writing
148 more portably efficient code and alleviates need for awkward casting
149 and suffixing in the process of porting or adjusting precision. Generic
150 math functions are a widely appreciated feature of Fortran.
151 The only arguments that affect the type resolution are the arguments
153 corresponding to the parameters that have type double in the synopsis.
154 Hence the type of a type-generic call to nexttoward(), whose second
155 parameter is long double in the synopsis, is determined solely by the
156 type of the first argument.
157 The term "type-generic" was chosen over the proposed alternatives of
159 intrinsic and overloading. The term is more specific than intrinsic,
160 which already is widely used with a more general meaning, and reflects
161 a closer match to Fortran's generic functions than to C++ overloading.
162 The macros are placed in their own header in order not to silently
164 break old programs that include the <math.h> header; for example, with:
165 printf ("%e", sin(x))
168 modf( double, double *) is excluded because no way was seen to make it
170 safe without complicating the type resolution.
171 The implementation might, as an extension, endow appropriate ones of
173 the macros that IEEE Std 1003.1-2001 specifies only for real arguments
174 with the ability to invoke the complex functions.
175 IEEE Std 1003.1-2001 does not prescribe any particular implementation
177 mechanism for generic macros. It could be implemented simply with
178 built-in macros. The generic macro for sqrt(), for example, could be
179 implemented with:
180 #undef sqrt
183 #define sqrt(x) __BUILTIN_GENERIC_sqrt(x)
184 Generic macros are designed for a useful level of consistency with C++
186 overloaded math functions.
187 The great majority of existing C programs are expected to be unaffected
189 when the <tgmath.h> header is included instead of the <math.h> or <com‐
190 plex.h> headers. Generic macros are similar to the ISO/IEC 9899:1999
191 standard library masking macros, though the semantic types of return
192 values differ.
193 The ability to overload on integer as well as floating types would have
195 been useful for some functions; for example, copysign(). Overloading
196 with different numbers of arguments would have allowed reusing names;
197 for example, remainder() for remquo(). However, these facilities would
198 have complicated the specification; and their natural consistent use,
199 such as for a floating abs() or a two-argument atan(), would have
200 introduced further inconsistencies with the ISO/IEC 9899:1999 standard
201 for insufficient benefit.
202 The ISO C standard in no way limits the implementation's options for
204 efficiency, including inlining library functions.
205
207 None.
208
210 <math.h> , <complex.h> , the System Interfaces volume of
211 IEEE Std 1003.1-2001, cabs(), fabs(), modf()
212
214 Portions of this text are reprinted and reproduced in electronic form
215 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
216 -- Portable Operating System Interface (POSIX), The Open Group Base
217 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
218 Electrical and Electronics Engineers, Inc and The Open Group. In the
219 event of any discrepancy between this version and the original IEEE and
220 The Open Group Standard, the original IEEE and The Open Group Standard
221 is the referee document. The original Standard can be obtained online
222 at http://www.opengroup.org/unix/online.html .
223IEEE/The Open Group 2003 <tgmath.h>(P)