libquadmath/libquadmath.texi

   1 \input texinfo @c -*-texinfo-*-
   2
   3 @c %**start of header
   4 @setfilename libquadmath.info
   5 @settitle GCC libquadmath
   6 @c %**end of header
   7
   8 @copying
   9 Copyright @copyright{} 2010-2023 Free Software Foundation, Inc.
  10
  11 @quotation
  12 Permission is granted to copy, distribute and/or modify this document
  13 under the terms of the GNU Free Documentation License, Version 1.2 or
  14 any later version published by the Free Software Foundation; with no
  15 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
  16 and with the Back-Cover Texts as in (a) below.  A copy of the
  17 license is included in the section entitled ``GNU Free Documentation
  18 License.''
  19
  20 (a) The FSF's Back-Cover Text is: ``You have the freedom to
  21 copy and modify this GNU manual.
  22 @end quotation
  23 @end copying
  24
  25 @ifinfo
  26 @dircategory GNU Libraries
  27 @direntry
  28 * libquadmath: (libquadmath).                  GCC Quad-Precision Math Library
  29 @end direntry
  30
  31 This manual documents the GCC Quad-Precision Math Library API.
  32
  33 Published by the Free Software Foundation
  34 51 Franklin Street, Fifth Floor
  35 Boston, MA 02110-1301 USA
  36
  37 @insertcopying
  38 @end ifinfo
  39
  40
  41 @setchapternewpage odd
  42
  43 @titlepage
  44 @title The GCC Quad-Precision Math Library
  45 @page
  46 @vskip 0pt plus 1filll
  47 @comment For the @value{version-GCC} Version*
  48 @sp 1
  49 Published by the Free Software Foundation @*
  50 51 Franklin Street, Fifth Floor@*
  51 Boston, MA 02110-1301, USA@*
  52 @sp 1
  53 @insertcopying
  54 @end titlepage
  55
  56 @summarycontents
  57 @contents
  58 @page
  59
  60
  61 @node Top
  62 @top Introduction
  63 @cindex Introduction
  64
  65 This manual documents the usage of libquadmath, the GCC Quad-Precision
  66 Math Library Application Programming Interface (API).
  67
  68
  69 @comment
  70 @comment  When you add a new menu item, please keep the right hand
  71 @comment  aligned to the same column.  Do not use tabs.  This provides
  72 @comment  better formatting.
  73 @comment
  74 @menu
  75 * Typedef and constants::      Defined data types and constants
  76 * Math Library Routines::      The Libquadmath math runtime application
  77                                programming interface.
  78 * I/O Library Routines::       The Libquadmath I/O runtime application
  79                                programming interface.
  80 * GNU Free Documentation License::
  81                                How you can copy and share this manual.
  82 * Reporting Bugs::             How to report bugs in GCC Libquadmath.
  83 @c * Index::                      Index of this documentation.
  84 @end menu
  85
  86
  87 @c ---------------------------------------------------------------------
  88 @c Defined macros
  89 @c ---------------------------------------------------------------------
  90
  91 @node Typedef and constants
  92 @chapter Typedef and constants
  93
  94 The following data type has been defined via @code{typedef}.
  95
  96 @table @asis
  97 @item @code{__complex128}: @code{__float128}-based complex number
  98 @end table
  99
 100 The following macros are defined, which give the numeric limits of the
 101 @code{__float128} data type.
 102
 103 @table @asis
 104 @item @code{FLT128_MAX}: largest finite number
 105 @item @code{FLT128_MIN}: smallest positive number with full precision
 106 @item @code{FLT128_EPSILON}: difference between 1 and the next larger
 107                              representable number
 108 @item @code{FLT128_DENORM_MIN}: smallest positive denormalized number
 109 @item @code{FLT128_MANT_DIG}: number of digits in the mantissa (bit precision)
 110 @item @code{FLT128_MIN_EXP}: maximal negative exponent
 111 @item @code{FLT128_MAX_EXP}: maximal positive exponent
 112 @item @code{FLT128_DIG}: number of decimal digits in the mantissa
 113 @item @code{FLT128_MIN_10_EXP}: maximal negative decimal exponent
 114 @item @code{FLT128_MAX_10_EXP}: maximal positive decimal exponent
 115 @end table
 116
 117 The following mathematical constants of type @code{__float128} are defined.
 118
 119 @table @asis
 120 @item @code{M_Eq}: the constant e (Euler's number)
 121 @item @code{M_LOG2Eq}: binary logarithm of 2
 122 @item @code{M_LOG10Eq}: common, decimal logarithm of 2
 123 @item @code{M_LN2q}: natural logarithm of 2
 124 @item @code{M_LN10q}: natural logarithm of 10
 125 @item @code{M_PIq}: pi
 126 @item @code{M_PI_2q}: pi divided by two
 127 @item @code{M_PI_4q}: pi divided by four
 128 @item @code{M_1_PIq}: one over pi
 129 @item @code{M_2_PIq}: one over two pi
 130 @item @code{M_2_SQRTPIq}: two over square root of pi
 131 @item @code{M_SQRT2q}: square root of 2
 132 @item @code{M_SQRT1_2q}: one over square root of 2
 133 @end table
 134
 135
 136 @c ---------------------------------------------------------------------
 137 @c Math routines
 138 @c ---------------------------------------------------------------------
 139
 140 @node Math Library Routines
 141 @chapter Math Library Routines
 142
 143 The following mathematical functions are available:
 144
 145 @table @asis
 146 @item @code{acosq}: arc cosine function
 147 @item @code{acoshq}: inverse hyperbolic cosine function
 148 @item @code{asinq}: arc sine function
 149 @item @code{asinhq}: inverse hyperbolic sine function
 150 @item @code{atanq}: arc tangent function
 151 @item @code{atanhq}: inverse hyperbolic tangent function
 152 @item @code{atan2q}: arc tangent function
 153 @item @code{cbrtq}: cube root function
 154 @item @code{ceilq}: ceiling value function
 155 @item @code{copysignq}: copy sign of a number
 156 @item @code{coshq}: hyperbolic cosine function
 157 @item @code{cosq}: cosine function
 158 @item @code{erfq}: error function
 159 @item @code{erfcq}: complementary error function
 160 @item @code{exp2q}: base 2 exponential function
 161 @item @code{expq}: exponential function
 162 @item @code{expm1q}: exponential minus 1 function
 163 @need 800
 164 @item @code{fabsq}: absolute value function
 165 @item @code{fdimq}: positive difference function
 166 @item @code{finiteq}: check finiteness of value
 167 @item @code{floorq}: floor value function
 168 @item @code{fmaq}: fused multiply and add
 169 @item @code{fmaxq}: determine maximum of two values
 170 @item @code{fminq}: determine minimum of two values
 171 @item @code{fmodq}: remainder value function
 172 @item @code{frexpq}: extract mantissa and exponent
 173 @item @code{hypotq}: Eucledian distance function
 174 @item @code{ilogbq}: get exponent of the value
 175 @item @code{isinfq}: check for infinity
 176 @item @code{isnanq}: check for not a number
 177 @item @code{issignalingq}: check for signaling not a number
 178 @item @code{j0q}: Bessel function of the first kind, first order
 179 @item @code{j1q}: Bessel function of the first kind, second order
 180 @item @code{jnq}: Bessel function of the first kind, @var{n}-th order
 181 @item @code{ldexpq}: load exponent of the value
 182 @item @code{lgammaq}: logarithmic gamma function
 183 @item @code{llrintq}: round to nearest integer value
 184 @item @code{llroundq}: round to nearest integer value away from zero
 185 @item @code{logbq}: get exponent of the value
 186 @item @code{logq}: natural logarithm function
 187 @item @code{log10q}: base 10 logarithm function
 188 @item @code{log1pq}: compute natural logarithm of the value plus one
 189 @item @code{log2q}: base 2 logarithm function
 190 @need 800
 191 @item @code{lrintq}: round to nearest integer value
 192 @item @code{lroundq}: round to nearest integer value away from zero
 193 @item @code{modfq}: decompose the floating-point number
 194 @item @code{nanq}: return quiet NaN
 195 @item @code{nearbyintq}: round to nearest integer
 196 @item @code{nextafterq}: next representable floating-point number
 197 @item @code{powq}: power function
 198 @item @code{remainderq}: remainder function
 199 @item @code{remquoq}: remainder and part of quotient
 200 @item @code{rintq}: round-to-nearest integral value
 201 @item @code{roundq}: round-to-nearest integral value, return @code{__float128}
 202 @item @code{scalblnq}: compute exponent using @code{FLT_RADIX}
 203 @item @code{scalbnq}: compute exponent using @code{FLT_RADIX}
 204 @item @code{signbitq}: return sign bit
 205 @item @code{sincosq}: calculate sine and cosine simultaneously
 206 @item @code{sinhq}: hyperbolic sine function
 207 @item @code{sinq}: sine function
 208 @item @code{sqrtq}: square root function
 209 @item @code{tanq}: tangent function
 210 @item @code{tanhq}: hyperbolic tangent function
 211 @need 800
 212 @item @code{tgammaq}: true gamma function
 213 @item @code{truncq}: round to integer, towards zero
 214 @item @code{y0q}: Bessel function of the second kind, first order
 215 @item @code{y1q}: Bessel function of the second kind, second order
 216 @item @code{ynq}: Bessel function of the second kind, @var{n}-th order
 217 @item @code{cabsq} complex absolute value function
 218 @item @code{cargq}: calculate the argument
 219 @item @code{cimagq} imaginary part of complex number
 220 @item @code{crealq}: real part of complex number
 221 @item @code{cacoshq}: complex arc hyperbolic cosine function
 222 @item @code{cacosq}: complex arc cosine function
 223 @item @code{casinhq}: complex arc hyperbolic sine function
 224 @item @code{casinq}: complex arc sine function
 225 @item @code{catanhq}: complex arc hyperbolic tangent function
 226 @item @code{catanq}: complex arc tangent function
 227 @item @code{ccosq} complex cosine function:
 228 @item @code{ccoshq}: complex hyperbolic cosine function
 229 @item @code{cexpq}: complex exponential function
 230 @need 800
 231 @item @code{cexpiq}: computes the exponential function of ``i'' times a
 232                      real value
 233 @item @code{clogq}: complex natural logarithm
 234 @item @code{clog10q}: complex base 10 logarithm
 235 @item @code{conjq}: complex conjugate function
 236 @item @code{cpowq}: complex power function
 237 @item @code{cprojq}: project into Riemann Sphere
 238 @item @code{csinq}: complex sine function
 239 @item @code{csinhq}: complex hyperbolic sine function
 240 @item @code{csqrtq}: complex square root
 241 @item @code{ctanq}: complex tangent function
 242 @item @code{ctanhq}: complex hyperbolic tangent function
 243 @end table
 244
 245
 246 @c ---------------------------------------------------------------------
 247 @c I/O routines
 248 @c ---------------------------------------------------------------------
 249
 250 @node I/O Library Routines
 251 @chapter I/O Library Routines
 252
 253 @menu
 254 * @code{strtoflt128}:          strtoflt128,          Convert from string
 255 * @code{quadmath_snprintf}:    quadmath_snprintf,    Convert to string
 256 @end menu
 257
 258
 259 @node strtoflt128
 260 @section @code{strtoflt128} --- Convert from string
 261
 262 The function @code{strtoflt128} converts a string into a
 263 @code{__float128} number.
 264
 265 @table @asis
 266 @item Syntax
 267 @code{__float128 strtoflt128 (const char *s, char **sp)}
 268
 269 @item @emph{Arguments}:
 270 @multitable @columnfractions .15 .70
 271 @item @var{s}  @tab input string
 272 @item @var{sp} @tab the address of the next character in the string
 273 @end multitable
 274
 275 The argument @var{sp} contains, if not @code{NULL}, the address of the
 276 next character following the parts of the string, which have been read.
 277
 278 @item Example
 279 @smallexample
 280 #include <quadmath.h>
 281
 282 int main ()
 283 @{
 284   __float128 r;
 285
 286   r = strtoflt128 ("1.2345678", NULL);
 287
 288   return 0;
 289 @}
 290 @end smallexample
 291 @end table
 292
 293
 294 @node quadmath_snprintf
 295 @section @code{quadmath_snprintf} --- Convert to string
 296
 297 The function @code{quadmath_snprintf} converts a @code{__float128} floating-point
 298 number into a string.  It is a specialized alternative to @code{snprintf}, where
 299 the format string is restricted to a single conversion specifier with @code{Q}
 300 modifier and conversion specifier @code{e}, @code{E}, @code{f}, @code{F}, @code{g},
 301 @code{G}, @code{a} or @code{A}, with no extra characters before or after the
 302 conversion specifier.  The @code{%m$} or @code{*m$} style must not be used in
 303 the format.
 304
 305 @table @asis
 306 @item Syntax
 307 @code{int quadmath_snprintf (char *s, size_t size, const char *format, ...)}
 308
 309 @item @emph{Arguments}:
 310 @multitable @columnfractions .15 .70
 311 @item @var{s}    @tab output string
 312 @item @var{size} @tab byte size of the string, including trailing NUL
 313 @item @var{format} @tab conversion specifier string
 314 @end multitable
 315
 316 @item Note
 317 On some targets when supported by the C library hooks are installed
 318 for @code{printf} family of functions, so that @code{printf ("%Qe", 1.2Q);}
 319 etc.@: works too.
 320
 321 @item Example
 322 @smallexample
 323 #include <quadmath.h>
 324 #include <stdlib.h>
 325 #include <stdio.h>
 326
 327 int main ()
 328 @{
 329   __float128 r;
 330   int prec = 20;
 331   int width = 46;
 332   char buf[128];
 333
 334   r = 2.0q;
 335   r = sqrtq (r);
 336   int n = quadmath_snprintf (buf, sizeof buf, "%+-#*.20Qe", width, r);
 337   if ((size_t) n < sizeof buf)
 338     printf ("%s\n", buf);
 339     /* Prints: +1.41421356237309504880e+00 */
 340   quadmath_snprintf (buf, sizeof buf, "%Qa", r);
 341   if ((size_t) n < sizeof buf)
 342     printf ("%s\n", buf);
 343     /* Prints: 0x1.6a09e667f3bcc908b2fb1366ea96p+0 */
 344   n = quadmath_snprintf (NULL, 0, "%+-#46.*Qe", prec, r);
 345   if (n > -1)
 346     @{
 347       char *str = malloc (n + 1);
 348       if (str)
 349         @{
 350           quadmath_snprintf (str, n + 1, "%+-#46.*Qe", prec, r);
 351           printf ("%s\n", str);
 352           /* Prints: +1.41421356237309504880e+00 */
 353         @}
 354       free (str);
 355     @}
 356   return 0;
 357 @}
 358 @end smallexample
 359
 360 @end table
 361
 362
 363 @c ---------------------------------------------------------------------
 364 @c GNU Free Documentation License
 365 @c ---------------------------------------------------------------------
 366
 367 @include fdl.texi
 368
 369 @c ---------------------------------------------------------------------
 370 @c Reporting Bugs
 371 @c ---------------------------------------------------------------------
 372
 373 @c For BUGURL
 374 @include libquadmath-vers.texi
 375
 376 @node Reporting Bugs
 377 @chapter Reporting Bugs
 378
 379 Bugs in the GCC Quad-Precision Math Library implementation should be
 380 reported via @value{BUGURL}.
 381
 382
 383 @c ---------------------------------------------------------------------
 384 @c Index
 385 @c ---------------------------------------------------------------------
 386
 387 @c @node Index
 388 @c @unnumbered Index
 389 @c
 390 @c @printindex cp
 391
 392 @bye