tgmath.h.html

IEEE 1003.1-2003, Single Unix Specification v3

</td>
<td align="left">
<p class="tent"><br>
<a href="../functions/remainder.html"><i>remainder</i>()</a><br>
<a href="../functions/remquo.html"><i>remquo</i>()</a><br>
<a href="../functions/rint.html"><i>rint</i>()</a><br>
<a href="../functions/round.html"><i>round</i>()</a><br>
<a href="../functions/scalbn.html"><i>scalbn</i>()</a><br>
<a href="../functions/scalbln.html"><i>scalbln</i>()</a><br>
<a href="../functions/tgamma.html"><i>tgamma</i>()</a><br>
<a href="../functions/trunc.html"><i>trunc</i>()</a><br>
&nbsp;</p>
</td>
</tr>
</table>
</blockquote>

<p>If all arguments for generic parameters are real, then use of the macro invokes a real function; otherwise, use of the macro
results in undefined behavior.</p>

<p>For each unsuffixed function in the <a href="../basedefs/complex.h.html"><i>&lt;complex.h&gt;</i></a> header that is not a
<i>c</i>-prefixed counterpart to a function in the <a href="../basedefs/math.h.html"><i>&lt;math.h&gt;</i></a> header, the
corresponding type-generic macro has the same name as the function. These type-generic macros are:</p>

<blockquote>
<pre>
<a href="../functions/carg.html"><i>carg</i>()</a>
<a href="../functions/cimag.html"><i>cimag</i>()</a>
<a href="../functions/conj.html"><i>conj</i>()</a>
<a href="../functions/cproj.html"><i>cproj</i>()</a>
<a href="../functions/creal.html"><i>creal</i>()</a>
</pre>
</blockquote>

<p>Use of the macro with any real or complex argument invokes a complex function.</p>
</blockquote>

<hr>
<div class="box"><em>The following sections are informative.</em></div>

<h4><a name="tag_13_75_04"></a>APPLICATION USAGE</h4>

<blockquote>
<p>With the declarations:</p>

<pre>
<tt>#include &lt;tgmath.h&gt;
int n;
float f;
double d;
long double ld;
float complex fc;
double complex dc;
long double complex ldc;
</tt>
</pre>

<p>functions invoked by use of type-generic macros are shown in the following table:</p>

<table border="1" cellpadding="3">
<tr valign="top">
<th align="center">
<p class="tent"><b>Macro</b></p>
</th>
<th align="center">
<p class="tent"><b>Use Invokes</b></p>
</th>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><i>exp</i>(<i>n</i>)</p>
</td>
<td align="left">
<p class="tent"><i>exp</i>(<i>n</i>), the function</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><i>acosh</i>(<i>f</i>)</p>
</td>
<td align="left">
<p class="tent"><i>acoshf</i>(<i>f</i>)</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><i>sin</i>(<i>d</i>)</p>
</td>
<td align="left">
<p class="tent"><i>sin</i>(<i>d</i>), the function</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><i>atan</i>(<i>ld</i>)</p>
</td>
<td align="left">
<p class="tent"><i>atanl</i>(<i>ld</i>)</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><i>log</i>(<i>fc</i>)</p>
</td>
<td align="left">
<p class="tent"><i>clogf</i>(<i>fc</i>)</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><i>sqrt</i>(<i>dc</i>)</p>
</td>
<td align="left">
<p class="tent"><i>csqrt</i>(<i>dc</i>)</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><i>pow</i>(<i>ldc,f</i>)</p>
</td>
<td align="left">
<p class="tent"><i>cpowl</i>(<i>ldc, f</i>)</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><i>remainder</i>(<i>n,n</i>)</p>
</td>
<td align="left">
<p class="tent"><i>remainder</i>(<i>n, n</i>), the function</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><i>nextafter</i>(<i>d,f</i>)</p>
</td>
<td align="left">
<p class="tent"><i>nextafter</i>(<i>d, f</i>), the function</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><i>nexttoward</i>(<i>f,ld</i>)</p>
</td>
<td align="left">
<p class="tent"><i>nexttowardf</i>(<i>f, ld</i>)</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><i>copysign</i>(<i>n,ld</i>)</p>
</td>
<td align="left">
<p class="tent"><i>copysignl</i>(<i>n, ld</i>)</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><i>ceil</i>(<i>fc</i>)</p>
</td>
<td align="left">
<p class="tent">Undefined behavior</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><i>rint</i>(<i>dc</i>)</p>
</td>
<td align="left">
<p class="tent">Undefined behavior</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><i>fmax</i>(<i>ldc,ld</i>)</p>
</td>
<td align="left">
<p class="tent">Undefined behavior</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><i>carg</i>(<i>n</i>)</p>
</td>
<td align="left">
<p class="tent"><i>carg</i>(<i>n</i>), the function</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><i>cproj</i>(<i>f</i>)</p>
</td>
<td align="left">
<p class="tent"><i>cprojf</i>(<i>f</i>)</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><i>creal</i>(<i>d</i>)</p>
</td>
<td align="left">
<p class="tent"><i>creal</i>(<i>d</i>), the function</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><i>cimag</i>(<i>ld</i>)</p>
</td>
<td align="left">
<p class="tent"><i>cimagl</i>(<i>ld</i>)</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><i>cabs</i>(<i>fc</i>)</p>
</td>
<td align="left">
<p class="tent"><i>cabsf</i>(<i>fc</i>)</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><i>carg</i>(<i>dc</i>)</p>
</td>
<td align="left">
<p class="tent"><i>carg</i>(<i>dc</i>), the function</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><i>cproj</i>(<i>ldc</i>)</p>
</td>
<td align="left">
<p class="tent"><i>cprojl</i>(<i>ldc</i>)</p>
</td>
</tr>
</table>
</blockquote>

