aboutsummaryrefslogtreecommitdiff
path: root/libquadmath/libquadmath.texi
blob: fad8e62d8bc6b5d459650b206ccc3da3abca6ecf (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
\input texinfo @c -*-texinfo-*-

@c %**start of header
@setfilename libquadmath.info
@settitle GCC libquadmath
@c %**end of header

@copying
Copyright @copyright{} 2010-2022 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}: pi divided by two
@item @code{M_PI_4q}: pi divided by four
@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{exp2q}: base 2 exponential 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{issignalingq}: check for signaling 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{logbq}: get exponent of the value
@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 simultaneously
@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{strtoflt128} 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 trailing NUL
@item @var{format} @tab conversion specifier string
@end multitable

@item Note
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.

@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


@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