diff options
Diffstat (limited to 'libquadmath/libquadmath.texi')
| -rw-r--r-- | libquadmath/libquadmath.texi | 388 |
1 files changed, 388 insertions, 0 deletions
diff --git a/libquadmath/libquadmath.texi b/libquadmath/libquadmath.texi new file mode 100644 index 000000000..f2557c8e6 --- /dev/null +++ b/libquadmath/libquadmath.texi @@ -0,0 +1,388 @@ +\input texinfo @c -*-texinfo-*- + +@c %**start of header +@setfilename libquadmath.info +@settitle GCC libquadmath +@c %**end of header + +@copying +Copyright @copyright{} 2010 Free Software Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' +and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License.'' + +(a) The FSF's Back-Cover Text is: ``You have the freedom to +copy and modify this GNU manual. +@end quotation +@end copying + +@ifinfo +@dircategory GNU Libraries +@direntry +* libquadmath: (libquadmath). GCC Quad-Precision Math Library +@end direntry + +This manual documents the GCC Quad-Precision Math Library API. + +Published by the Free Software Foundation +51 Franklin Street, Fifth Floor +Boston, MA 02110-1301 USA + +@insertcopying +@end ifinfo + + +@setchapternewpage odd + +@titlepage +@title The GCC Quad-Precision Math Library +@page +@vskip 0pt plus 1filll +@comment For the @value{version-GCC} Version* +@sp 1 +Published by the Free Software Foundation @* +51 Franklin Street, Fifth Floor@* +Boston, MA 02110-1301, USA@* +@sp 1 +@insertcopying +@end titlepage + +@summarycontents +@contents +@page + + +@node Top +@top Introduction +@cindex Introduction + +This manual documents the usage of libquadmath, the GCC Quad-Precision +Math Library Application Programming Interface (API). + + +@comment +@comment When you add a new menu item, please keep the right hand +@comment aligned to the same column. Do not use tabs. This provides +@comment better formatting. +@comment +@menu +* Typedef and constants:: Defined data types and constants +* Math Library Routines:: The Libquadmath math runtime application + programming interface. +* I/O Library Routines:: The Libquadmath I/O runtime application + programming interface. +* GNU Free Documentation License:: + How you can copy and share this manual. +* Reporting Bugs:: How to report bugs in GCC Libquadmath. +@c * Index:: Index of this documentation. +@end menu + + +@c --------------------------------------------------------------------- +@c Defined macros +@c --------------------------------------------------------------------- + +@node Typedef and constants +@chapter Typedef and constants + +The following data type has been defined via @code{typedef}. + +@table @asis +@item @code{__complex128}: @code{__float128}-based complex number +@end table + +The following macros are defined, which give the numeric limits of the +@code{__float128} data type. + +@table @asis +@item @code{FLT128_MAX}: largest finite number +@item @code{FLT128_MIN}: smallest positive number with full precision +@item @code{FLT128_EPSILON}: difference between 1 and the next larger + representable number +@item @code{FLT128_DENORM_MIN}: smallest positive denormalized number +@item @code{FLT128_MANT_DIG}: number of digits in the mantissa (bit precision) +@item @code{FLT128_MIN_EXP}: maximal negative exponent +@item @code{FLT128_MAX_EXP}: maximal positive exponent +@item @code{FLT128_DIG}: number of decimal digits in the mantissa +@item @code{FLT128_MIN_10_EXP}: maximal negative decimal exponent +@item @code{FLT128_MAX_10_EXP}: maximal positive decimal exponent +@end table + +The following mathematical constants of type @code{__float128} are defined. + +@table @asis +@item @code{M_Eq}: the constant e (Euler's number) +@item @code{M_LOG2Eq}: binary logarithm of 2 +@item @code{M_LOG10Eq}: common, decimal logarithm of 2 +@item @code{M_LN2q}: natural logarithm of 2 +@item @code{M_LN10q}: natural logarithm of 10 +@item @code{M_PIq}: pi +@item @code{M_PI_2q}: two pi +@item @code{M_PI_4q}: four pi +@item @code{M_1_PIq}: one over pi +@item @code{M_2_PIq}: one over two pi +@item @code{M_2_SQRTPIq}: two over square root of pi +@item @code{M_SQRT2q}: square root of 2 +@item @code{M_SQRT1_2q}: one over square root of 2 +@end table + + +@c --------------------------------------------------------------------- +@c Math routines +@c --------------------------------------------------------------------- + +@node Math Library Routines +@chapter Math Library Routines + +The following mathematical functions are available: + +@table @asis +@item @code{acosq}: arc cosine function +@item @code{acoshq}: inverse hyperbolic cosine function +@item @code{asinq}: arc sine function +@item @code{asinhq}: inverse hyperbolic sine function +@item @code{atanq}: arc tangent function +@item @code{atanhq}: inverse hyperbolic tangent function +@item @code{atan2q}: arc tangent function +@item @code{cbrtq}: cube root function +@item @code{ceilq}: ceiling value function +@item @code{copysignq}: copy sign of a number +@item @code{coshq}: hyperbolic cosine function +@item @code{cosq}: cosine function +@item @code{erfq}: error function +@item @code{erfcq}: complementary error function +@item @code{expq}: exponential function +@item @code{expm1q}: exponential minus 1 function +@need 800 +@item @code{fabsq}: absolute value function +@item @code{fdimq}: positive difference function +@item @code{finiteq}: check finiteness of value +@item @code{floorq}: floor value function +@item @code{fmaq}: fused multiply and add +@item @code{fmaxq}: determine maximum of two values +@item @code{fminq}: determine minimum of two values +@item @code{fmodq}: remainder value function +@item @code{frexpq}: extract mantissa and exponent +@item @code{hypotq}: Eucledian distance function +@item @code{ilogbq}: get exponent of the value +@item @code{isinfq}: check for infinity +@item @code{isnanq}: check for not a number +@item @code{j0q}: Bessel function of the first kind, first order +@item @code{j1q}: Bessel function of the first kind, second order +@item @code{jnq}: Bessel function of the first kind, @var{n}-th order +@item @code{ldexpq}: load exponent of the value +@item @code{lgammaq}: logarithmic gamma function +@item @code{llrintq}: round to nearest integer value +@item @code{llroundq}: round to nearest integer value away from zero +@item @code{logq}: natural logarithm function +@item @code{log10q}: base 10 logarithm function +@item @code{log1pq}: compute natural logarithm of the value plus one +@item @code{log2q}: base 2 logarithm function +@need 800 +@item @code{lrintq}: round to nearest integer value +@item @code{lroundq}: round to nearest integer value away from zero +@item @code{modfq}: decompose the floating-point number +@item @code{nanq}: return quiet NaN +@item @code{nearbyintq}: round to nearest integer +@item @code{nextafterq}: next representable floating-point number +@item @code{powq}: power function +@item @code{remainderq}: remainder function +@item @code{remquoq}: remainder and part of quotient +@item @code{rintq}: round-to-nearest integral value +@item @code{roundq}: round-to-nearest integral value, return @code{__float128} +@item @code{scalblnq}: compute exponent using @code{FLT_RADIX} +@item @code{scalbnq}: compute exponent using @code{FLT_RADIX} +@item @code{signbitq}: return sign bit +@item @code{sincosq}: calculate sine and cosine simulataneously +@item @code{sinhq}: hyperbolic sine function +@item @code{sinq}: sine function +@item @code{sqrtq}: square root function +@item @code{tanq}: tangent function +@item @code{tanhq}: hyperbolic tangent function +@need 800 +@item @code{tgammaq}: true gamma function +@item @code{truncq}: round to integer, towards zero +@item @code{y0q}: Bessel function of the second kind, first order +@item @code{y1q}: Bessel function of the second kind, second order +@item @code{ynq}: Bessel function of the second kind, @var{n}-th order +@item @code{cabsq} complex absolute value function +@item @code{cargq}: calculate the argument +@item @code{cimagq} imaginary part of complex number +@item @code{crealq}: real part of complex number +@item @code{cacoshq}: complex arc hyperbolic cosine function +@item @code{cacosq}: complex arc cosine function +@item @code{casinhq}: complex arc hyperbolic sine function +@item @code{casinq}: complex arc sine function +@item @code{catanhq}: complex arc hyperbolic tangent function +@item @code{catanq}: complex arc tangent function +@item @code{ccosq} complex cosine function: +@item @code{ccoshq}: complex hyperbolic cosine function +@item @code{cexpq}: complex exponential function +@need 800 +@item @code{cexpiq}: computes the exponential function of ``i'' times a + real value +@item @code{clogq}: complex natural logarithm +@item @code{clog10q}: complex base 10 logarithm +@item @code{conjq}: complex conjugate function +@item @code{cpowq}: complex power function +@item @code{cprojq}: project into Riemann Sphere +@item @code{csinq}: complex sine function +@item @code{csinhq}: complex hyperbolic sine function +@item @code{csqrtq}: complex square root +@item @code{ctanq}: complex tangent function +@item @code{ctanhq}: complex hyperbolic tangent function +@end table + + +@c --------------------------------------------------------------------- +@c I/O routines +@c --------------------------------------------------------------------- + +@node I/O Library Routines +@chapter I/O Library Routines + +@menu +* @code{strtoflt128}: strtoflt128, Convert from string +* @code{quadmath_snprintf}: quadmath_snprintf, Convert to string +@end menu + + +@node strtoflt128 +@section @code{strtoflt128} --- Convert from string + +The function @code{dmath_strtopQ} converts a string into a +@code{__float128} number. + +@table @asis +@item Syntax +@code{__float128 strtoflt128 (const char *s, char **sp)} + +@item @emph{Arguments}: +@multitable @columnfractions .15 .70 +@item @var{s} @tab input string +@item @var{sp} @tab the address of the next character in the string +@end multitable + +The argument @var{sp} contains, if not @code{NULL}, the address of the +next character following the parts of the string, which have been read. + +@item Example +@smallexample +#include <quadmath.h> + +int main () +@{ + __float128 r; + + r = strtoflt128 ("1.2345678", NULL); + + return 0; +@} +@end smallexample +@end table + + +@node quadmath_snprintf +@section @code{quadmath_snprintf} --- Convert to string + +The function @code{quadmath_snprintf} converts a @code{__float128} floating-point +number into a string. It is a specialized alternative to @code{snprintf}, where +the format string is restricted to a single conversion specifier with @code{Q} +modifier and conversion specifier @code{e}, @code{E}, @code{f}, @code{F}, @code{g}, +@code{G}, @code{a} or @code{A}, with no extra characters before or after the +conversion specifier. The @code{%m$} or @code{*m$} style must not be used in +the format. + +@table @asis +@item Syntax +@code{int quadmath_snprintf (char *s, size_t size, const char *format, ...)} + +@item @emph{Arguments}: +@multitable @columnfractions .15 .70 +@item @var{s} @tab output string +@item @var{size} @tab byte size of the string, including tailing NUL +@item @var{format} @tab conversion specifier string +@end multitable + +@item Example +@smallexample +#include <quadmath.h> +#include <stdlib.h> +#include <stdio.h> + +int main () +@{ + __float128 r; + int prec = 20; + int width = 46; + char buf[128]; + + r = 2.0q; + r = sqrtq (r); + int n = quadmath_snprintf (buf, sizeof buf, "%+-#*.20Qe", width, r); + if ((size_t) n < sizeof buf) + printf ("%s\n", buf); + /* Prints: +1.41421356237309504880e+00 */ + quadmath_snprintf (buf, sizeof buf, "%Qa", r); + if ((size_t) n < sizeof buf) + printf ("%s\n", buf); + /* Prints: 0x1.6a09e667f3bcc908b2fb1366ea96p+0 */ + n = quadmath_snprintf (NULL, 0, "%+-#46.*Qe", prec, r); + if (n > -1) + @{ + char *str = malloc (n + 1); + if (str) + @{ + quadmath_snprintf (str, n + 1, "%+-#46.*Qe", prec, r); + printf ("%s\n", str); + /* Prints: +1.41421356237309504880e+00 */ + @} + free (str); + @} + return 0; +@} +@end smallexample + +@end table + +On some targets when supported by the C library hooks are installed +for @code{printf} family of functions, so that @code{printf ("%Qe", 1.2Q);} +etc.@: works too. + + +@c --------------------------------------------------------------------- +@c GNU Free Documentation License +@c --------------------------------------------------------------------- + +@include fdl.texi + +@c --------------------------------------------------------------------- +@c Reporting Bugs +@c --------------------------------------------------------------------- + +@c For BUGURL +@include libquadmath-vers.texi + +@node Reporting Bugs +@chapter Reporting Bugs + +Bugs in the GCC Quad-Precision Math Library implementation should be +reported via @value{BUGURL}. + + +@c --------------------------------------------------------------------- +@c Index +@c --------------------------------------------------------------------- + +@c @node Index +@c @unnumbered Index +@c +@c @printindex cp + +@bye |