]>
Commit | Line | Data |
---|---|---|
4c993c44 TB |
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 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 | |
0ecf8f66 | 75 | * Typedef and constants:: Defined data types and constants |
4c993c44 TB |
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 | ||
0ecf8f66 TB |
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 | |
a855debf JJ |
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 | |
0ecf8f66 TB |
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}: two pi | |
127 | @item @code{M_PI_4q}: four pi | |
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 | ||
4c993c44 TB |
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{expq}: exponential function | |
161 | @item @code{expm1q}: exponential minus 1 function | |
162 | @need 800 | |
163 | @item @code{fabsq}: absolute value function | |
dbc9f6c6 | 164 | @item @code{fdimq}: positive difference function |
4c993c44 TB |
165 | @item @code{finiteq}: check finiteness of value |
166 | @item @code{floorq}: floor value function | |
e8d42d28 | 167 | @item @code{fmaq}: fused multiply and add |
dbc9f6c6 JJ |
168 | @item @code{fmaxq}: determine maximum of two values |
169 | @item @code{fminq}: determine minimum of two values | |
4c993c44 TB |
170 | @item @code{fmodq}: remainder value function |
171 | @item @code{frexpq}: extract mantissa and exponent | |
172 | @item @code{hypotq}: Eucledian distance function | |
dbc9f6c6 | 173 | @item @code{ilogbq}: get exponent of the value |
4c993c44 TB |
174 | @item @code{isinfq}: check for infinity |
175 | @item @code{isnanq}: check for not a number | |
176 | @item @code{j0q}: Bessel function of the first kind, first order | |
177 | @item @code{j1q}: Bessel function of the first kind, second order | |
178 | @item @code{jnq}: Bessel function of the first kind, @var{n}-th order | |
179 | @item @code{ldexpq}: load exponent of the value | |
180 | @item @code{lgammaq}: logarithmic gamma function | |
dbc9f6c6 | 181 | @item @code{llrintq}: round to nearest integer value |
4c993c44 TB |
182 | @item @code{llroundq}: round to nearest integer value away from zero |
183 | @item @code{logq}: natural logarithm function | |
184 | @item @code{log10q}: base 10 logarithm function | |
185 | @item @code{log1pq}: compute natural logarithm of the value plus one | |
dbc9f6c6 | 186 | @item @code{log2q}: base 2 logarithm function |
4c993c44 | 187 | @need 800 |
dbc9f6c6 | 188 | @item @code{lrintq}: round to nearest integer value |
4c993c44 TB |
189 | @item @code{lroundq}: round to nearest integer value away from zero |
190 | @item @code{modfq}: decompose the floating-point number | |
191 | @item @code{nanq}: return quiet NaN | |
dbc9f6c6 | 192 | @item @code{nearbyintq}: round to nearest integer |
4c993c44 TB |
193 | @item @code{nextafterq}: next representable floating-point number |
194 | @item @code{powq}: power function | |
195 | @item @code{remainderq}: remainder function | |
dbc9f6c6 | 196 | @item @code{remquoq}: remainder and part of quotient |
4c993c44 TB |
197 | @item @code{rintq}: round-to-nearest integral value |
198 | @item @code{roundq}: round-to-nearest integral value, return @code{__float128} | |
199 | @item @code{scalblnq}: compute exponent using @code{FLT_RADIX} | |
200 | @item @code{scalbnq}: compute exponent using @code{FLT_RADIX} | |
201 | @item @code{signbitq}: return sign bit | |
202 | @item @code{sincosq}: calculate sine and cosine simulataneously | |
203 | @item @code{sinhq}: hyperbolic sine function | |
204 | @item @code{sinq}: sine function | |
205 | @item @code{sqrtq}: square root function | |
206 | @item @code{tanq}: tangent function | |
207 | @item @code{tanhq}: hyperbolic tangent function | |
208 | @need 800 | |
209 | @item @code{tgammaq}: true gamma function | |
210 | @item @code{truncq}: round to integer, towards zero | |
211 | @item @code{y0q}: Bessel function of the second kind, first order | |
212 | @item @code{y1q}: Bessel function of the second kind, second order | |
213 | @item @code{ynq}: Bessel function of the second kind, @var{n}-th order | |
dbc9f6c6 | 214 | @item @code{cabsq} complex absolute value function |
4c993c44 | 215 | @item @code{cargq}: calculate the argument |
dbc9f6c6 JJ |
216 | @item @code{cimagq} imaginary part of complex number |
217 | @item @code{crealq}: real part of complex number | |
fa23b182 JJ |
218 | @item @code{cacoshq}: complex arc hyperbolic cosine function |
219 | @item @code{cacosq}: complex arc cosine function | |
220 | @item @code{casinhq}: complex arc hyperbolic sine function | |
221 | @item @code{casinq}: complex arc sine function | |
222 | @item @code{catanhq}: complex arc hyperbolic tangent function | |
223 | @item @code{catanq}: complex arc tangent function | |
4c993c44 TB |
224 | @item @code{ccosq} complex cosine function: |
225 | @item @code{ccoshq}: complex hyperbolic cosine function | |
226 | @item @code{cexpq}: complex exponential function | |
fa23b182 | 227 | @need 800 |
4c993c44 TB |
228 | @item @code{cexpiq}: computes the exponential function of ``i'' times a |
229 | real value | |
230 | @item @code{clogq}: complex natural logarithm | |
231 | @item @code{clog10q}: complex base 10 logarithm | |
dbc9f6c6 | 232 | @item @code{conjq}: complex conjugate function |
4c993c44 | 233 | @item @code{cpowq}: complex power function |
dbc9f6c6 | 234 | @item @code{cprojq}: project into Riemann Sphere |
4c993c44 TB |
235 | @item @code{csinq}: complex sine function |
236 | @item @code{csinhq}: complex hyperbolic sine function | |
4c993c44 TB |
237 | @item @code{csqrtq}: complex square root |
238 | @item @code{ctanq}: complex tangent function | |
239 | @item @code{ctanhq}: complex hyperbolic tangent function | |
240 | @end table | |
241 | ||
242 | ||
243 | @c --------------------------------------------------------------------- | |
244 | @c I/O routines | |
245 | @c --------------------------------------------------------------------- | |
246 | ||
247 | @node I/O Library Routines | |
248 | @chapter I/O Library Routines | |
249 | ||
250 | @menu | |
e313241f | 251 | * @code{strtoflt128}: strtoflt128, Convert from string |
1d92226b | 252 | * @code{quadmath_snprintf}: quadmath_snprintf, Convert to string |
4c993c44 TB |
253 | @end menu |
254 | ||
255 | ||
e313241f JJ |
256 | @node strtoflt128 |
257 | @section @code{strtoflt128} --- Convert from string | |
4c993c44 TB |
258 | |
259 | The function @code{dmath_strtopQ} converts a string into a | |
260 | @code{__float128} number. | |
261 | ||
262 | @table @asis | |
263 | @item Syntax | |
e313241f | 264 | @code{__float128 strtoflt128 (const char *s, char **sp)} |
4c993c44 | 265 | |
4c993c44 TB |
266 | @item @emph{Arguments}: |
267 | @multitable @columnfractions .15 .70 | |
268 | @item @var{s} @tab input string | |
269 | @item @var{sp} @tab the address of the next character in the string | |
4c993c44 TB |
270 | @end multitable |
271 | ||
272 | The argument @var{sp} contains, if not @code{NULL}, the address of the | |
273 | next character following the parts of the string, which have been read. | |
274 | ||
275 | @item Example | |
276 | @smallexample | |
277 | #include <quadmath.h> | |
278 | ||
279 | int main () | |
280 | @{ | |
281 | __float128 r; | |
4c993c44 | 282 | |
e313241f | 283 | r = strtoflt128 ("1.2345678", NULL); |
4c993c44 TB |
284 | |
285 | return 0; | |
286 | @} | |
287 | @end smallexample | |
288 | @end table | |
289 | ||
290 | ||
1d92226b JJ |
291 | @node quadmath_snprintf |
292 | @section @code{quadmath_snprintf} --- Convert to string | |
4c993c44 | 293 | |
1d92226b JJ |
294 | The function @code{quadmath_snprintf} converts a @code{__float128} floating-point |
295 | number into a string. It is a specialized alternative to @code{snprintf}, where | |
296 | the format string is restricted to a single conversion specifier with @code{Q} | |
297 | modifier and conversion specifier @code{e}, @code{E}, @code{f}, @code{F}, @code{g}, | |
298 | @code{G}, @code{a} or @code{A}, with no extra characters before or after the | |
299 | conversion specifier. The @code{%m$} or @code{*m$} style must not be used in | |
300 | the format. | |
4c993c44 TB |
301 | |
302 | @table @asis | |
303 | @item Syntax | |
1d92226b | 304 | @code{int quadmath_snprintf (char *s, size_t size, const char *format, ...)} |
4c993c44 TB |
305 | |
306 | @item @emph{Arguments}: | |
307 | @multitable @columnfractions .15 .70 | |
308 | @item @var{s} @tab output string | |
309 | @item @var{size} @tab byte size of the string, including tailing NUL | |
1d92226b | 310 | @item @var{format} @tab conversion specifier string |
4c993c44 TB |
311 | @end multitable |
312 | ||
313 | @item Example | |
314 | @smallexample | |
315 | #include <quadmath.h> | |
1d92226b JJ |
316 | #include <stdlib.h> |
317 | #include <stdio.h> | |
4c993c44 TB |
318 | |
319 | int main () | |
320 | @{ | |
321 | __float128 r; | |
1d92226b JJ |
322 | int prec = 20; |
323 | int width = 46; | |
324 | char buf[128]; | |
4c993c44 TB |
325 | |
326 | r = 2.0q; | |
1d92226b JJ |
327 | r = sqrtq (r); |
328 | int n = quadmath_snprintf (buf, sizeof buf, "%+-#*.20Qe", width, r); | |
329 | if ((size_t) n < sizeof buf) | |
330 | printf ("%s\n", buf); | |
331 | /* Prints: +1.41421356237309504880e+00 */ | |
332 | quadmath_snprintf (buf, sizeof buf, "%Qa", r); | |
333 | if ((size_t) n < sizeof buf) | |
334 | printf ("%s\n", buf); | |
335 | /* Prints: 0x1.6a09e667f3bcc908b2fb1366ea96p+0 */ | |
336 | n = quadmath_snprintf (NULL, 0, "%+-#46.*Qe", prec, r); | |
337 | if (n > -1) | |
338 | @{ | |
339 | char *str = malloc (n + 1); | |
340 | if (str) | |
341 | @{ | |
342 | quadmath_snprintf (str, n + 1, "%+-#46.*Qe", prec, r); | |
343 | printf ("%s\n", str); | |
344 | /* Prints: +1.41421356237309504880e+00 */ | |
345 | @} | |
346 | free (str); | |
347 | @} | |
4c993c44 TB |
348 | return 0; |
349 | @} | |
350 | @end smallexample | |
1d92226b | 351 | |
4c993c44 TB |
352 | @end table |
353 | ||
1d92226b JJ |
354 | On some targets when supported by the C library hooks are installed |
355 | for @code{printf} family of functions, so that @code{printf ("%Qe", 1.2Q);} | |
356 | etc.@: works too. | |
357 | ||
4c993c44 TB |
358 | |
359 | @c --------------------------------------------------------------------- | |
360 | @c GNU Free Documentation License | |
361 | @c --------------------------------------------------------------------- | |
362 | ||
363 | @include fdl.texi | |
364 | ||
365 | @c --------------------------------------------------------------------- | |
366 | @c Reporting Bugs | |
367 | @c --------------------------------------------------------------------- | |
368 | ||
642d2873 TB |
369 | @c For BUGURL |
370 | @include libquadmath-vers.texi | |
371 | ||
4c993c44 TB |
372 | @node Reporting Bugs |
373 | @chapter Reporting Bugs | |
374 | ||
375 | Bugs in the GCC Quad-Precision Math Library implementation should be | |
376 | reported via @value{BUGURL}. | |
377 | ||
378 | ||
379 | @c --------------------------------------------------------------------- | |
380 | @c Index | |
381 | @c --------------------------------------------------------------------- | |
382 | ||
383 | @c @node Index | |
384 | @c @unnumbered Index | |
385 | @c | |
386 | @c @printindex cp | |
387 | ||
388 | @bye |