<h4><a name="tag_13_75_05"></a>RATIONALE</h4>

<blockquote>
<p>Type-generic macros allow calling a function whose type is determined by the argument type, as is the case for C operators such
as <tt>'+'</tt> and <tt>'*'</tt> . For example, with a type-generic <a href="../functions/cos.html"><i>cos</i>()</a> macro, the
expression <i>cos</i>(( <b>float</b>) <i>x</i>) will have type <b>float</b>. This feature enables writing more portably efficient
code and alleviates need for awkward casting and suffixing in the process of porting or adjusting precision. Generic math functions
are a widely appreciated feature of Fortran.</p>

<p>The only arguments that affect the type resolution are the arguments corresponding to the parameters that have type
<b>double</b> in the synopsis. Hence the type of a type-generic call to <a href=
"../functions/nexttoward.html"><i>nexttoward</i>()</a>, whose second parameter is <b>long double</b> in the synopsis, is determined
solely by the type of the first argument.</p>

<p>The term &quot;type-generic&quot; was chosen over the proposed alternatives of intrinsic and overloading. The term is more specific than
intrinsic, which already is widely used with a more general meaning, and reflects a closer match to Fortran's generic functions
than to C++ overloading.</p>

<p>The macros are placed in their own header in order not to silently break old programs that include the <a href=
"../basedefs/math.h.html"><i>&lt;math.h&gt;</i></a> header; for example, with:</p>

<pre>
<tt>printf ("%e", sin(x))
</tt>
</pre>

<p><i>modf</i>( <b>double</b>, <b>double *</b>) is excluded because no way was seen to make it safe without complicating the type
resolution.</p>

<p>The implementation might, as an extension, endow appropriate ones of the macros that IEEE&nbsp;Std&nbsp;1003.1-2001 specifies
only for real arguments with the ability to invoke the complex functions.</p>

<p>IEEE&nbsp;Std&nbsp;1003.1-2001 does not prescribe any particular implementation mechanism for generic macros. It could be
implemented simply with built-in macros. The generic macro for <a href="../functions/sqrt.html"><i>sqrt</i>()</a>, for example,
could be implemented with:</p>

<pre>
<tt>#undef sqrt
#define sqrt(x) __BUILTIN_GENERIC_sqrt(x)
</tt>
</pre>

<p>Generic macros are designed for a useful level of consistency with C++ overloaded math functions.</p>

<p>The great majority of existing C programs are expected to be unaffected when the <i>&lt;tgmath.h&gt;</i> header is included
instead of the <a href="../basedefs/math.h.html"><i>&lt;math.h&gt;</i></a> or <a href=
"../basedefs/complex.h.html"><i>&lt;complex.h&gt;</i></a> headers. Generic macros are similar to the ISO/IEC&nbsp;9899:1999
standard library masking macros, though the semantic types of return values differ.</p>

<p>The ability to overload on integer as well as floating types would have been useful for some functions; for example, <a href=
"../functions/copysign.html"><i>copysign</i>()</a>. Overloading with different numbers of arguments would have allowed reusing
names; for example, <a href="../functions/remainder.html"><i>remainder</i>()</a> for <a href=
"../functions/remquo.html"><i>remquo</i>()</a>. However, these facilities would have complicated the specification; and their
natural consistent use, such as for a floating <a href="../functions/abs.html"><i>abs</i>()</a> or a two-argument <a href=
"../functions/atan.html"><i>atan</i>()</a>, would have introduced further inconsistencies with the ISO/IEC&nbsp;9899:1999 standard
for insufficient benefit.</p>

<p>The ISO&nbsp;C standard in no way limits the implementation's options for efficiency, including inlining library functions.</p>
</blockquote>

<h4><a name="tag_13_75_06"></a>FUTURE DIRECTIONS</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_13_75_07"></a>SEE ALSO</h4>

<blockquote>
<p><a href="math.h.html"><i>&lt;math.h&gt;</i></a> , <a href="complex.h.html"><i>&lt;complex.h&gt;</i></a> , the System Interfaces
volume of IEEE&nbsp;Std&nbsp;1003.1-2001, <a href="../functions/cabs.html"><i>cabs</i>()</a>, <a href=
"../functions/fabs.html"><i>fabs</i>()</a>, <a href="../functions/modf.html"><i>modf</i>()</a></p>
</blockquote>

<h4><a name="tag_13_75_08"></a>CHANGE HISTORY</h4>

<blockquote>
<p>First released in Issue 6. Included for alignment with the ISO/IEC&nbsp;9899:1999 standard.</p>
</blockquote>

<div class="box"><em>End of informative text.</em></div>

<hr>
<hr size="2" noshade>
<center><font size="2"><!--footer start-->
UNIX &reg; is a registered Trademark of The Open Group.<br>
POSIX &reg; is a registered Trademark of The IEEE.<br>
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
]</font></center>

<!--footer end-->
<hr size="2" noshade>
</body>
</html>