]>
Commit | Line | Data |
---|---|---|
d77de738 ML |
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 | |
74d5206f | 9 | Copyright @copyright{} 2010-2023 Free Software Foundation, Inc. |
d77de738 ML |
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 |