]>
Commit | Line | Data |
---|---|---|
28f540f4 | 1 | @node Arithmetic, Date and Time, Mathematics, Top |
7a68c94a UD |
2 | @c %MENU% Low level arithmetic functions |
3 | @chapter Arithmetic Functions | |
28f540f4 RM |
4 | |
5 | This chapter contains information about functions for doing basic | |
6 | arithmetic operations, such as splitting a float into its integer and | |
b4012b75 UD |
7 | fractional parts or retrieving the imaginary part of a complex value. |
8 | These functions are declared in the header files @file{math.h} and | |
9 | @file{complex.h}. | |
28f540f4 RM |
10 | |
11 | @menu | |
7a68c94a UD |
12 | * Floating Point Numbers:: Basic concepts. IEEE 754. |
13 | * Floating Point Classes:: The five kinds of floating-point number. | |
14 | * Floating Point Errors:: When something goes wrong in a calculation. | |
15 | * Rounding:: Controlling how results are rounded. | |
16 | * Control Functions:: Saving and restoring the FPU's state. | |
17 | * Arithmetic Functions:: Fundamental operations provided by the library. | |
18 | * Complex Numbers:: The types. Writing complex constants. | |
19 | * Operations on Complex:: Projection, conjugation, decomposition. | |
20 | * Integer Division:: Integer division with guaranteed rounding. | |
21 | * Parsing of Numbers:: Converting strings to numbers. | |
22 | * System V Number Conversion:: An archaic way to convert numbers to strings. | |
28f540f4 RM |
23 | @end menu |
24 | ||
7a68c94a UD |
25 | @node Floating Point Numbers |
26 | @section Floating Point Numbers | |
27 | @cindex floating point | |
28 | @cindex IEEE 754 | |
b4012b75 UD |
29 | @cindex IEEE floating point |
30 | ||
7a68c94a UD |
31 | Most computer hardware has support for two different kinds of numbers: |
32 | integers (@math{@dots{}-3, -2, -1, 0, 1, 2, 3@dots{}}) and | |
33 | floating-point numbers. Floating-point numbers have three parts: the | |
34 | @dfn{mantissa}, the @dfn{exponent}, and the @dfn{sign bit}. The real | |
35 | number represented by a floating-point value is given by | |
36 | @tex | |
37 | $(s \mathrel? -1 \mathrel: 1) \cdot 2^e \cdot M$ | |
38 | @end tex | |
39 | @ifnottex | |
40 | @math{(s ? -1 : 1) @mul{} 2^e @mul{} M} | |
41 | @end ifnottex | |
42 | where @math{s} is the sign bit, @math{e} the exponent, and @math{M} | |
43 | the mantissa. @xref{Floating Point Concepts}, for details. (It is | |
44 | possible to have a different @dfn{base} for the exponent, but all modern | |
45 | hardware uses @math{2}.) | |
46 | ||
47 | Floating-point numbers can represent a finite subset of the real | |
48 | numbers. While this subset is large enough for most purposes, it is | |
49 | important to remember that the only reals that can be represented | |
50 | exactly are rational numbers that have a terminating binary expansion | |
51 | shorter than the width of the mantissa. Even simple fractions such as | |
52 | @math{1/5} can only be approximated by floating point. | |
53 | ||
54 | Mathematical operations and functions frequently need to produce values | |
55 | that are not representable. Often these values can be approximated | |
56 | closely enough for practical purposes, but sometimes they can't. | |
57 | Historically there was no way to tell when the results of a calculation | |
58 | were inaccurate. Modern computers implement the @w{IEEE 754} standard | |
59 | for numerical computations, which defines a framework for indicating to | |
60 | the program when the results of calculation are not trustworthy. This | |
61 | framework consists of a set of @dfn{exceptions} that indicate why a | |
62 | result could not be represented, and the special values @dfn{infinity} | |
63 | and @dfn{not a number} (NaN). | |
64 | ||
65 | @node Floating Point Classes | |
66 | @section Floating-Point Number Classification Functions | |
67 | @cindex floating-point classes | |
68 | @cindex classes, floating-point | |
69 | @pindex math.h | |
b4012b75 | 70 | |
ec751a23 | 71 | @w{ISO C99} defines macros that let you determine what sort of |
7a68c94a | 72 | floating-point number a variable holds. |
b4012b75 UD |
73 | |
74 | @comment math.h | |
75 | @comment ISO | |
7a68c94a UD |
76 | @deftypefn {Macro} int fpclassify (@emph{float-type} @var{x}) |
77 | This is a generic macro which works on all floating-point types and | |
78 | which returns a value of type @code{int}. The possible values are: | |
28f540f4 | 79 | |
7a68c94a UD |
80 | @vtable @code |
81 | @item FP_NAN | |
82 | The floating-point number @var{x} is ``Not a Number'' (@pxref{Infinity | |
83 | and NaN}) | |
84 | @item FP_INFINITE | |
85 | The value of @var{x} is either plus or minus infinity (@pxref{Infinity | |
86 | and NaN}) | |
87 | @item FP_ZERO | |
88 | The value of @var{x} is zero. In floating-point formats like @w{IEEE | |
89 | 754}, where zero can be signed, this value is also returned if | |
90 | @var{x} is negative zero. | |
91 | @item FP_SUBNORMAL | |
92 | Numbers whose absolute value is too small to be represented in the | |
93 | normal format are represented in an alternate, @dfn{denormalized} format | |
94 | (@pxref{Floating Point Concepts}). This format is less precise but can | |
95 | represent values closer to zero. @code{fpclassify} returns this value | |
96 | for values of @var{x} in this alternate format. | |
97 | @item FP_NORMAL | |
98 | This value is returned for all other values of @var{x}. It indicates | |
99 | that there is nothing special about the number. | |
100 | @end vtable | |
28f540f4 | 101 | |
7a68c94a | 102 | @end deftypefn |
28f540f4 | 103 | |
7a68c94a UD |
104 | @code{fpclassify} is most useful if more than one property of a number |
105 | must be tested. There are more specific macros which only test one | |
106 | property at a time. Generally these macros execute faster than | |
107 | @code{fpclassify}, since there is special hardware support for them. | |
108 | You should therefore use the specific macros whenever possible. | |
28f540f4 RM |
109 | |
110 | @comment math.h | |
7a68c94a UD |
111 | @comment ISO |
112 | @deftypefn {Macro} int isfinite (@emph{float-type} @var{x}) | |
113 | This macro returns a nonzero value if @var{x} is finite: not plus or | |
114 | minus infinity, and not NaN. It is equivalent to | |
fe0ec73e UD |
115 | |
116 | @smallexample | |
7a68c94a | 117 | (fpclassify (x) != FP_NAN && fpclassify (x) != FP_INFINITE) |
fe0ec73e UD |
118 | @end smallexample |
119 | ||
7a68c94a UD |
120 | @code{isfinite} is implemented as a macro which accepts any |
121 | floating-point type. | |
122 | @end deftypefn | |
fe0ec73e | 123 | |
7a68c94a UD |
124 | @comment math.h |
125 | @comment ISO | |
126 | @deftypefn {Macro} int isnormal (@emph{float-type} @var{x}) | |
127 | This macro returns a nonzero value if @var{x} is finite and normalized. | |
128 | It is equivalent to | |
b4012b75 UD |
129 | |
130 | @smallexample | |
7a68c94a | 131 | (fpclassify (x) == FP_NORMAL) |
b4012b75 | 132 | @end smallexample |
7a68c94a | 133 | @end deftypefn |
b4012b75 | 134 | |
7a68c94a UD |
135 | @comment math.h |
136 | @comment ISO | |
137 | @deftypefn {Macro} int isnan (@emph{float-type} @var{x}) | |
138 | This macro returns a nonzero value if @var{x} is NaN. It is equivalent | |
139 | to | |
b4012b75 UD |
140 | |
141 | @smallexample | |
7a68c94a | 142 | (fpclassify (x) == FP_NAN) |
b4012b75 | 143 | @end smallexample |
7a68c94a | 144 | @end deftypefn |
b4012b75 | 145 | |
7a68c94a UD |
146 | Another set of floating-point classification functions was provided by |
147 | BSD. The GNU C library also supports these functions; however, we | |
ec751a23 | 148 | recommend that you use the ISO C99 macros in new code. Those are standard |
7a68c94a UD |
149 | and will be available more widely. Also, since they are macros, you do |
150 | not have to worry about the type of their argument. | |
28f540f4 RM |
151 | |
152 | @comment math.h | |
153 | @comment BSD | |
154 | @deftypefun int isinf (double @var{x}) | |
4260bc74 UD |
155 | @comment math.h |
156 | @comment BSD | |
779ae82e | 157 | @deftypefunx int isinff (float @var{x}) |
4260bc74 UD |
158 | @comment math.h |
159 | @comment BSD | |
779ae82e | 160 | @deftypefunx int isinfl (long double @var{x}) |
28f540f4 RM |
161 | This function returns @code{-1} if @var{x} represents negative infinity, |
162 | @code{1} if @var{x} represents positive infinity, and @code{0} otherwise. | |
163 | @end deftypefun | |
164 | ||
165 | @comment math.h | |
166 | @comment BSD | |
167 | @deftypefun int isnan (double @var{x}) | |
4260bc74 UD |
168 | @comment math.h |
169 | @comment BSD | |
779ae82e | 170 | @deftypefunx int isnanf (float @var{x}) |
4260bc74 UD |
171 | @comment math.h |
172 | @comment BSD | |
779ae82e | 173 | @deftypefunx int isnanl (long double @var{x}) |
28f540f4 | 174 | This function returns a nonzero value if @var{x} is a ``not a number'' |
7a68c94a | 175 | value, and zero otherwise. |
b9b49b44 | 176 | |
ec751a23 | 177 | @strong{Note:} The @code{isnan} macro defined by @w{ISO C99} overrides |
7a68c94a UD |
178 | the BSD function. This is normally not a problem, because the two |
179 | routines behave identically. However, if you really need to get the BSD | |
180 | function for some reason, you can write | |
b9b49b44 | 181 | |
7a68c94a UD |
182 | @smallexample |
183 | (isnan) (x) | |
184 | @end smallexample | |
28f540f4 RM |
185 | @end deftypefun |
186 | ||
187 | @comment math.h | |
188 | @comment BSD | |
189 | @deftypefun int finite (double @var{x}) | |
4260bc74 UD |
190 | @comment math.h |
191 | @comment BSD | |
779ae82e | 192 | @deftypefunx int finitef (float @var{x}) |
4260bc74 UD |
193 | @comment math.h |
194 | @comment BSD | |
779ae82e | 195 | @deftypefunx int finitel (long double @var{x}) |
28f540f4 RM |
196 | This function returns a nonzero value if @var{x} is finite or a ``not a |
197 | number'' value, and zero otherwise. | |
198 | @end deftypefun | |
199 | ||
200 | @comment math.h | |
201 | @comment BSD | |
202 | @deftypefun double infnan (int @var{error}) | |
7a68c94a UD |
203 | This function is provided for compatibility with BSD. Its argument is |
204 | an error code, @code{EDOM} or @code{ERANGE}; @code{infnan} returns the | |
205 | value that a math function would return if it set @code{errno} to that | |
206 | value. @xref{Math Error Reporting}. @code{-ERANGE} is also acceptable | |
207 | as an argument, and corresponds to @code{-HUGE_VAL} as a value. | |
28f540f4 RM |
208 | |
209 | In the BSD library, on certain machines, @code{infnan} raises a fatal | |
210 | signal in all cases. The GNU library does not do likewise, because that | |
f65fd747 | 211 | does not fit the @w{ISO C} specification. |
28f540f4 RM |
212 | @end deftypefun |
213 | ||
214 | @strong{Portability Note:} The functions listed in this section are BSD | |
215 | extensions. | |
216 | ||
b4012b75 | 217 | |
7a68c94a UD |
218 | @node Floating Point Errors |
219 | @section Errors in Floating-Point Calculations | |
220 | ||
221 | @menu | |
222 | * FP Exceptions:: IEEE 754 math exceptions and how to detect them. | |
223 | * Infinity and NaN:: Special values returned by calculations. | |
224 | * Status bit operations:: Checking for exceptions after the fact. | |
225 | * Math Error Reporting:: How the math functions report errors. | |
226 | @end menu | |
227 | ||
228 | @node FP Exceptions | |
229 | @subsection FP Exceptions | |
230 | @cindex exception | |
231 | @cindex signal | |
232 | @cindex zero divide | |
233 | @cindex division by zero | |
234 | @cindex inexact exception | |
235 | @cindex invalid exception | |
236 | @cindex overflow exception | |
237 | @cindex underflow exception | |
238 | ||
239 | The @w{IEEE 754} standard defines five @dfn{exceptions} that can occur | |
240 | during a calculation. Each corresponds to a particular sort of error, | |
241 | such as overflow. | |
242 | ||
243 | When exceptions occur (when exceptions are @dfn{raised}, in the language | |
244 | of the standard), one of two things can happen. By default the | |
245 | exception is simply noted in the floating-point @dfn{status word}, and | |
246 | the program continues as if nothing had happened. The operation | |
247 | produces a default value, which depends on the exception (see the table | |
248 | below). Your program can check the status word to find out which | |
249 | exceptions happened. | |
250 | ||
251 | Alternatively, you can enable @dfn{traps} for exceptions. In that case, | |
252 | when an exception is raised, your program will receive the @code{SIGFPE} | |
253 | signal. The default action for this signal is to terminate the | |
8b7fb588 | 254 | program. @xref{Signal Handling}, for how you can change the effect of |
7a68c94a UD |
255 | the signal. |
256 | ||
257 | @findex matherr | |
258 | In the System V math library, the user-defined function @code{matherr} | |
259 | is called when certain exceptions occur inside math library functions. | |
260 | However, the Unix98 standard deprecates this interface. We support it | |
261 | for historical compatibility, but recommend that you do not use it in | |
262 | new programs. | |
263 | ||
264 | @noindent | |
265 | The exceptions defined in @w{IEEE 754} are: | |
266 | ||
267 | @table @samp | |
268 | @item Invalid Operation | |
269 | This exception is raised if the given operands are invalid for the | |
270 | operation to be performed. Examples are | |
271 | (see @w{IEEE 754}, @w{section 7}): | |
272 | @enumerate | |
273 | @item | |
274 | Addition or subtraction: @math{@infinity{} - @infinity{}}. (But | |
275 | @math{@infinity{} + @infinity{} = @infinity{}}). | |
276 | @item | |
277 | Multiplication: @math{0 @mul{} @infinity{}}. | |
278 | @item | |
279 | Division: @math{0/0} or @math{@infinity{}/@infinity{}}. | |
280 | @item | |
281 | Remainder: @math{x} REM @math{y}, where @math{y} is zero or @math{x} is | |
282 | infinite. | |
283 | @item | |
284 | Square root if the operand is less then zero. More generally, any | |
285 | mathematical function evaluated outside its domain produces this | |
286 | exception. | |
287 | @item | |
288 | Conversion of a floating-point number to an integer or decimal | |
289 | string, when the number cannot be represented in the target format (due | |
290 | to overflow, infinity, or NaN). | |
291 | @item | |
292 | Conversion of an unrecognizable input string. | |
293 | @item | |
294 | Comparison via predicates involving @math{<} or @math{>}, when one or | |
295 | other of the operands is NaN. You can prevent this exception by using | |
296 | the unordered comparison functions instead; see @ref{FP Comparison Functions}. | |
297 | @end enumerate | |
298 | ||
299 | If the exception does not trap, the result of the operation is NaN. | |
300 | ||
301 | @item Division by Zero | |
302 | This exception is raised when a finite nonzero number is divided | |
303 | by zero. If no trap occurs the result is either @math{+@infinity{}} or | |
304 | @math{-@infinity{}}, depending on the signs of the operands. | |
305 | ||
306 | @item Overflow | |
307 | This exception is raised whenever the result cannot be represented | |
308 | as a finite value in the precision format of the destination. If no trap | |
309 | occurs the result depends on the sign of the intermediate result and the | |
310 | current rounding mode (@w{IEEE 754}, @w{section 7.3}): | |
311 | @enumerate | |
312 | @item | |
313 | Round to nearest carries all overflows to @math{@infinity{}} | |
314 | with the sign of the intermediate result. | |
315 | @item | |
316 | Round toward @math{0} carries all overflows to the largest representable | |
317 | finite number with the sign of the intermediate result. | |
318 | @item | |
319 | Round toward @math{-@infinity{}} carries positive overflows to the | |
320 | largest representable finite number and negative overflows to | |
321 | @math{-@infinity{}}. | |
322 | ||
323 | @item | |
324 | Round toward @math{@infinity{}} carries negative overflows to the | |
325 | most negative representable finite number and positive overflows | |
326 | to @math{@infinity{}}. | |
327 | @end enumerate | |
328 | ||
329 | Whenever the overflow exception is raised, the inexact exception is also | |
330 | raised. | |
331 | ||
332 | @item Underflow | |
333 | The underflow exception is raised when an intermediate result is too | |
334 | small to be calculated accurately, or if the operation's result rounded | |
335 | to the destination precision is too small to be normalized. | |
336 | ||
337 | When no trap is installed for the underflow exception, underflow is | |
338 | signaled (via the underflow flag) only when both tininess and loss of | |
339 | accuracy have been detected. If no trap handler is installed the | |
340 | operation continues with an imprecise small value, or zero if the | |
341 | destination precision cannot hold the small exact result. | |
342 | ||
343 | @item Inexact | |
344 | This exception is signalled if a rounded result is not exact (such as | |
345 | when calculating the square root of two) or a result overflows without | |
346 | an overflow trap. | |
347 | @end table | |
348 | ||
349 | @node Infinity and NaN | |
350 | @subsection Infinity and NaN | |
351 | @cindex infinity | |
352 | @cindex not a number | |
353 | @cindex NaN | |
354 | ||
355 | @w{IEEE 754} floating point numbers can represent positive or negative | |
356 | infinity, and @dfn{NaN} (not a number). These three values arise from | |
357 | calculations whose result is undefined or cannot be represented | |
358 | accurately. You can also deliberately set a floating-point variable to | |
359 | any of them, which is sometimes useful. Some examples of calculations | |
360 | that produce infinity or NaN: | |
361 | ||
362 | @ifnottex | |
363 | @smallexample | |
364 | @math{1/0 = @infinity{}} | |
365 | @math{log (0) = -@infinity{}} | |
366 | @math{sqrt (-1) = NaN} | |
367 | @end smallexample | |
368 | @end ifnottex | |
369 | @tex | |
370 | $${1\over0} = \infty$$ | |
371 | $$\log 0 = -\infty$$ | |
372 | $$\sqrt{-1} = \hbox{NaN}$$ | |
373 | @end tex | |
374 | ||
375 | When a calculation produces any of these values, an exception also | |
376 | occurs; see @ref{FP Exceptions}. | |
377 | ||
378 | The basic operations and math functions all accept infinity and NaN and | |
379 | produce sensible output. Infinities propagate through calculations as | |
380 | one would expect: for example, @math{2 + @infinity{} = @infinity{}}, | |
381 | @math{4/@infinity{} = 0}, atan @math{(@infinity{}) = @pi{}/2}. NaN, on | |
382 | the other hand, infects any calculation that involves it. Unless the | |
383 | calculation would produce the same result no matter what real value | |
384 | replaced NaN, the result is NaN. | |
385 | ||
386 | In comparison operations, positive infinity is larger than all values | |
387 | except itself and NaN, and negative infinity is smaller than all values | |
388 | except itself and NaN. NaN is @dfn{unordered}: it is not equal to, | |
389 | greater than, or less than anything, @emph{including itself}. @code{x == | |
390 | x} is false if the value of @code{x} is NaN. You can use this to test | |
391 | whether a value is NaN or not, but the recommended way to test for NaN | |
392 | is with the @code{isnan} function (@pxref{Floating Point Classes}). In | |
393 | addition, @code{<}, @code{>}, @code{<=}, and @code{>=} will raise an | |
394 | exception when applied to NaNs. | |
395 | ||
396 | @file{math.h} defines macros that allow you to explicitly set a variable | |
397 | to infinity or NaN. | |
b4012b75 UD |
398 | |
399 | @comment math.h | |
400 | @comment ISO | |
7a68c94a UD |
401 | @deftypevr Macro float INFINITY |
402 | An expression representing positive infinity. It is equal to the value | |
403 | produced by mathematical operations like @code{1.0 / 0.0}. | |
404 | @code{-INFINITY} represents negative infinity. | |
405 | ||
406 | You can test whether a floating-point value is infinite by comparing it | |
407 | to this macro. However, this is not recommended; you should use the | |
408 | @code{isfinite} macro instead. @xref{Floating Point Classes}. | |
409 | ||
ec751a23 | 410 | This macro was introduced in the @w{ISO C99} standard. |
7a68c94a UD |
411 | @end deftypevr |
412 | ||
413 | @comment math.h | |
414 | @comment GNU | |
415 | @deftypevr Macro float NAN | |
416 | An expression representing a value which is ``not a number''. This | |
417 | macro is a GNU extension, available only on machines that support the | |
418 | ``not a number'' value---that is to say, on all machines that support | |
419 | IEEE floating point. | |
420 | ||
421 | You can use @samp{#ifdef NAN} to test whether the machine supports | |
422 | NaN. (Of course, you must arrange for GNU extensions to be visible, | |
423 | such as by defining @code{_GNU_SOURCE}, and then you must include | |
424 | @file{math.h}.) | |
425 | @end deftypevr | |
426 | ||
427 | @w{IEEE 754} also allows for another unusual value: negative zero. This | |
428 | value is produced when you divide a positive number by negative | |
429 | infinity, or when a negative result is smaller than the limits of | |
430 | representation. Negative zero behaves identically to zero in all | |
431 | calculations, unless you explicitly test the sign bit with | |
432 | @code{signbit} or @code{copysign}. | |
433 | ||
434 | @node Status bit operations | |
435 | @subsection Examining the FPU status word | |
436 | ||
ec751a23 | 437 | @w{ISO C99} defines functions to query and manipulate the |
7a68c94a UD |
438 | floating-point status word. You can use these functions to check for |
439 | untrapped exceptions when it's convenient, rather than worrying about | |
440 | them in the middle of a calculation. | |
441 | ||
442 | These constants represent the various @w{IEEE 754} exceptions. Not all | |
443 | FPUs report all the different exceptions. Each constant is defined if | |
444 | and only if the FPU you are compiling for supports that exception, so | |
445 | you can test for FPU support with @samp{#ifdef}. They are defined in | |
446 | @file{fenv.h}. | |
b4012b75 UD |
447 | |
448 | @vtable @code | |
7a68c94a UD |
449 | @comment fenv.h |
450 | @comment ISO | |
451 | @item FE_INEXACT | |
452 | The inexact exception. | |
453 | @comment fenv.h | |
454 | @comment ISO | |
455 | @item FE_DIVBYZERO | |
456 | The divide by zero exception. | |
457 | @comment fenv.h | |
458 | @comment ISO | |
459 | @item FE_UNDERFLOW | |
460 | The underflow exception. | |
461 | @comment fenv.h | |
462 | @comment ISO | |
463 | @item FE_OVERFLOW | |
464 | The overflow exception. | |
465 | @comment fenv.h | |
466 | @comment ISO | |
467 | @item FE_INVALID | |
468 | The invalid exception. | |
b4012b75 UD |
469 | @end vtable |
470 | ||
7a68c94a UD |
471 | The macro @code{FE_ALL_EXCEPT} is the bitwise OR of all exception macros |
472 | which are supported by the FP implementation. | |
b4012b75 | 473 | |
7a68c94a UD |
474 | These functions allow you to clear exception flags, test for exceptions, |
475 | and save and restore the set of exceptions flagged. | |
b4012b75 | 476 | |
7a68c94a | 477 | @comment fenv.h |
b4012b75 | 478 | @comment ISO |
63ae7b63 | 479 | @deftypefun int feclearexcept (int @var{excepts}) |
7a68c94a UD |
480 | This function clears all of the supported exception flags indicated by |
481 | @var{excepts}. | |
63ae7b63 UD |
482 | |
483 | The function returns zero in case the operation was successful, a | |
484 | non-zero value otherwise. | |
485 | @end deftypefun | |
486 | ||
487 | @comment fenv.h | |
488 | @comment ISO | |
489 | @deftypefun int feraiseexcept (int @var{excepts}) | |
490 | This function raises the supported exceptions indicated by | |
491 | @var{excepts}. If more than one exception bit in @var{excepts} is set | |
492 | the order in which the exceptions are raised is undefined except that | |
493 | overflow (@code{FE_OVERFLOW}) or underflow (@code{FE_UNDERFLOW}) are | |
494 | raised before inexact (@code{FE_INEXACT}). Whether for overflow or | |
495 | underflow the inexact exception is also raised is also implementation | |
496 | dependent. | |
497 | ||
498 | The function returns zero in case the operation was successful, a | |
499 | non-zero value otherwise. | |
7a68c94a UD |
500 | @end deftypefun |
501 | ||
502 | @comment fenv.h | |
503 | @comment ISO | |
504 | @deftypefun int fetestexcept (int @var{excepts}) | |
505 | Test whether the exception flags indicated by the parameter @var{except} | |
506 | are currently set. If any of them are, a nonzero value is returned | |
507 | which specifies which exceptions are set. Otherwise the result is zero. | |
508 | @end deftypefun | |
509 | ||
510 | To understand these functions, imagine that the status word is an | |
511 | integer variable named @var{status}. @code{feclearexcept} is then | |
512 | equivalent to @samp{status &= ~excepts} and @code{fetestexcept} is | |
513 | equivalent to @samp{(status & excepts)}. The actual implementation may | |
514 | be very different, of course. | |
515 | ||
516 | Exception flags are only cleared when the program explicitly requests it, | |
517 | by calling @code{feclearexcept}. If you want to check for exceptions | |
518 | from a set of calculations, you should clear all the flags first. Here | |
519 | is a simple example of the way to use @code{fetestexcept}: | |
b4012b75 UD |
520 | |
521 | @smallexample | |
7a68c94a UD |
522 | @{ |
523 | double f; | |
524 | int raised; | |
525 | feclearexcept (FE_ALL_EXCEPT); | |
526 | f = compute (); | |
527 | raised = fetestexcept (FE_OVERFLOW | FE_INVALID); | |
528 | if (raised & FE_OVERFLOW) @{ /* ... */ @} | |
529 | if (raised & FE_INVALID) @{ /* ... */ @} | |
530 | /* ... */ | |
531 | @} | |
b4012b75 UD |
532 | @end smallexample |
533 | ||
7a68c94a UD |
534 | You cannot explicitly set bits in the status word. You can, however, |
535 | save the entire status word and restore it later. This is done with the | |
536 | following functions: | |
b4012b75 | 537 | |
7a68c94a | 538 | @comment fenv.h |
b4012b75 | 539 | @comment ISO |
63ae7b63 | 540 | @deftypefun int fegetexceptflag (fexcept_t *@var{flagp}, int @var{excepts}) |
7a68c94a UD |
541 | This function stores in the variable pointed to by @var{flagp} an |
542 | implementation-defined value representing the current setting of the | |
543 | exception flags indicated by @var{excepts}. | |
63ae7b63 UD |
544 | |
545 | The function returns zero in case the operation was successful, a | |
546 | non-zero value otherwise. | |
7a68c94a | 547 | @end deftypefun |
b4012b75 | 548 | |
7a68c94a UD |
549 | @comment fenv.h |
550 | @comment ISO | |
63ae7b63 | 551 | @deftypefun int fesetexceptflag (const fexcept_t *@var{flagp}, int |
7a68c94a UD |
552 | @var{excepts}) |
553 | This function restores the flags for the exceptions indicated by | |
554 | @var{excepts} to the values stored in the variable pointed to by | |
555 | @var{flagp}. | |
63ae7b63 UD |
556 | |
557 | The function returns zero in case the operation was successful, a | |
558 | non-zero value otherwise. | |
7a68c94a UD |
559 | @end deftypefun |
560 | ||
561 | Note that the value stored in @code{fexcept_t} bears no resemblance to | |
562 | the bit mask returned by @code{fetestexcept}. The type may not even be | |
563 | an integer. Do not attempt to modify an @code{fexcept_t} variable. | |
564 | ||
565 | @node Math Error Reporting | |
566 | @subsection Error Reporting by Mathematical Functions | |
567 | @cindex errors, mathematical | |
568 | @cindex domain error | |
569 | @cindex range error | |
570 | ||
571 | Many of the math functions are defined only over a subset of the real or | |
572 | complex numbers. Even if they are mathematically defined, their result | |
573 | may be larger or smaller than the range representable by their return | |
574 | type. These are known as @dfn{domain errors}, @dfn{overflows}, and | |
575 | @dfn{underflows}, respectively. Math functions do several things when | |
576 | one of these errors occurs. In this manual we will refer to the | |
577 | complete response as @dfn{signalling} a domain error, overflow, or | |
578 | underflow. | |
579 | ||
580 | When a math function suffers a domain error, it raises the invalid | |
581 | exception and returns NaN. It also sets @var{errno} to @code{EDOM}; | |
582 | this is for compatibility with old systems that do not support @w{IEEE | |
583 | 754} exception handling. Likewise, when overflow occurs, math | |
584 | functions raise the overflow exception and return @math{@infinity{}} or | |
585 | @math{-@infinity{}} as appropriate. They also set @var{errno} to | |
586 | @code{ERANGE}. When underflow occurs, the underflow exception is | |
587 | raised, and zero (appropriately signed) is returned. @var{errno} may be | |
588 | set to @code{ERANGE}, but this is not guaranteed. | |
589 | ||
590 | Some of the math functions are defined mathematically to result in a | |
591 | complex value over parts of their domains. The most familiar example of | |
592 | this is taking the square root of a negative number. The complex math | |
593 | functions, such as @code{csqrt}, will return the appropriate complex value | |
594 | in this case. The real-valued functions, such as @code{sqrt}, will | |
595 | signal a domain error. | |
596 | ||
597 | Some older hardware does not support infinities. On that hardware, | |
598 | overflows instead return a particular very large number (usually the | |
599 | largest representable number). @file{math.h} defines macros you can use | |
600 | to test for overflow on both old and new hardware. | |
b4012b75 UD |
601 | |
602 | @comment math.h | |
603 | @comment ISO | |
7a68c94a | 604 | @deftypevr Macro double HUGE_VAL |
4260bc74 UD |
605 | @comment math.h |
606 | @comment ISO | |
7a68c94a | 607 | @deftypevrx Macro float HUGE_VALF |
4260bc74 UD |
608 | @comment math.h |
609 | @comment ISO | |
7a68c94a UD |
610 | @deftypevrx Macro {long double} HUGE_VALL |
611 | An expression representing a particular very large number. On machines | |
612 | that use @w{IEEE 754} floating point format, @code{HUGE_VAL} is infinity. | |
613 | On other machines, it's typically the largest positive number that can | |
614 | be represented. | |
615 | ||
616 | Mathematical functions return the appropriately typed version of | |
617 | @code{HUGE_VAL} or @code{@minus{}HUGE_VAL} when the result is too large | |
618 | to be represented. | |
619 | @end deftypevr | |
b4012b75 | 620 | |
7a68c94a UD |
621 | @node Rounding |
622 | @section Rounding Modes | |
623 | ||
624 | Floating-point calculations are carried out internally with extra | |
625 | precision, and then rounded to fit into the destination type. This | |
626 | ensures that results are as precise as the input data. @w{IEEE 754} | |
627 | defines four possible rounding modes: | |
628 | ||
629 | @table @asis | |
630 | @item Round to nearest. | |
631 | This is the default mode. It should be used unless there is a specific | |
632 | need for one of the others. In this mode results are rounded to the | |
633 | nearest representable value. If the result is midway between two | |
634 | representable values, the even representable is chosen. @dfn{Even} here | |
635 | means the lowest-order bit is zero. This rounding mode prevents | |
636 | statistical bias and guarantees numeric stability: round-off errors in a | |
637 | lengthy calculation will remain smaller than half of @code{FLT_EPSILON}. | |
638 | ||
639 | @c @item Round toward @math{+@infinity{}} | |
640 | @item Round toward plus Infinity. | |
641 | All results are rounded to the smallest representable value | |
642 | which is greater than the result. | |
643 | ||
644 | @c @item Round toward @math{-@infinity{}} | |
645 | @item Round toward minus Infinity. | |
646 | All results are rounded to the largest representable value which is less | |
647 | than the result. | |
648 | ||
649 | @item Round toward zero. | |
650 | All results are rounded to the largest representable value whose | |
651 | magnitude is less than that of the result. In other words, if the | |
652 | result is negative it is rounded up; if it is positive, it is rounded | |
653 | down. | |
654 | @end table | |
b4012b75 | 655 | |
7a68c94a UD |
656 | @noindent |
657 | @file{fenv.h} defines constants which you can use to refer to the | |
658 | various rounding modes. Each one will be defined if and only if the FPU | |
659 | supports the corresponding rounding mode. | |
b4012b75 | 660 | |
7a68c94a UD |
661 | @table @code |
662 | @comment fenv.h | |
663 | @comment ISO | |
664 | @vindex FE_TONEAREST | |
665 | @item FE_TONEAREST | |
666 | Round to nearest. | |
b4012b75 | 667 | |
7a68c94a UD |
668 | @comment fenv.h |
669 | @comment ISO | |
670 | @vindex FE_UPWARD | |
671 | @item FE_UPWARD | |
672 | Round toward @math{+@infinity{}}. | |
b4012b75 | 673 | |
7a68c94a UD |
674 | @comment fenv.h |
675 | @comment ISO | |
676 | @vindex FE_DOWNWARD | |
677 | @item FE_DOWNWARD | |
678 | Round toward @math{-@infinity{}}. | |
b4012b75 | 679 | |
7a68c94a UD |
680 | @comment fenv.h |
681 | @comment ISO | |
682 | @vindex FE_TOWARDZERO | |
683 | @item FE_TOWARDZERO | |
684 | Round toward zero. | |
685 | @end table | |
b4012b75 | 686 | |
7a68c94a UD |
687 | Underflow is an unusual case. Normally, @w{IEEE 754} floating point |
688 | numbers are always normalized (@pxref{Floating Point Concepts}). | |
689 | Numbers smaller than @math{2^r} (where @math{r} is the minimum exponent, | |
690 | @code{FLT_MIN_RADIX-1} for @var{float}) cannot be represented as | |
691 | normalized numbers. Rounding all such numbers to zero or @math{2^r} | |
692 | would cause some algorithms to fail at 0. Therefore, they are left in | |
693 | denormalized form. That produces loss of precision, since some bits of | |
694 | the mantissa are stolen to indicate the decimal point. | |
695 | ||
696 | If a result is too small to be represented as a denormalized number, it | |
697 | is rounded to zero. However, the sign of the result is preserved; if | |
698 | the calculation was negative, the result is @dfn{negative zero}. | |
699 | Negative zero can also result from some operations on infinity, such as | |
700 | @math{4/-@infinity{}}. Negative zero behaves identically to zero except | |
701 | when the @code{copysign} or @code{signbit} functions are used to check | |
702 | the sign bit directly. | |
703 | ||
704 | At any time one of the above four rounding modes is selected. You can | |
705 | find out which one with this function: | |
706 | ||
707 | @comment fenv.h | |
708 | @comment ISO | |
709 | @deftypefun int fegetround (void) | |
710 | Returns the currently selected rounding mode, represented by one of the | |
711 | values of the defined rounding mode macros. | |
712 | @end deftypefun | |
b4012b75 | 713 | |
7a68c94a UD |
714 | @noindent |
715 | To change the rounding mode, use this function: | |
b4012b75 | 716 | |
7a68c94a UD |
717 | @comment fenv.h |
718 | @comment ISO | |
719 | @deftypefun int fesetround (int @var{round}) | |
720 | Changes the currently selected rounding mode to @var{round}. If | |
721 | @var{round} does not correspond to one of the supported rounding modes | |
722 | nothing is changed. @code{fesetround} returns a nonzero value if it | |
723 | changed the rounding mode, zero if the mode is not supported. | |
724 | @end deftypefun | |
b4012b75 | 725 | |
7a68c94a UD |
726 | You should avoid changing the rounding mode if possible. It can be an |
727 | expensive operation; also, some hardware requires you to compile your | |
728 | program differently for it to work. The resulting code may run slower. | |
729 | See your compiler documentation for details. | |
730 | @c This section used to claim that functions existed to round one number | |
731 | @c in a specific fashion. I can't find any functions in the library | |
732 | @c that do that. -zw | |
733 | ||
734 | @node Control Functions | |
735 | @section Floating-Point Control Functions | |
736 | ||
737 | @w{IEEE 754} floating-point implementations allow the programmer to | |
738 | decide whether traps will occur for each of the exceptions, by setting | |
739 | bits in the @dfn{control word}. In C, traps result in the program | |
740 | receiving the @code{SIGFPE} signal; see @ref{Signal Handling}. | |
741 | ||
742 | @strong{Note:} @w{IEEE 754} says that trap handlers are given details of | |
743 | the exceptional situation, and can set the result value. C signals do | |
744 | not provide any mechanism to pass this information back and forth. | |
745 | Trapping exceptions in C is therefore not very useful. | |
746 | ||
747 | It is sometimes necessary to save the state of the floating-point unit | |
748 | while you perform some calculation. The library provides functions | |
749 | which save and restore the exception flags, the set of exceptions that | |
750 | generate traps, and the rounding mode. This information is known as the | |
751 | @dfn{floating-point environment}. | |
752 | ||
753 | The functions to save and restore the floating-point environment all use | |
754 | a variable of type @code{fenv_t} to store information. This type is | |
755 | defined in @file{fenv.h}. Its size and contents are | |
756 | implementation-defined. You should not attempt to manipulate a variable | |
757 | of this type directly. | |
758 | ||
759 | To save the state of the FPU, use one of these functions: | |
760 | ||
761 | @comment fenv.h | |
b4012b75 | 762 | @comment ISO |
63ae7b63 | 763 | @deftypefun int fegetenv (fenv_t *@var{envp}) |
7a68c94a UD |
764 | Store the floating-point environment in the variable pointed to by |
765 | @var{envp}. | |
63ae7b63 UD |
766 | |
767 | The function returns zero in case the operation was successful, a | |
768 | non-zero value otherwise. | |
b4012b75 UD |
769 | @end deftypefun |
770 | ||
7a68c94a | 771 | @comment fenv.h |
b4012b75 | 772 | @comment ISO |
7a68c94a UD |
773 | @deftypefun int feholdexcept (fenv_t *@var{envp}) |
774 | Store the current floating-point environment in the object pointed to by | |
775 | @var{envp}. Then clear all exception flags, and set the FPU to trap no | |
776 | exceptions. Not all FPUs support trapping no exceptions; if | |
777 | @code{feholdexcept} cannot set this mode, it returns zero. If it | |
778 | succeeds, it returns a nonzero value. | |
b4012b75 UD |
779 | @end deftypefun |
780 | ||
7a68c94a UD |
781 | The functions which restore the floating-point environment can take two |
782 | kinds of arguments: | |
b4012b75 | 783 | |
7a68c94a UD |
784 | @itemize @bullet |
785 | @item | |
786 | Pointers to @code{fenv_t} objects, which were initialized previously by a | |
787 | call to @code{fegetenv} or @code{feholdexcept}. | |
788 | @item | |
789 | @vindex FE_DFL_ENV | |
790 | The special macro @code{FE_DFL_ENV} which represents the floating-point | |
791 | environment as it was available at program start. | |
792 | @item | |
793 | Implementation defined macros with names starting with @code{FE_}. | |
b4012b75 | 794 | |
7a68c94a UD |
795 | @vindex FE_NOMASK_ENV |
796 | If possible, the GNU C Library defines a macro @code{FE_NOMASK_ENV} | |
797 | which represents an environment where every exception raised causes a | |
798 | trap to occur. You can test for this macro using @code{#ifdef}. It is | |
799 | only defined if @code{_GNU_SOURCE} is defined. | |
800 | ||
801 | Some platforms might define other predefined environments. | |
802 | @end itemize | |
803 | ||
804 | @noindent | |
805 | To set the floating-point environment, you can use either of these | |
806 | functions: | |
807 | ||
808 | @comment fenv.h | |
b4012b75 | 809 | @comment ISO |
63ae7b63 | 810 | @deftypefun int fesetenv (const fenv_t *@var{envp}) |
7a68c94a | 811 | Set the floating-point environment to that described by @var{envp}. |
63ae7b63 UD |
812 | |
813 | The function returns zero in case the operation was successful, a | |
814 | non-zero value otherwise. | |
b4012b75 UD |
815 | @end deftypefun |
816 | ||
7a68c94a | 817 | @comment fenv.h |
b4012b75 | 818 | @comment ISO |
63ae7b63 | 819 | @deftypefun int feupdateenv (const fenv_t *@var{envp}) |
7a68c94a UD |
820 | Like @code{fesetenv}, this function sets the floating-point environment |
821 | to that described by @var{envp}. However, if any exceptions were | |
822 | flagged in the status word before @code{feupdateenv} was called, they | |
823 | remain flagged after the call. In other words, after @code{feupdateenv} | |
824 | is called, the status word is the bitwise OR of the previous status word | |
825 | and the one saved in @var{envp}. | |
63ae7b63 UD |
826 | |
827 | The function returns zero in case the operation was successful, a | |
828 | non-zero value otherwise. | |
b4012b75 UD |
829 | @end deftypefun |
830 | ||
05ef7ce9 UD |
831 | @noindent |
832 | To control for individual exceptions if raising them causes a trap to | |
833 | occur, you can use the following two functions. | |
834 | ||
835 | @strong{Portability Note:} These functions are all GNU extensions. | |
836 | ||
837 | @comment fenv.h | |
838 | @comment GNU | |
839 | @deftypefun int feenableexcept (int @var{excepts}) | |
840 | This functions enables traps for each of the exceptions as indicated by | |
841 | the parameter @var{except}. The individual excepetions are described in | |
6e8afc1c | 842 | @ref{Status bit operations}. Only the specified exceptions are |
05ef7ce9 UD |
843 | enabled, the status of the other exceptions is not changed. |
844 | ||
845 | The function returns the previous enabled exceptions in case the | |
846 | operation was successful, @code{-1} otherwise. | |
847 | @end deftypefun | |
848 | ||
849 | @comment fenv.h | |
850 | @comment GNU | |
851 | @deftypefun int fedisableexcept (int @var{excepts}) | |
852 | This functions disables traps for each of the exceptions as indicated by | |
853 | the parameter @var{except}. The individual excepetions are described in | |
6e8afc1c | 854 | @ref{Status bit operations}. Only the specified exceptions are |
05ef7ce9 UD |
855 | disabled, the status of the other exceptions is not changed. |
856 | ||
857 | The function returns the previous enabled exceptions in case the | |
858 | operation was successful, @code{-1} otherwise. | |
859 | @end deftypefun | |
860 | ||
861 | @comment fenv.h | |
862 | @comment GNU | |
863 | @deftypefun int fegetexcept (int @var{excepts}) | |
864 | The function returns a bitmask of all currently enabled exceptions. It | |
865 | returns @code{-1} in case of failure. | |
6e8afc1c | 866 | @end deftypefun |
05ef7ce9 | 867 | |
7a68c94a UD |
868 | @node Arithmetic Functions |
869 | @section Arithmetic Functions | |
b4012b75 | 870 | |
7a68c94a UD |
871 | The C library provides functions to do basic operations on |
872 | floating-point numbers. These include absolute value, maximum and minimum, | |
873 | normalization, bit twiddling, rounding, and a few others. | |
b4012b75 | 874 | |
7a68c94a UD |
875 | @menu |
876 | * Absolute Value:: Absolute values of integers and floats. | |
877 | * Normalization Functions:: Extracting exponents and putting them back. | |
878 | * Rounding Functions:: Rounding floats to integers. | |
879 | * Remainder Functions:: Remainders on division, precisely defined. | |
880 | * FP Bit Twiddling:: Sign bit adjustment. Adding epsilon. | |
881 | * FP Comparison Functions:: Comparisons without risk of exceptions. | |
882 | * Misc FP Arithmetic:: Max, min, positive difference, multiply-add. | |
883 | @end menu | |
b4012b75 | 884 | |
28f540f4 | 885 | @node Absolute Value |
7a68c94a | 886 | @subsection Absolute Value |
28f540f4 RM |
887 | @cindex absolute value functions |
888 | ||
889 | These functions are provided for obtaining the @dfn{absolute value} (or | |
890 | @dfn{magnitude}) of a number. The absolute value of a real number | |
2d26e9eb | 891 | @var{x} is @var{x} if @var{x} is positive, @minus{}@var{x} if @var{x} is |
28f540f4 RM |
892 | negative. For a complex number @var{z}, whose real part is @var{x} and |
893 | whose imaginary part is @var{y}, the absolute value is @w{@code{sqrt | |
894 | (@var{x}*@var{x} + @var{y}*@var{y})}}. | |
895 | ||
896 | @pindex math.h | |
897 | @pindex stdlib.h | |
fe0ec73e | 898 | Prototypes for @code{abs}, @code{labs} and @code{llabs} are in @file{stdlib.h}; |
e518937a | 899 | @code{imaxabs} is declared in @file{inttypes.h}; |
7a68c94a | 900 | @code{fabs}, @code{fabsf} and @code{fabsl} are declared in @file{math.h}. |
b4012b75 | 901 | @code{cabs}, @code{cabsf} and @code{cabsl} are declared in @file{complex.h}. |
28f540f4 RM |
902 | |
903 | @comment stdlib.h | |
f65fd747 | 904 | @comment ISO |
28f540f4 | 905 | @deftypefun int abs (int @var{number}) |
4260bc74 UD |
906 | @comment stdlib.h |
907 | @comment ISO | |
7a68c94a | 908 | @deftypefunx {long int} labs (long int @var{number}) |
4260bc74 UD |
909 | @comment stdlib.h |
910 | @comment ISO | |
7a68c94a | 911 | @deftypefunx {long long int} llabs (long long int @var{number}) |
e518937a UD |
912 | @comment inttypes.h |
913 | @comment ISO | |
914 | @deftypefunx intmax_t imaxabs (intmax_t @var{number}) | |
7a68c94a | 915 | These functions return the absolute value of @var{number}. |
28f540f4 RM |
916 | |
917 | Most computers use a two's complement integer representation, in which | |
918 | the absolute value of @code{INT_MIN} (the smallest possible @code{int}) | |
919 | cannot be represented; thus, @w{@code{abs (INT_MIN)}} is not defined. | |
28f540f4 | 920 | |
ec751a23 | 921 | @code{llabs} and @code{imaxdiv} are new to @w{ISO C99}. |
fe0ec73e UD |
922 | @end deftypefun |
923 | ||
28f540f4 | 924 | @comment math.h |
f65fd747 | 925 | @comment ISO |
28f540f4 | 926 | @deftypefun double fabs (double @var{number}) |
4260bc74 UD |
927 | @comment math.h |
928 | @comment ISO | |
779ae82e | 929 | @deftypefunx float fabsf (float @var{number}) |
4260bc74 UD |
930 | @comment math.h |
931 | @comment ISO | |
779ae82e | 932 | @deftypefunx {long double} fabsl (long double @var{number}) |
28f540f4 RM |
933 | This function returns the absolute value of the floating-point number |
934 | @var{number}. | |
935 | @end deftypefun | |
936 | ||
b4012b75 UD |
937 | @comment complex.h |
938 | @comment ISO | |
939 | @deftypefun double cabs (complex double @var{z}) | |
4260bc74 UD |
940 | @comment complex.h |
941 | @comment ISO | |
779ae82e | 942 | @deftypefunx float cabsf (complex float @var{z}) |
4260bc74 UD |
943 | @comment complex.h |
944 | @comment ISO | |
779ae82e | 945 | @deftypefunx {long double} cabsl (complex long double @var{z}) |
7a68c94a UD |
946 | These functions return the absolute value of the complex number @var{z} |
947 | (@pxref{Complex Numbers}). The absolute value of a complex number is: | |
28f540f4 RM |
948 | |
949 | @smallexample | |
b4012b75 | 950 | sqrt (creal (@var{z}) * creal (@var{z}) + cimag (@var{z}) * cimag (@var{z})) |
28f540f4 | 951 | @end smallexample |
dfd2257a | 952 | |
7a68c94a UD |
953 | This function should always be used instead of the direct formula |
954 | because it takes special care to avoid losing precision. It may also | |
955 | take advantage of hardware support for this operation. See @code{hypot} | |
8b7fb588 | 956 | in @ref{Exponents and Logarithms}. |
28f540f4 RM |
957 | @end deftypefun |
958 | ||
959 | @node Normalization Functions | |
7a68c94a | 960 | @subsection Normalization Functions |
28f540f4 RM |
961 | @cindex normalization functions (floating-point) |
962 | ||
963 | The functions described in this section are primarily provided as a way | |
964 | to efficiently perform certain low-level manipulations on floating point | |
965 | numbers that are represented internally using a binary radix; | |
966 | see @ref{Floating Point Concepts}. These functions are required to | |
967 | have equivalent behavior even if the representation does not use a radix | |
968 | of 2, but of course they are unlikely to be particularly efficient in | |
969 | those cases. | |
970 | ||
971 | @pindex math.h | |
972 | All these functions are declared in @file{math.h}. | |
973 | ||
974 | @comment math.h | |
f65fd747 | 975 | @comment ISO |
28f540f4 | 976 | @deftypefun double frexp (double @var{value}, int *@var{exponent}) |
4260bc74 UD |
977 | @comment math.h |
978 | @comment ISO | |
779ae82e | 979 | @deftypefunx float frexpf (float @var{value}, int *@var{exponent}) |
4260bc74 UD |
980 | @comment math.h |
981 | @comment ISO | |
779ae82e | 982 | @deftypefunx {long double} frexpl (long double @var{value}, int *@var{exponent}) |
b4012b75 | 983 | These functions are used to split the number @var{value} |
28f540f4 RM |
984 | into a normalized fraction and an exponent. |
985 | ||
986 | If the argument @var{value} is not zero, the return value is @var{value} | |
987 | times a power of two, and is always in the range 1/2 (inclusive) to 1 | |
988 | (exclusive). The corresponding exponent is stored in | |
989 | @code{*@var{exponent}}; the return value multiplied by 2 raised to this | |
990 | exponent equals the original number @var{value}. | |
991 | ||
992 | For example, @code{frexp (12.8, &exponent)} returns @code{0.8} and | |
993 | stores @code{4} in @code{exponent}. | |
994 | ||
995 | If @var{value} is zero, then the return value is zero and | |
996 | zero is stored in @code{*@var{exponent}}. | |
997 | @end deftypefun | |
998 | ||
999 | @comment math.h | |
f65fd747 | 1000 | @comment ISO |
28f540f4 | 1001 | @deftypefun double ldexp (double @var{value}, int @var{exponent}) |
4260bc74 UD |
1002 | @comment math.h |
1003 | @comment ISO | |
779ae82e | 1004 | @deftypefunx float ldexpf (float @var{value}, int @var{exponent}) |
4260bc74 UD |
1005 | @comment math.h |
1006 | @comment ISO | |
779ae82e | 1007 | @deftypefunx {long double} ldexpl (long double @var{value}, int @var{exponent}) |
b4012b75 | 1008 | These functions return the result of multiplying the floating-point |
28f540f4 RM |
1009 | number @var{value} by 2 raised to the power @var{exponent}. (It can |
1010 | be used to reassemble floating-point numbers that were taken apart | |
1011 | by @code{frexp}.) | |
1012 | ||
1013 | For example, @code{ldexp (0.8, 4)} returns @code{12.8}. | |
1014 | @end deftypefun | |
1015 | ||
7a68c94a UD |
1016 | The following functions, which come from BSD, provide facilities |
1017 | equivalent to those of @code{ldexp} and @code{frexp}. | |
28f540f4 RM |
1018 | |
1019 | @comment math.h | |
1020 | @comment BSD | |
1021 | @deftypefun double logb (double @var{x}) | |
4260bc74 UD |
1022 | @comment math.h |
1023 | @comment BSD | |
779ae82e | 1024 | @deftypefunx float logbf (float @var{x}) |
4260bc74 UD |
1025 | @comment math.h |
1026 | @comment BSD | |
779ae82e | 1027 | @deftypefunx {long double} logbl (long double @var{x}) |
7a68c94a | 1028 | These functions return the integer part of the base-2 logarithm of |
28f540f4 RM |
1029 | @var{x}, an integer value represented in type @code{double}. This is |
1030 | the highest integer power of @code{2} contained in @var{x}. The sign of | |
1031 | @var{x} is ignored. For example, @code{logb (3.5)} is @code{1.0} and | |
1032 | @code{logb (4.0)} is @code{2.0}. | |
1033 | ||
1034 | When @code{2} raised to this power is divided into @var{x}, it gives a | |
1035 | quotient between @code{1} (inclusive) and @code{2} (exclusive). | |
1036 | ||
7a68c94a UD |
1037 | If @var{x} is zero, the return value is minus infinity if the machine |
1038 | supports infinities, and a very small number if it does not. If @var{x} | |
1039 | is infinity, the return value is infinity. | |
1040 | ||
1041 | For finite @var{x}, the value returned by @code{logb} is one less than | |
1042 | the value that @code{frexp} would store into @code{*@var{exponent}}. | |
1043 | @end deftypefun | |
1044 | ||
1045 | @comment math.h | |
1046 | @comment BSD | |
1047 | @deftypefun double scalb (double @var{value}, int @var{exponent}) | |
4260bc74 UD |
1048 | @comment math.h |
1049 | @comment BSD | |
7a68c94a | 1050 | @deftypefunx float scalbf (float @var{value}, int @var{exponent}) |
4260bc74 UD |
1051 | @comment math.h |
1052 | @comment BSD | |
7a68c94a UD |
1053 | @deftypefunx {long double} scalbl (long double @var{value}, int @var{exponent}) |
1054 | The @code{scalb} function is the BSD name for @code{ldexp}. | |
1055 | @end deftypefun | |
1056 | ||
1057 | @comment math.h | |
1058 | @comment BSD | |
1059 | @deftypefun {long long int} scalbn (double @var{x}, int n) | |
4260bc74 UD |
1060 | @comment math.h |
1061 | @comment BSD | |
7a68c94a | 1062 | @deftypefunx {long long int} scalbnf (float @var{x}, int n) |
4260bc74 UD |
1063 | @comment math.h |
1064 | @comment BSD | |
7a68c94a UD |
1065 | @deftypefunx {long long int} scalbnl (long double @var{x}, int n) |
1066 | @code{scalbn} is identical to @code{scalb}, except that the exponent | |
1067 | @var{n} is an @code{int} instead of a floating-point number. | |
1068 | @end deftypefun | |
1069 | ||
1070 | @comment math.h | |
1071 | @comment BSD | |
1072 | @deftypefun {long long int} scalbln (double @var{x}, long int n) | |
4260bc74 UD |
1073 | @comment math.h |
1074 | @comment BSD | |
7a68c94a | 1075 | @deftypefunx {long long int} scalblnf (float @var{x}, long int n) |
4260bc74 UD |
1076 | @comment math.h |
1077 | @comment BSD | |
7a68c94a UD |
1078 | @deftypefunx {long long int} scalblnl (long double @var{x}, long int n) |
1079 | @code{scalbln} is identical to @code{scalb}, except that the exponent | |
1080 | @var{n} is a @code{long int} instead of a floating-point number. | |
1081 | @end deftypefun | |
28f540f4 | 1082 | |
7a68c94a UD |
1083 | @comment math.h |
1084 | @comment BSD | |
1085 | @deftypefun {long long int} significand (double @var{x}) | |
4260bc74 UD |
1086 | @comment math.h |
1087 | @comment BSD | |
7a68c94a | 1088 | @deftypefunx {long long int} significandf (float @var{x}) |
4260bc74 UD |
1089 | @comment math.h |
1090 | @comment BSD | |
7a68c94a UD |
1091 | @deftypefunx {long long int} significandl (long double @var{x}) |
1092 | @code{significand} returns the mantissa of @var{x} scaled to the range | |
1093 | @math{[1, 2)}. | |
1094 | It is equivalent to @w{@code{scalb (@var{x}, (double) -ilogb (@var{x}))}}. | |
1095 | ||
1096 | This function exists mainly for use in certain standardized tests | |
1097 | of @w{IEEE 754} conformance. | |
28f540f4 RM |
1098 | @end deftypefun |
1099 | ||
7a68c94a UD |
1100 | @node Rounding Functions |
1101 | @subsection Rounding Functions | |
28f540f4 RM |
1102 | @cindex converting floats to integers |
1103 | ||
1104 | @pindex math.h | |
7a68c94a UD |
1105 | The functions listed here perform operations such as rounding and |
1106 | truncation of floating-point values. Some of these functions convert | |
1107 | floating point numbers to integer values. They are all declared in | |
1108 | @file{math.h}. | |
28f540f4 RM |
1109 | |
1110 | You can also convert floating-point numbers to integers simply by | |
1111 | casting them to @code{int}. This discards the fractional part, | |
1112 | effectively rounding towards zero. However, this only works if the | |
1113 | result can actually be represented as an @code{int}---for very large | |
1114 | numbers, this is impossible. The functions listed here return the | |
1115 | result as a @code{double} instead to get around this problem. | |
1116 | ||
1117 | @comment math.h | |
f65fd747 | 1118 | @comment ISO |
28f540f4 | 1119 | @deftypefun double ceil (double @var{x}) |
4260bc74 UD |
1120 | @comment math.h |
1121 | @comment ISO | |
779ae82e | 1122 | @deftypefunx float ceilf (float @var{x}) |
4260bc74 UD |
1123 | @comment math.h |
1124 | @comment ISO | |
779ae82e | 1125 | @deftypefunx {long double} ceill (long double @var{x}) |
b4012b75 | 1126 | These functions round @var{x} upwards to the nearest integer, |
28f540f4 RM |
1127 | returning that value as a @code{double}. Thus, @code{ceil (1.5)} |
1128 | is @code{2.0}. | |
1129 | @end deftypefun | |
1130 | ||
1131 | @comment math.h | |
f65fd747 | 1132 | @comment ISO |
28f540f4 | 1133 | @deftypefun double floor (double @var{x}) |
4260bc74 UD |
1134 | @comment math.h |
1135 | @comment ISO | |
779ae82e | 1136 | @deftypefunx float floorf (float @var{x}) |
4260bc74 UD |
1137 | @comment math.h |
1138 | @comment ISO | |
779ae82e | 1139 | @deftypefunx {long double} floorl (long double @var{x}) |
b4012b75 | 1140 | These functions round @var{x} downwards to the nearest |
28f540f4 RM |
1141 | integer, returning that value as a @code{double}. Thus, @code{floor |
1142 | (1.5)} is @code{1.0} and @code{floor (-1.5)} is @code{-2.0}. | |
1143 | @end deftypefun | |
1144 | ||
7a68c94a UD |
1145 | @comment math.h |
1146 | @comment ISO | |
1147 | @deftypefun double trunc (double @var{x}) | |
4260bc74 UD |
1148 | @comment math.h |
1149 | @comment ISO | |
7a68c94a | 1150 | @deftypefunx float truncf (float @var{x}) |
4260bc74 UD |
1151 | @comment math.h |
1152 | @comment ISO | |
7a68c94a UD |
1153 | @deftypefunx {long double} truncl (long double @var{x}) |
1154 | @code{trunc} is another name for @code{floor} | |
1155 | @end deftypefun | |
1156 | ||
28f540f4 | 1157 | @comment math.h |
b4012b75 | 1158 | @comment ISO |
28f540f4 | 1159 | @deftypefun double rint (double @var{x}) |
4260bc74 UD |
1160 | @comment math.h |
1161 | @comment ISO | |
779ae82e | 1162 | @deftypefunx float rintf (float @var{x}) |
4260bc74 UD |
1163 | @comment math.h |
1164 | @comment ISO | |
779ae82e | 1165 | @deftypefunx {long double} rintl (long double @var{x}) |
b4012b75 | 1166 | These functions round @var{x} to an integer value according to the |
28f540f4 RM |
1167 | current rounding mode. @xref{Floating Point Parameters}, for |
1168 | information about the various rounding modes. The default | |
1169 | rounding mode is to round to the nearest integer; some machines | |
1170 | support other modes, but round-to-nearest is always used unless | |
7a68c94a UD |
1171 | you explicitly select another. |
1172 | ||
1173 | If @var{x} was not initially an integer, these functions raise the | |
1174 | inexact exception. | |
28f540f4 RM |
1175 | @end deftypefun |
1176 | ||
b4012b75 UD |
1177 | @comment math.h |
1178 | @comment ISO | |
1179 | @deftypefun double nearbyint (double @var{x}) | |
4260bc74 UD |
1180 | @comment math.h |
1181 | @comment ISO | |
779ae82e | 1182 | @deftypefunx float nearbyintf (float @var{x}) |
4260bc74 UD |
1183 | @comment math.h |
1184 | @comment ISO | |
779ae82e | 1185 | @deftypefunx {long double} nearbyintl (long double @var{x}) |
7a68c94a UD |
1186 | These functions return the same value as the @code{rint} functions, but |
1187 | do not raise the inexact exception if @var{x} is not an integer. | |
1188 | @end deftypefun | |
1189 | ||
1190 | @comment math.h | |
1191 | @comment ISO | |
1192 | @deftypefun double round (double @var{x}) | |
4260bc74 UD |
1193 | @comment math.h |
1194 | @comment ISO | |
7a68c94a | 1195 | @deftypefunx float roundf (float @var{x}) |
4260bc74 UD |
1196 | @comment math.h |
1197 | @comment ISO | |
7a68c94a UD |
1198 | @deftypefunx {long double} roundl (long double @var{x}) |
1199 | These functions are similar to @code{rint}, but they round halfway | |
1200 | cases away from zero instead of to the nearest even integer. | |
1201 | @end deftypefun | |
1202 | ||
1203 | @comment math.h | |
1204 | @comment ISO | |
1205 | @deftypefun {long int} lrint (double @var{x}) | |
4260bc74 UD |
1206 | @comment math.h |
1207 | @comment ISO | |
7a68c94a | 1208 | @deftypefunx {long int} lrintf (float @var{x}) |
4260bc74 UD |
1209 | @comment math.h |
1210 | @comment ISO | |
7a68c94a UD |
1211 | @deftypefunx {long int} lrintl (long double @var{x}) |
1212 | These functions are just like @code{rint}, but they return a | |
1213 | @code{long int} instead of a floating-point number. | |
1214 | @end deftypefun | |
1215 | ||
1216 | @comment math.h | |
1217 | @comment ISO | |
1218 | @deftypefun {long long int} llrint (double @var{x}) | |
4260bc74 UD |
1219 | @comment math.h |
1220 | @comment ISO | |
7a68c94a | 1221 | @deftypefunx {long long int} llrintf (float @var{x}) |
4260bc74 UD |
1222 | @comment math.h |
1223 | @comment ISO | |
7a68c94a UD |
1224 | @deftypefunx {long long int} llrintl (long double @var{x}) |
1225 | These functions are just like @code{rint}, but they return a | |
1226 | @code{long long int} instead of a floating-point number. | |
b4012b75 UD |
1227 | @end deftypefun |
1228 | ||
7a68c94a UD |
1229 | @comment math.h |
1230 | @comment ISO | |
1231 | @deftypefun {long int} lround (double @var{x}) | |
4260bc74 UD |
1232 | @comment math.h |
1233 | @comment ISO | |
7a68c94a | 1234 | @deftypefunx {long int} lroundf (float @var{x}) |
4260bc74 UD |
1235 | @comment math.h |
1236 | @comment ISO | |
7a68c94a UD |
1237 | @deftypefunx {long int} lroundl (long double @var{x}) |
1238 | These functions are just like @code{round}, but they return a | |
1239 | @code{long int} instead of a floating-point number. | |
1240 | @end deftypefun | |
1241 | ||
1242 | @comment math.h | |
1243 | @comment ISO | |
1244 | @deftypefun {long long int} llround (double @var{x}) | |
4260bc74 UD |
1245 | @comment math.h |
1246 | @comment ISO | |
7a68c94a | 1247 | @deftypefunx {long long int} llroundf (float @var{x}) |
4260bc74 UD |
1248 | @comment math.h |
1249 | @comment ISO | |
7a68c94a UD |
1250 | @deftypefunx {long long int} llroundl (long double @var{x}) |
1251 | These functions are just like @code{round}, but they return a | |
1252 | @code{long long int} instead of a floating-point number. | |
1253 | @end deftypefun | |
1254 | ||
1255 | ||
28f540f4 | 1256 | @comment math.h |
f65fd747 | 1257 | @comment ISO |
28f540f4 | 1258 | @deftypefun double modf (double @var{value}, double *@var{integer-part}) |
4260bc74 UD |
1259 | @comment math.h |
1260 | @comment ISO | |
f2ea0f5b | 1261 | @deftypefunx float modff (float @var{value}, float *@var{integer-part}) |
4260bc74 UD |
1262 | @comment math.h |
1263 | @comment ISO | |
779ae82e | 1264 | @deftypefunx {long double} modfl (long double @var{value}, long double *@var{integer-part}) |
b4012b75 | 1265 | These functions break the argument @var{value} into an integer part and a |
28f540f4 RM |
1266 | fractional part (between @code{-1} and @code{1}, exclusive). Their sum |
1267 | equals @var{value}. Each of the parts has the same sign as @var{value}, | |
7a68c94a | 1268 | and the integer part is always rounded toward zero. |
28f540f4 RM |
1269 | |
1270 | @code{modf} stores the integer part in @code{*@var{integer-part}}, and | |
1271 | returns the fractional part. For example, @code{modf (2.5, &intpart)} | |
1272 | returns @code{0.5} and stores @code{2.0} into @code{intpart}. | |
1273 | @end deftypefun | |
1274 | ||
7a68c94a UD |
1275 | @node Remainder Functions |
1276 | @subsection Remainder Functions | |
1277 | ||
1278 | The functions in this section compute the remainder on division of two | |
1279 | floating-point numbers. Each is a little different; pick the one that | |
1280 | suits your problem. | |
1281 | ||
28f540f4 | 1282 | @comment math.h |
f65fd747 | 1283 | @comment ISO |
28f540f4 | 1284 | @deftypefun double fmod (double @var{numerator}, double @var{denominator}) |
4260bc74 UD |
1285 | @comment math.h |
1286 | @comment ISO | |
779ae82e | 1287 | @deftypefunx float fmodf (float @var{numerator}, float @var{denominator}) |
4260bc74 UD |
1288 | @comment math.h |
1289 | @comment ISO | |
779ae82e | 1290 | @deftypefunx {long double} fmodl (long double @var{numerator}, long double @var{denominator}) |
b4012b75 | 1291 | These functions compute the remainder from the division of |
28f540f4 RM |
1292 | @var{numerator} by @var{denominator}. Specifically, the return value is |
1293 | @code{@var{numerator} - @w{@var{n} * @var{denominator}}}, where @var{n} | |
1294 | is the quotient of @var{numerator} divided by @var{denominator}, rounded | |
1295 | towards zero to an integer. Thus, @w{@code{fmod (6.5, 2.3)}} returns | |
1296 | @code{1.9}, which is @code{6.5} minus @code{4.6}. | |
1297 | ||
1298 | The result has the same sign as the @var{numerator} and has magnitude | |
1299 | less than the magnitude of the @var{denominator}. | |
1300 | ||
7a68c94a | 1301 | If @var{denominator} is zero, @code{fmod} signals a domain error. |
28f540f4 RM |
1302 | @end deftypefun |
1303 | ||
1304 | @comment math.h | |
1305 | @comment BSD | |
1306 | @deftypefun double drem (double @var{numerator}, double @var{denominator}) | |
4260bc74 UD |
1307 | @comment math.h |
1308 | @comment BSD | |
779ae82e | 1309 | @deftypefunx float dremf (float @var{numerator}, float @var{denominator}) |
4260bc74 UD |
1310 | @comment math.h |
1311 | @comment BSD | |
779ae82e | 1312 | @deftypefunx {long double} dreml (long double @var{numerator}, long double @var{denominator}) |
7a68c94a | 1313 | These functions are like @code{fmod} except that they rounds the |
28f540f4 RM |
1314 | internal quotient @var{n} to the nearest integer instead of towards zero |
1315 | to an integer. For example, @code{drem (6.5, 2.3)} returns @code{-0.4}, | |
1316 | which is @code{6.5} minus @code{6.9}. | |
1317 | ||
1318 | The absolute value of the result is less than or equal to half the | |
1319 | absolute value of the @var{denominator}. The difference between | |
1320 | @code{fmod (@var{numerator}, @var{denominator})} and @code{drem | |
1321 | (@var{numerator}, @var{denominator})} is always either | |
1322 | @var{denominator}, minus @var{denominator}, or zero. | |
1323 | ||
7a68c94a | 1324 | If @var{denominator} is zero, @code{drem} signals a domain error. |
28f540f4 RM |
1325 | @end deftypefun |
1326 | ||
7a68c94a UD |
1327 | @comment math.h |
1328 | @comment BSD | |
1329 | @deftypefun double remainder (double @var{numerator}, double @var{denominator}) | |
4260bc74 UD |
1330 | @comment math.h |
1331 | @comment BSD | |
7a68c94a | 1332 | @deftypefunx float remainderf (float @var{numerator}, float @var{denominator}) |
4260bc74 UD |
1333 | @comment math.h |
1334 | @comment BSD | |
7a68c94a UD |
1335 | @deftypefunx {long double} remainderl (long double @var{numerator}, long double @var{denominator}) |
1336 | This function is another name for @code{drem}. | |
1337 | @end deftypefun | |
28f540f4 | 1338 | |
7a68c94a UD |
1339 | @node FP Bit Twiddling |
1340 | @subsection Setting and modifying single bits of FP values | |
fe0ec73e UD |
1341 | @cindex FP arithmetic |
1342 | ||
7a68c94a | 1343 | There are some operations that are too complicated or expensive to |
ec751a23 | 1344 | perform by hand on floating-point numbers. @w{ISO C99} defines |
7a68c94a UD |
1345 | functions to do these operations, which mostly involve changing single |
1346 | bits. | |
fe0ec73e UD |
1347 | |
1348 | @comment math.h | |
1349 | @comment ISO | |
1350 | @deftypefun double copysign (double @var{x}, double @var{y}) | |
4260bc74 UD |
1351 | @comment math.h |
1352 | @comment ISO | |
fe0ec73e | 1353 | @deftypefunx float copysignf (float @var{x}, float @var{y}) |
4260bc74 UD |
1354 | @comment math.h |
1355 | @comment ISO | |
fe0ec73e | 1356 | @deftypefunx {long double} copysignl (long double @var{x}, long double @var{y}) |
7a68c94a UD |
1357 | These functions return @var{x} but with the sign of @var{y}. They work |
1358 | even if @var{x} or @var{y} are NaN or zero. Both of these can carry a | |
1359 | sign (although not all implementations support it) and this is one of | |
1360 | the few operations that can tell the difference. | |
fe0ec73e | 1361 | |
7a68c94a UD |
1362 | @code{copysign} never raises an exception. |
1363 | @c except signalling NaNs | |
fe0ec73e UD |
1364 | |
1365 | This function is defined in @w{IEC 559} (and the appendix with | |
1366 | recommended functions in @w{IEEE 754}/@w{IEEE 854}). | |
1367 | @end deftypefun | |
1368 | ||
1369 | @comment math.h | |
1370 | @comment ISO | |
1371 | @deftypefun int signbit (@emph{float-type} @var{x}) | |
1372 | @code{signbit} is a generic macro which can work on all floating-point | |
1373 | types. It returns a nonzero value if the value of @var{x} has its sign | |
1374 | bit set. | |
1375 | ||
7a68c94a UD |
1376 | This is not the same as @code{x < 0.0}, because @w{IEEE 754} floating |
1377 | point allows zero to be signed. The comparison @code{-0.0 < 0.0} is | |
1378 | false, but @code{signbit (-0.0)} will return a nonzero value. | |
fe0ec73e UD |
1379 | @end deftypefun |
1380 | ||
1381 | @comment math.h | |
1382 | @comment ISO | |
1383 | @deftypefun double nextafter (double @var{x}, double @var{y}) | |
4260bc74 UD |
1384 | @comment math.h |
1385 | @comment ISO | |
fe0ec73e | 1386 | @deftypefunx float nextafterf (float @var{x}, float @var{y}) |
4260bc74 UD |
1387 | @comment math.h |
1388 | @comment ISO | |
fe0ec73e UD |
1389 | @deftypefunx {long double} nextafterl (long double @var{x}, long double @var{y}) |
1390 | The @code{nextafter} function returns the next representable neighbor of | |
7a68c94a UD |
1391 | @var{x} in the direction towards @var{y}. The size of the step between |
1392 | @var{x} and the result depends on the type of the result. If | |
1393 | @math{@var{x} = @var{y}} the function simply returns @var{x}. If either | |
1394 | value is @code{NaN}, @code{NaN} is returned. Otherwise | |
1395 | a value corresponding to the value of the least significant bit in the | |
1396 | mantissa is added or subtracted, depending on the direction. | |
1397 | @code{nextafter} will signal overflow or underflow if the result goes | |
1398 | outside of the range of normalized numbers. | |
fe0ec73e UD |
1399 | |
1400 | This function is defined in @w{IEC 559} (and the appendix with | |
1401 | recommended functions in @w{IEEE 754}/@w{IEEE 854}). | |
1402 | @end deftypefun | |
1403 | ||
7a68c94a UD |
1404 | @comment math.h |
1405 | @comment ISO | |
36fe9ac9 | 1406 | @deftypefun double nexttoward (double @var{x}, long double @var{y}) |
4260bc74 UD |
1407 | @comment math.h |
1408 | @comment ISO | |
36fe9ac9 | 1409 | @deftypefunx float nexttowardf (float @var{x}, long double @var{y}) |
4260bc74 UD |
1410 | @comment math.h |
1411 | @comment ISO | |
36fe9ac9 | 1412 | @deftypefunx {long double} nexttowardl (long double @var{x}, long double @var{y}) |
7a68c94a UD |
1413 | These functions are identical to the corresponding versions of |
1414 | @code{nextafter} except that their second argument is a @code{long | |
1415 | double}. | |
1416 | @end deftypefun | |
1417 | ||
fe0ec73e UD |
1418 | @cindex NaN |
1419 | @comment math.h | |
1420 | @comment ISO | |
1421 | @deftypefun double nan (const char *@var{tagp}) | |
4260bc74 UD |
1422 | @comment math.h |
1423 | @comment ISO | |
fe0ec73e | 1424 | @deftypefunx float nanf (const char *@var{tagp}) |
4260bc74 UD |
1425 | @comment math.h |
1426 | @comment ISO | |
fe0ec73e | 1427 | @deftypefunx {long double} nanl (const char *@var{tagp}) |
7a68c94a UD |
1428 | The @code{nan} function returns a representation of NaN, provided that |
1429 | NaN is supported by the target platform. | |
1430 | @code{nan ("@var{n-char-sequence}")} is equivalent to | |
1431 | @code{strtod ("NAN(@var{n-char-sequence})")}. | |
1432 | ||
1433 | The argument @var{tagp} is used in an unspecified manner. On @w{IEEE | |
1434 | 754} systems, there are many representations of NaN, and @var{tagp} | |
1435 | selects one. On other systems it may do nothing. | |
fe0ec73e UD |
1436 | @end deftypefun |
1437 | ||
7a68c94a UD |
1438 | @node FP Comparison Functions |
1439 | @subsection Floating-Point Comparison Functions | |
1440 | @cindex unordered comparison | |
fe0ec73e | 1441 | |
7a68c94a UD |
1442 | The standard C comparison operators provoke exceptions when one or other |
1443 | of the operands is NaN. For example, | |
1444 | ||
1445 | @smallexample | |
1446 | int v = a < 1.0; | |
1447 | @end smallexample | |
1448 | ||
1449 | @noindent | |
1450 | will raise an exception if @var{a} is NaN. (This does @emph{not} | |
1451 | happen with @code{==} and @code{!=}; those merely return false and true, | |
1452 | respectively, when NaN is examined.) Frequently this exception is | |
ec751a23 | 1453 | undesirable. @w{ISO C99} therefore defines comparison functions that |
7a68c94a UD |
1454 | do not raise exceptions when NaN is examined. All of the functions are |
1455 | implemented as macros which allow their arguments to be of any | |
1456 | floating-point type. The macros are guaranteed to evaluate their | |
1457 | arguments only once. | |
1458 | ||
1459 | @comment math.h | |
1460 | @comment ISO | |
1461 | @deftypefn Macro int isgreater (@emph{real-floating} @var{x}, @emph{real-floating} @var{y}) | |
1462 | This macro determines whether the argument @var{x} is greater than | |
1463 | @var{y}. It is equivalent to @code{(@var{x}) > (@var{y})}, but no | |
1464 | exception is raised if @var{x} or @var{y} are NaN. | |
1465 | @end deftypefn | |
1466 | ||
1467 | @comment math.h | |
1468 | @comment ISO | |
1469 | @deftypefn Macro int isgreaterequal (@emph{real-floating} @var{x}, @emph{real-floating} @var{y}) | |
1470 | This macro determines whether the argument @var{x} is greater than or | |
1471 | equal to @var{y}. It is equivalent to @code{(@var{x}) >= (@var{y})}, but no | |
1472 | exception is raised if @var{x} or @var{y} are NaN. | |
1473 | @end deftypefn | |
1474 | ||
1475 | @comment math.h | |
1476 | @comment ISO | |
1477 | @deftypefn Macro int isless (@emph{real-floating} @var{x}, @emph{real-floating} @var{y}) | |
1478 | This macro determines whether the argument @var{x} is less than @var{y}. | |
1479 | It is equivalent to @code{(@var{x}) < (@var{y})}, but no exception is | |
1480 | raised if @var{x} or @var{y} are NaN. | |
1481 | @end deftypefn | |
1482 | ||
1483 | @comment math.h | |
1484 | @comment ISO | |
1485 | @deftypefn Macro int islessequal (@emph{real-floating} @var{x}, @emph{real-floating} @var{y}) | |
1486 | This macro determines whether the argument @var{x} is less than or equal | |
1487 | to @var{y}. It is equivalent to @code{(@var{x}) <= (@var{y})}, but no | |
1488 | exception is raised if @var{x} or @var{y} are NaN. | |
1489 | @end deftypefn | |
1490 | ||
1491 | @comment math.h | |
1492 | @comment ISO | |
1493 | @deftypefn Macro int islessgreater (@emph{real-floating} @var{x}, @emph{real-floating} @var{y}) | |
1494 | This macro determines whether the argument @var{x} is less or greater | |
1495 | than @var{y}. It is equivalent to @code{(@var{x}) < (@var{y}) || | |
1496 | (@var{x}) > (@var{y})} (although it only evaluates @var{x} and @var{y} | |
1497 | once), but no exception is raised if @var{x} or @var{y} are NaN. | |
1498 | ||
1499 | This macro is not equivalent to @code{@var{x} != @var{y}}, because that | |
1500 | expression is true if @var{x} or @var{y} are NaN. | |
1501 | @end deftypefn | |
1502 | ||
1503 | @comment math.h | |
1504 | @comment ISO | |
1505 | @deftypefn Macro int isunordered (@emph{real-floating} @var{x}, @emph{real-floating} @var{y}) | |
1506 | This macro determines whether its arguments are unordered. In other | |
1507 | words, it is true if @var{x} or @var{y} are NaN, and false otherwise. | |
1508 | @end deftypefn | |
1509 | ||
1510 | Not all machines provide hardware support for these operations. On | |
1511 | machines that don't, the macros can be very slow. Therefore, you should | |
1512 | not use these functions when NaN is not a concern. | |
1513 | ||
1514 | @strong{Note:} There are no macros @code{isequal} or @code{isunequal}. | |
1515 | They are unnecessary, because the @code{==} and @code{!=} operators do | |
1516 | @emph{not} throw an exception if one or both of the operands are NaN. | |
1517 | ||
1518 | @node Misc FP Arithmetic | |
1519 | @subsection Miscellaneous FP arithmetic functions | |
fe0ec73e UD |
1520 | @cindex minimum |
1521 | @cindex maximum | |
7a68c94a UD |
1522 | @cindex positive difference |
1523 | @cindex multiply-add | |
fe0ec73e | 1524 | |
7a68c94a UD |
1525 | The functions in this section perform miscellaneous but common |
1526 | operations that are awkward to express with C operators. On some | |
1527 | processors these functions can use special machine instructions to | |
1528 | perform these operations faster than the equivalent C code. | |
fe0ec73e UD |
1529 | |
1530 | @comment math.h | |
1531 | @comment ISO | |
1532 | @deftypefun double fmin (double @var{x}, double @var{y}) | |
4260bc74 UD |
1533 | @comment math.h |
1534 | @comment ISO | |
fe0ec73e | 1535 | @deftypefunx float fminf (float @var{x}, float @var{y}) |
4260bc74 UD |
1536 | @comment math.h |
1537 | @comment ISO | |
fe0ec73e | 1538 | @deftypefunx {long double} fminl (long double @var{x}, long double @var{y}) |
7a68c94a UD |
1539 | The @code{fmin} function returns the lesser of the two values @var{x} |
1540 | and @var{y}. It is similar to the expression | |
1541 | @smallexample | |
1542 | ((x) < (y) ? (x) : (y)) | |
1543 | @end smallexample | |
1544 | except that @var{x} and @var{y} are only evaluated once. | |
fe0ec73e | 1545 | |
7a68c94a UD |
1546 | If an argument is NaN, the other argument is returned. If both arguments |
1547 | are NaN, NaN is returned. | |
fe0ec73e UD |
1548 | @end deftypefun |
1549 | ||
1550 | @comment math.h | |
1551 | @comment ISO | |
1552 | @deftypefun double fmax (double @var{x}, double @var{y}) | |
4260bc74 UD |
1553 | @comment math.h |
1554 | @comment ISO | |
fe0ec73e | 1555 | @deftypefunx float fmaxf (float @var{x}, float @var{y}) |
4260bc74 UD |
1556 | @comment math.h |
1557 | @comment ISO | |
fe0ec73e | 1558 | @deftypefunx {long double} fmaxl (long double @var{x}, long double @var{y}) |
7a68c94a UD |
1559 | The @code{fmax} function returns the greater of the two values @var{x} |
1560 | and @var{y}. | |
fe0ec73e | 1561 | |
7a68c94a UD |
1562 | If an argument is NaN, the other argument is returned. If both arguments |
1563 | are NaN, NaN is returned. | |
fe0ec73e UD |
1564 | @end deftypefun |
1565 | ||
1566 | @comment math.h | |
1567 | @comment ISO | |
1568 | @deftypefun double fdim (double @var{x}, double @var{y}) | |
4260bc74 UD |
1569 | @comment math.h |
1570 | @comment ISO | |
fe0ec73e | 1571 | @deftypefunx float fdimf (float @var{x}, float @var{y}) |
4260bc74 UD |
1572 | @comment math.h |
1573 | @comment ISO | |
fe0ec73e | 1574 | @deftypefunx {long double} fdiml (long double @var{x}, long double @var{y}) |
7a68c94a UD |
1575 | The @code{fdim} function returns the positive difference between |
1576 | @var{x} and @var{y}. The positive difference is @math{@var{x} - | |
1577 | @var{y}} if @var{x} is greater than @var{y}, and @math{0} otherwise. | |
fe0ec73e | 1578 | |
7a68c94a | 1579 | If @var{x}, @var{y}, or both are NaN, NaN is returned. |
fe0ec73e UD |
1580 | @end deftypefun |
1581 | ||
1582 | @comment math.h | |
1583 | @comment ISO | |
1584 | @deftypefun double fma (double @var{x}, double @var{y}, double @var{z}) | |
4260bc74 UD |
1585 | @comment math.h |
1586 | @comment ISO | |
fe0ec73e | 1587 | @deftypefunx float fmaf (float @var{x}, float @var{y}, float @var{z}) |
4260bc74 UD |
1588 | @comment math.h |
1589 | @comment ISO | |
fe0ec73e UD |
1590 | @deftypefunx {long double} fmal (long double @var{x}, long double @var{y}, long double @var{z}) |
1591 | @cindex butterfly | |
7a68c94a UD |
1592 | The @code{fma} function performs floating-point multiply-add. This is |
1593 | the operation @math{(@var{x} @mul{} @var{y}) + @var{z}}, but the | |
1594 | intermediate result is not rounded to the destination type. This can | |
1595 | sometimes improve the precision of a calculation. | |
1596 | ||
1597 | This function was introduced because some processors have a special | |
1598 | instruction to perform multiply-add. The C compiler cannot use it | |
1599 | directly, because the expression @samp{x*y + z} is defined to round the | |
1600 | intermediate result. @code{fma} lets you choose when you want to round | |
1601 | only once. | |
fe0ec73e UD |
1602 | |
1603 | @vindex FP_FAST_FMA | |
7a68c94a UD |
1604 | On processors which do not implement multiply-add in hardware, |
1605 | @code{fma} can be very slow since it must avoid intermediate rounding. | |
1606 | @file{math.h} defines the symbols @code{FP_FAST_FMA}, | |
1607 | @code{FP_FAST_FMAF}, and @code{FP_FAST_FMAL} when the corresponding | |
1608 | version of @code{fma} is no slower than the expression @samp{x*y + z}. | |
1609 | In the GNU C library, this always means the operation is implemented in | |
1610 | hardware. | |
fe0ec73e UD |
1611 | @end deftypefun |
1612 | ||
7a68c94a UD |
1613 | @node Complex Numbers |
1614 | @section Complex Numbers | |
1615 | @pindex complex.h | |
1616 | @cindex complex numbers | |
1617 | ||
ec751a23 | 1618 | @w{ISO C99} introduces support for complex numbers in C. This is done |
7a68c94a UD |
1619 | with a new type qualifier, @code{complex}. It is a keyword if and only |
1620 | if @file{complex.h} has been included. There are three complex types, | |
1621 | corresponding to the three real types: @code{float complex}, | |
1622 | @code{double complex}, and @code{long double complex}. | |
1623 | ||
1624 | To construct complex numbers you need a way to indicate the imaginary | |
1625 | part of a number. There is no standard notation for an imaginary | |
1626 | floating point constant. Instead, @file{complex.h} defines two macros | |
1627 | that can be used to create complex numbers. | |
1628 | ||
1629 | @deftypevr Macro {const float complex} _Complex_I | |
1630 | This macro is a representation of the complex number ``@math{0+1i}''. | |
1631 | Multiplying a real floating-point value by @code{_Complex_I} gives a | |
1632 | complex number whose value is purely imaginary. You can use this to | |
1633 | construct complex constants: | |
1634 | ||
1635 | @smallexample | |
1636 | @math{3.0 + 4.0i} = @code{3.0 + 4.0 * _Complex_I} | |
1637 | @end smallexample | |
1638 | ||
1639 | Note that @code{_Complex_I * _Complex_I} has the value @code{-1}, but | |
1640 | the type of that value is @code{complex}. | |
1641 | @end deftypevr | |
1642 | ||
1643 | @c Put this back in when gcc supports _Imaginary_I. It's too confusing. | |
1644 | @ignore | |
1645 | @noindent | |
1646 | Without an optimizing compiler this is more expensive than the use of | |
1647 | @code{_Imaginary_I} but with is better than nothing. You can avoid all | |
1648 | the hassles if you use the @code{I} macro below if the name is not | |
1649 | problem. | |
1650 | ||
1651 | @deftypevr Macro {const float imaginary} _Imaginary_I | |
1652 | This macro is a representation of the value ``@math{1i}''. I.e., it is | |
1653 | the value for which | |
1654 | ||
1655 | @smallexample | |
1656 | _Imaginary_I * _Imaginary_I = -1 | |
1657 | @end smallexample | |
1658 | ||
1659 | @noindent | |
1660 | The result is not of type @code{float imaginary} but instead @code{float}. | |
1661 | One can use it to easily construct complex number like in | |
1662 | ||
1663 | @smallexample | |
1664 | 3.0 - _Imaginary_I * 4.0 | |
1665 | @end smallexample | |
1666 | ||
1667 | @noindent | |
1668 | which results in the complex number with a real part of 3.0 and a | |
1669 | imaginary part -4.0. | |
1670 | @end deftypevr | |
1671 | @end ignore | |
1672 | ||
1673 | @noindent | |
1674 | @code{_Complex_I} is a bit of a mouthful. @file{complex.h} also defines | |
1675 | a shorter name for the same constant. | |
1676 | ||
1677 | @deftypevr Macro {const float complex} I | |
1678 | This macro has exactly the same value as @code{_Complex_I}. Most of the | |
1679 | time it is preferable. However, it causes problems if you want to use | |
1680 | the identifier @code{I} for something else. You can safely write | |
1681 | ||
1682 | @smallexample | |
1683 | #include <complex.h> | |
1684 | #undef I | |
1685 | @end smallexample | |
1686 | ||
1687 | @noindent | |
1688 | if you need @code{I} for your own purposes. (In that case we recommend | |
1689 | you also define some other short name for @code{_Complex_I}, such as | |
1690 | @code{J}.) | |
1691 | ||
1692 | @ignore | |
1693 | If the implementation does not support the @code{imaginary} types | |
1694 | @code{I} is defined as @code{_Complex_I} which is the second best | |
1695 | solution. It still can be used in the same way but requires a most | |
1696 | clever compiler to get the same results. | |
1697 | @end ignore | |
1698 | @end deftypevr | |
1699 | ||
1700 | @node Operations on Complex | |
1701 | @section Projections, Conjugates, and Decomposing of Complex Numbers | |
1702 | @cindex project complex numbers | |
1703 | @cindex conjugate complex numbers | |
1704 | @cindex decompose complex numbers | |
1705 | @pindex complex.h | |
1706 | ||
ec751a23 | 1707 | @w{ISO C99} also defines functions that perform basic operations on |
7a68c94a UD |
1708 | complex numbers, such as decomposition and conjugation. The prototypes |
1709 | for all these functions are in @file{complex.h}. All functions are | |
1710 | available in three variants, one for each of the three complex types. | |
1711 | ||
1712 | @comment complex.h | |
1713 | @comment ISO | |
1714 | @deftypefun double creal (complex double @var{z}) | |
4260bc74 UD |
1715 | @comment complex.h |
1716 | @comment ISO | |
7a68c94a | 1717 | @deftypefunx float crealf (complex float @var{z}) |
4260bc74 UD |
1718 | @comment complex.h |
1719 | @comment ISO | |
7a68c94a UD |
1720 | @deftypefunx {long double} creall (complex long double @var{z}) |
1721 | These functions return the real part of the complex number @var{z}. | |
1722 | @end deftypefun | |
1723 | ||
1724 | @comment complex.h | |
1725 | @comment ISO | |
1726 | @deftypefun double cimag (complex double @var{z}) | |
4260bc74 UD |
1727 | @comment complex.h |
1728 | @comment ISO | |
7a68c94a | 1729 | @deftypefunx float cimagf (complex float @var{z}) |
4260bc74 UD |
1730 | @comment complex.h |
1731 | @comment ISO | |
7a68c94a UD |
1732 | @deftypefunx {long double} cimagl (complex long double @var{z}) |
1733 | These functions return the imaginary part of the complex number @var{z}. | |
1734 | @end deftypefun | |
1735 | ||
1736 | @comment complex.h | |
1737 | @comment ISO | |
1738 | @deftypefun {complex double} conj (complex double @var{z}) | |
4260bc74 UD |
1739 | @comment complex.h |
1740 | @comment ISO | |
7a68c94a | 1741 | @deftypefunx {complex float} conjf (complex float @var{z}) |
4260bc74 UD |
1742 | @comment complex.h |
1743 | @comment ISO | |
7a68c94a UD |
1744 | @deftypefunx {complex long double} conjl (complex long double @var{z}) |
1745 | These functions return the conjugate value of the complex number | |
1746 | @var{z}. The conjugate of a complex number has the same real part and a | |
1747 | negated imaginary part. In other words, @samp{conj(a + bi) = a + -bi}. | |
1748 | @end deftypefun | |
1749 | ||
1750 | @comment complex.h | |
1751 | @comment ISO | |
1752 | @deftypefun double carg (complex double @var{z}) | |
4260bc74 UD |
1753 | @comment complex.h |
1754 | @comment ISO | |
7a68c94a | 1755 | @deftypefunx float cargf (complex float @var{z}) |
4260bc74 UD |
1756 | @comment complex.h |
1757 | @comment ISO | |
7a68c94a UD |
1758 | @deftypefunx {long double} cargl (complex long double @var{z}) |
1759 | These functions return the argument of the complex number @var{z}. | |
1760 | The argument of a complex number is the angle in the complex plane | |
1761 | between the positive real axis and a line passing through zero and the | |
1762 | number. This angle is measured in the usual fashion and ranges from @math{0} | |
1763 | to @math{2@pi{}}. | |
1764 | ||
1765 | @code{carg} has a branch cut along the positive real axis. | |
1766 | @end deftypefun | |
1767 | ||
1768 | @comment complex.h | |
1769 | @comment ISO | |
1770 | @deftypefun {complex double} cproj (complex double @var{z}) | |
4260bc74 UD |
1771 | @comment complex.h |
1772 | @comment ISO | |
7a68c94a | 1773 | @deftypefunx {complex float} cprojf (complex float @var{z}) |
4260bc74 UD |
1774 | @comment complex.h |
1775 | @comment ISO | |
7a68c94a UD |
1776 | @deftypefunx {complex long double} cprojl (complex long double @var{z}) |
1777 | These functions return the projection of the complex value @var{z} onto | |
1778 | the Riemann sphere. Values with a infinite imaginary part are projected | |
1779 | to positive infinity on the real axis, even if the real part is NaN. If | |
1780 | the real part is infinite, the result is equivalent to | |
1781 | ||
1782 | @smallexample | |
1783 | INFINITY + I * copysign (0.0, cimag (z)) | |
1784 | @end smallexample | |
1785 | @end deftypefun | |
fe0ec73e | 1786 | |
28f540f4 RM |
1787 | @node Integer Division |
1788 | @section Integer Division | |
1789 | @cindex integer division functions | |
1790 | ||
1791 | This section describes functions for performing integer division. These | |
7a68c94a UD |
1792 | functions are redundant when GNU CC is used, because in GNU C the |
1793 | @samp{/} operator always rounds towards zero. But in other C | |
1794 | implementations, @samp{/} may round differently with negative arguments. | |
1795 | @code{div} and @code{ldiv} are useful because they specify how to round | |
1796 | the quotient: towards zero. The remainder has the same sign as the | |
1797 | numerator. | |
28f540f4 RM |
1798 | |
1799 | These functions are specified to return a result @var{r} such that the value | |
1800 | @code{@var{r}.quot*@var{denominator} + @var{r}.rem} equals | |
1801 | @var{numerator}. | |
1802 | ||
1803 | @pindex stdlib.h | |
1804 | To use these facilities, you should include the header file | |
1805 | @file{stdlib.h} in your program. | |
1806 | ||
1807 | @comment stdlib.h | |
f65fd747 | 1808 | @comment ISO |
28f540f4 RM |
1809 | @deftp {Data Type} div_t |
1810 | This is a structure type used to hold the result returned by the @code{div} | |
1811 | function. It has the following members: | |
1812 | ||
1813 | @table @code | |
1814 | @item int quot | |
1815 | The quotient from the division. | |
1816 | ||
1817 | @item int rem | |
1818 | The remainder from the division. | |
1819 | @end table | |
1820 | @end deftp | |
1821 | ||
1822 | @comment stdlib.h | |
f65fd747 | 1823 | @comment ISO |
28f540f4 RM |
1824 | @deftypefun div_t div (int @var{numerator}, int @var{denominator}) |
1825 | This function @code{div} computes the quotient and remainder from | |
1826 | the division of @var{numerator} by @var{denominator}, returning the | |
1827 | result in a structure of type @code{div_t}. | |
1828 | ||
1829 | If the result cannot be represented (as in a division by zero), the | |
1830 | behavior is undefined. | |
1831 | ||
1832 | Here is an example, albeit not a very useful one. | |
1833 | ||
1834 | @smallexample | |
1835 | div_t result; | |
1836 | result = div (20, -6); | |
1837 | @end smallexample | |
1838 | ||
1839 | @noindent | |
1840 | Now @code{result.quot} is @code{-3} and @code{result.rem} is @code{2}. | |
1841 | @end deftypefun | |
1842 | ||
1843 | @comment stdlib.h | |
f65fd747 | 1844 | @comment ISO |
28f540f4 RM |
1845 | @deftp {Data Type} ldiv_t |
1846 | This is a structure type used to hold the result returned by the @code{ldiv} | |
1847 | function. It has the following members: | |
1848 | ||
1849 | @table @code | |
1850 | @item long int quot | |
1851 | The quotient from the division. | |
1852 | ||
1853 | @item long int rem | |
1854 | The remainder from the division. | |
1855 | @end table | |
1856 | ||
1857 | (This is identical to @code{div_t} except that the components are of | |
1858 | type @code{long int} rather than @code{int}.) | |
1859 | @end deftp | |
1860 | ||
1861 | @comment stdlib.h | |
f65fd747 | 1862 | @comment ISO |
28f540f4 RM |
1863 | @deftypefun ldiv_t ldiv (long int @var{numerator}, long int @var{denominator}) |
1864 | The @code{ldiv} function is similar to @code{div}, except that the | |
1865 | arguments are of type @code{long int} and the result is returned as a | |
fe7bdd63 UD |
1866 | structure of type @code{ldiv_t}. |
1867 | @end deftypefun | |
1868 | ||
1869 | @comment stdlib.h | |
7a68c94a | 1870 | @comment ISO |
fe7bdd63 UD |
1871 | @deftp {Data Type} lldiv_t |
1872 | This is a structure type used to hold the result returned by the @code{lldiv} | |
1873 | function. It has the following members: | |
1874 | ||
1875 | @table @code | |
1876 | @item long long int quot | |
1877 | The quotient from the division. | |
1878 | ||
1879 | @item long long int rem | |
1880 | The remainder from the division. | |
1881 | @end table | |
1882 | ||
1883 | (This is identical to @code{div_t} except that the components are of | |
1884 | type @code{long long int} rather than @code{int}.) | |
1885 | @end deftp | |
1886 | ||
1887 | @comment stdlib.h | |
7a68c94a | 1888 | @comment ISO |
fe7bdd63 UD |
1889 | @deftypefun lldiv_t lldiv (long long int @var{numerator}, long long int @var{denominator}) |
1890 | The @code{lldiv} function is like the @code{div} function, but the | |
1891 | arguments are of type @code{long long int} and the result is returned as | |
1892 | a structure of type @code{lldiv_t}. | |
1893 | ||
ec751a23 | 1894 | The @code{lldiv} function was added in @w{ISO C99}. |
28f540f4 RM |
1895 | @end deftypefun |
1896 | ||
e518937a UD |
1897 | @comment inttypes.h |
1898 | @comment ISO | |
1899 | @deftp {Data Type} imaxdiv_t | |
1900 | This is a structure type used to hold the result returned by the @code{imaxdiv} | |
1901 | function. It has the following members: | |
1902 | ||
1903 | @table @code | |
1904 | @item intmax_t quot | |
1905 | The quotient from the division. | |
1906 | ||
1907 | @item intmax_t rem | |
1908 | The remainder from the division. | |
1909 | @end table | |
1910 | ||
1911 | (This is identical to @code{div_t} except that the components are of | |
1912 | type @code{intmax_t} rather than @code{int}.) | |
1913 | @end deftp | |
1914 | ||
1915 | @comment inttypes.h | |
1916 | @comment ISO | |
1917 | @deftypefun imaxdiv_t imaxdiv (intmax_t @var{numerator}, intmax_t @var{denominator}) | |
1918 | The @code{imaxdiv} function is like the @code{div} function, but the | |
1919 | arguments are of type @code{intmax_t} and the result is returned as | |
1920 | a structure of type @code{imaxdiv_t}. | |
1921 | ||
ec751a23 | 1922 | The @code{imaxdiv} function was added in @w{ISO C99}. |
e518937a UD |
1923 | @end deftypefun |
1924 | ||
28f540f4 RM |
1925 | |
1926 | @node Parsing of Numbers | |
1927 | @section Parsing of Numbers | |
1928 | @cindex parsing numbers (in formatted input) | |
1929 | @cindex converting strings to numbers | |
1930 | @cindex number syntax, parsing | |
1931 | @cindex syntax, for reading numbers | |
1932 | ||
1933 | This section describes functions for ``reading'' integer and | |
1934 | floating-point numbers from a string. It may be more convenient in some | |
1935 | cases to use @code{sscanf} or one of the related functions; see | |
1936 | @ref{Formatted Input}. But often you can make a program more robust by | |
1937 | finding the tokens in the string by hand, then converting the numbers | |
1938 | one by one. | |
1939 | ||
1940 | @menu | |
1941 | * Parsing of Integers:: Functions for conversion of integer values. | |
1942 | * Parsing of Floats:: Functions for conversion of floating-point | |
1943 | values. | |
1944 | @end menu | |
1945 | ||
1946 | @node Parsing of Integers | |
1947 | @subsection Parsing of Integers | |
1948 | ||
1949 | @pindex stdlib.h | |
1950 | These functions are declared in @file{stdlib.h}. | |
1951 | ||
1952 | @comment stdlib.h | |
f65fd747 | 1953 | @comment ISO |
28f540f4 RM |
1954 | @deftypefun {long int} strtol (const char *@var{string}, char **@var{tailptr}, int @var{base}) |
1955 | The @code{strtol} (``string-to-long'') function converts the initial | |
1956 | part of @var{string} to a signed integer, which is returned as a value | |
b8fe19fa | 1957 | of type @code{long int}. |
28f540f4 RM |
1958 | |
1959 | This function attempts to decompose @var{string} as follows: | |
1960 | ||
1961 | @itemize @bullet | |
b8fe19fa | 1962 | @item |
28f540f4 RM |
1963 | A (possibly empty) sequence of whitespace characters. Which characters |
1964 | are whitespace is determined by the @code{isspace} function | |
1965 | (@pxref{Classification of Characters}). These are discarded. | |
1966 | ||
b8fe19fa | 1967 | @item |
28f540f4 RM |
1968 | An optional plus or minus sign (@samp{+} or @samp{-}). |
1969 | ||
b8fe19fa | 1970 | @item |
28f540f4 RM |
1971 | A nonempty sequence of digits in the radix specified by @var{base}. |
1972 | ||
1973 | If @var{base} is zero, decimal radix is assumed unless the series of | |
1974 | digits begins with @samp{0} (specifying octal radix), or @samp{0x} or | |
1975 | @samp{0X} (specifying hexadecimal radix); in other words, the same | |
1976 | syntax used for integer constants in C. | |
1977 | ||
1978 | Otherwise @var{base} must have a value between @code{2} and @code{35}. | |
1979 | If @var{base} is @code{16}, the digits may optionally be preceded by | |
2c6fe0bd UD |
1980 | @samp{0x} or @samp{0X}. If base has no legal value the value returned |
1981 | is @code{0l} and the global variable @code{errno} is set to @code{EINVAL}. | |
28f540f4 | 1982 | |
b8fe19fa | 1983 | @item |
28f540f4 RM |
1984 | Any remaining characters in the string. If @var{tailptr} is not a null |
1985 | pointer, @code{strtol} stores a pointer to this tail in | |
1986 | @code{*@var{tailptr}}. | |
1987 | @end itemize | |
1988 | ||
1989 | If the string is empty, contains only whitespace, or does not contain an | |
1990 | initial substring that has the expected syntax for an integer in the | |
1991 | specified @var{base}, no conversion is performed. In this case, | |
1992 | @code{strtol} returns a value of zero and the value stored in | |
1993 | @code{*@var{tailptr}} is the value of @var{string}. | |
1994 | ||
1995 | In a locale other than the standard @code{"C"} locale, this function | |
1996 | may recognize additional implementation-dependent syntax. | |
1997 | ||
1998 | If the string has valid syntax for an integer but the value is not | |
1999 | representable because of overflow, @code{strtol} returns either | |
2000 | @code{LONG_MAX} or @code{LONG_MIN} (@pxref{Range of Type}), as | |
2001 | appropriate for the sign of the value. It also sets @code{errno} | |
2002 | to @code{ERANGE} to indicate there was overflow. | |
2003 | ||
7a68c94a UD |
2004 | You should not check for errors by examining the return value of |
2005 | @code{strtol}, because the string might be a valid representation of | |
2006 | @code{0l}, @code{LONG_MAX}, or @code{LONG_MIN}. Instead, check whether | |
2007 | @var{tailptr} points to what you expect after the number | |
2008 | (e.g. @code{'\0'} if the string should end after the number). You also | |
2009 | need to clear @var{errno} before the call and check it afterward, in | |
2010 | case there was overflow. | |
2c6fe0bd | 2011 | |
28f540f4 RM |
2012 | There is an example at the end of this section. |
2013 | @end deftypefun | |
2014 | ||
2015 | @comment stdlib.h | |
f65fd747 | 2016 | @comment ISO |
28f540f4 RM |
2017 | @deftypefun {unsigned long int} strtoul (const char *@var{string}, char **@var{tailptr}, int @var{base}) |
2018 | The @code{strtoul} (``string-to-unsigned-long'') function is like | |
7a68c94a UD |
2019 | @code{strtol} except it returns an @code{unsigned long int} value. If |
2020 | the number has a leading @samp{-} sign, the return value is negated. | |
2021 | The syntax is the same as described above for @code{strtol}. The value | |
2022 | returned on overflow is @code{ULONG_MAX} (@pxref{Range of | |
2023 | Type}). | |
2024 | ||
2025 | @code{strtoul} sets @var{errno} to @code{EINVAL} if @var{base} is out of | |
2026 | range, or @code{ERANGE} on overflow. | |
2c6fe0bd UD |
2027 | @end deftypefun |
2028 | ||
2029 | @comment stdlib.h | |
7a68c94a | 2030 | @comment ISO |
fe7bdd63 | 2031 | @deftypefun {long long int} strtoll (const char *@var{string}, char **@var{tailptr}, int @var{base}) |
7a68c94a UD |
2032 | The @code{strtoll} function is like @code{strtol} except that it returns |
2033 | a @code{long long int} value, and accepts numbers with a correspondingly | |
2034 | larger range. | |
2c6fe0bd UD |
2035 | |
2036 | If the string has valid syntax for an integer but the value is not | |
fe7bdd63 | 2037 | representable because of overflow, @code{strtoll} returns either |
2c6fe0bd UD |
2038 | @code{LONG_LONG_MAX} or @code{LONG_LONG_MIN} (@pxref{Range of Type}), as |
2039 | appropriate for the sign of the value. It also sets @code{errno} to | |
2040 | @code{ERANGE} to indicate there was overflow. | |
2c6fe0bd | 2041 | |
ec751a23 | 2042 | The @code{strtoll} function was introduced in @w{ISO C99}. |
2c6fe0bd UD |
2043 | @end deftypefun |
2044 | ||
2045 | @comment stdlib.h | |
2046 | @comment BSD | |
fe7bdd63 | 2047 | @deftypefun {long long int} strtoq (const char *@var{string}, char **@var{tailptr}, int @var{base}) |
7a68c94a | 2048 | @code{strtoq} (``string-to-quad-word'') is the BSD name for @code{strtoll}. |
2c6fe0bd UD |
2049 | @end deftypefun |
2050 | ||
2051 | @comment stdlib.h | |
7a68c94a | 2052 | @comment ISO |
2c6fe0bd | 2053 | @deftypefun {unsigned long long int} strtoull (const char *@var{string}, char **@var{tailptr}, int @var{base}) |
7a68c94a UD |
2054 | The @code{strtoull} function is like @code{strtoul} except that it |
2055 | returns an @code{unsigned long long int}. The value returned on overflow | |
fe7bdd63 UD |
2056 | is @code{ULONG_LONG_MAX} (@pxref{Range of Type}). |
2057 | ||
ec751a23 | 2058 | The @code{strtoull} function was introduced in @w{ISO C99}. |
fe7bdd63 UD |
2059 | @end deftypefun |
2060 | ||
2061 | @comment stdlib.h | |
2062 | @comment BSD | |
2063 | @deftypefun {unsigned long long int} strtouq (const char *@var{string}, char **@var{tailptr}, int @var{base}) | |
7a68c94a | 2064 | @code{strtouq} is the BSD name for @code{strtoull}. |
28f540f4 RM |
2065 | @end deftypefun |
2066 | ||
2067 | @comment stdlib.h | |
f65fd747 | 2068 | @comment ISO |
28f540f4 RM |
2069 | @deftypefun {long int} atol (const char *@var{string}) |
2070 | This function is similar to the @code{strtol} function with a @var{base} | |
2071 | argument of @code{10}, except that it need not detect overflow errors. | |
2072 | The @code{atol} function is provided mostly for compatibility with | |
2073 | existing code; using @code{strtol} is more robust. | |
2074 | @end deftypefun | |
2075 | ||
2076 | @comment stdlib.h | |
f65fd747 | 2077 | @comment ISO |
28f540f4 | 2078 | @deftypefun int atoi (const char *@var{string}) |
7a68c94a UD |
2079 | This function is like @code{atol}, except that it returns an @code{int}. |
2080 | The @code{atoi} function is also considered obsolete; use @code{strtol} | |
2081 | instead. | |
28f540f4 RM |
2082 | @end deftypefun |
2083 | ||
fe7bdd63 | 2084 | @comment stdlib.h |
7a68c94a | 2085 | @comment ISO |
fe7bdd63 UD |
2086 | @deftypefun {long long int} atoll (const char *@var{string}) |
2087 | This function is similar to @code{atol}, except it returns a @code{long | |
7a68c94a | 2088 | long int}. |
fe7bdd63 | 2089 | |
ec751a23 | 2090 | The @code{atoll} function was introduced in @w{ISO C99}. It too is |
7a68c94a | 2091 | obsolete (despite having just been added); use @code{strtoll} instead. |
fe7bdd63 UD |
2092 | @end deftypefun |
2093 | ||
7a68c94a UD |
2094 | @c !!! please fact check this paragraph -zw |
2095 | @findex strtol_l | |
2096 | @findex strtoul_l | |
2097 | @findex strtoll_l | |
2098 | @findex strtoull_l | |
2099 | @cindex parsing numbers and locales | |
2100 | @cindex locales, parsing numbers and | |
2101 | Some locales specify a printed syntax for numbers other than the one | |
2102 | that these functions understand. If you need to read numbers formatted | |
2103 | in some other locale, you can use the @code{strtoX_l} functions. Each | |
2104 | of the @code{strtoX} functions has a counterpart with @samp{_l} added to | |
2105 | its name. The @samp{_l} counterparts take an additional argument: a | |
2106 | pointer to an @code{locale_t} structure, which describes how the numbers | |
2107 | to be read are formatted. @xref{Locales}. | |
2108 | ||
2109 | @strong{Portability Note:} These functions are all GNU extensions. You | |
2110 | can also use @code{scanf} or its relatives, which have the @samp{'} flag | |
2111 | for parsing numeric input according to the current locale | |
2112 | (@pxref{Numeric Input Conversions}). This feature is standard. | |
2c6fe0bd | 2113 | |
28f540f4 RM |
2114 | Here is a function which parses a string as a sequence of integers and |
2115 | returns the sum of them: | |
2116 | ||
2117 | @smallexample | |
2118 | int | |
2119 | sum_ints_from_string (char *string) | |
2120 | @{ | |
2121 | int sum = 0; | |
2122 | ||
2123 | while (1) @{ | |
2124 | char *tail; | |
2125 | int next; | |
2126 | ||
2127 | /* @r{Skip whitespace by hand, to detect the end.} */ | |
2128 | while (isspace (*string)) string++; | |
2129 | if (*string == 0) | |
2130 | break; | |
2131 | ||
2132 | /* @r{There is more nonwhitespace,} */ | |
2133 | /* @r{so it ought to be another number.} */ | |
2134 | errno = 0; | |
2135 | /* @r{Parse it.} */ | |
2136 | next = strtol (string, &tail, 0); | |
2137 | /* @r{Add it in, if not overflow.} */ | |
2138 | if (errno) | |
2139 | printf ("Overflow\n"); | |
2140 | else | |
2141 | sum += next; | |
2142 | /* @r{Advance past it.} */ | |
2143 | string = tail; | |
2144 | @} | |
2145 | ||
2146 | return sum; | |
2147 | @} | |
2148 | @end smallexample | |
2149 | ||
2150 | @node Parsing of Floats | |
2151 | @subsection Parsing of Floats | |
2152 | ||
2153 | @pindex stdlib.h | |
2154 | These functions are declared in @file{stdlib.h}. | |
2155 | ||
2156 | @comment stdlib.h | |
f65fd747 | 2157 | @comment ISO |
28f540f4 RM |
2158 | @deftypefun double strtod (const char *@var{string}, char **@var{tailptr}) |
2159 | The @code{strtod} (``string-to-double'') function converts the initial | |
2160 | part of @var{string} to a floating-point number, which is returned as a | |
b8fe19fa | 2161 | value of type @code{double}. |
28f540f4 RM |
2162 | |
2163 | This function attempts to decompose @var{string} as follows: | |
2164 | ||
2165 | @itemize @bullet | |
b8fe19fa | 2166 | @item |
28f540f4 RM |
2167 | A (possibly empty) sequence of whitespace characters. Which characters |
2168 | are whitespace is determined by the @code{isspace} function | |
2169 | (@pxref{Classification of Characters}). These are discarded. | |
2170 | ||
2171 | @item | |
2172 | An optional plus or minus sign (@samp{+} or @samp{-}). | |
2173 | ||
0c34b1e9 UD |
2174 | @item A floating point number in decimal or hexadecimal format. The |
2175 | decimal format is: | |
2176 | @itemize @minus | |
2177 | ||
28f540f4 RM |
2178 | @item |
2179 | A nonempty sequence of digits optionally containing a decimal-point | |
2180 | character---normally @samp{.}, but it depends on the locale | |
85c165be | 2181 | (@pxref{General Numeric}). |
28f540f4 RM |
2182 | |
2183 | @item | |
2184 | An optional exponent part, consisting of a character @samp{e} or | |
2185 | @samp{E}, an optional sign, and a sequence of digits. | |
2186 | ||
0c34b1e9 UD |
2187 | @end itemize |
2188 | ||
2189 | The hexadecimal format is as follows: | |
2190 | @itemize @minus | |
2191 | ||
2192 | @item | |
2193 | A 0x or 0X followed by a nonempty sequence of hexadecimal digits | |
2194 | optionally containing a decimal-point character---normally @samp{.}, but | |
2195 | it depends on the locale (@pxref{General Numeric}). | |
2196 | ||
2197 | @item | |
2198 | An optional binary-exponent part, consisting of a character @samp{p} or | |
2199 | @samp{P}, an optional sign, and a sequence of digits. | |
2200 | ||
2201 | @end itemize | |
2202 | ||
28f540f4 RM |
2203 | @item |
2204 | Any remaining characters in the string. If @var{tailptr} is not a null | |
2205 | pointer, a pointer to this tail of the string is stored in | |
2206 | @code{*@var{tailptr}}. | |
2207 | @end itemize | |
2208 | ||
2209 | If the string is empty, contains only whitespace, or does not contain an | |
2210 | initial substring that has the expected syntax for a floating-point | |
2211 | number, no conversion is performed. In this case, @code{strtod} returns | |
2212 | a value of zero and the value returned in @code{*@var{tailptr}} is the | |
2213 | value of @var{string}. | |
2214 | ||
26761c28 | 2215 | In a locale other than the standard @code{"C"} or @code{"POSIX"} locales, |
2c6fe0bd | 2216 | this function may recognize additional locale-dependent syntax. |
28f540f4 RM |
2217 | |
2218 | If the string has valid syntax for a floating-point number but the value | |
7a68c94a UD |
2219 | is outside the range of a @code{double}, @code{strtod} will signal |
2220 | overflow or underflow as described in @ref{Math Error Reporting}. | |
2221 | ||
2222 | @code{strtod} recognizes four special input strings. The strings | |
2223 | @code{"inf"} and @code{"infinity"} are converted to @math{@infinity{}}, | |
2224 | or to the largest representable value if the floating-point format | |
2225 | doesn't support infinities. You can prepend a @code{"+"} or @code{"-"} | |
2226 | to specify the sign. Case is ignored when scanning these strings. | |
2227 | ||
2228 | The strings @code{"nan"} and @code{"nan(@var{chars...})"} are converted | |
2229 | to NaN. Again, case is ignored. If @var{chars...} are provided, they | |
2230 | are used in some unspecified fashion to select a particular | |
2231 | representation of NaN (there can be several). | |
2232 | ||
2233 | Since zero is a valid result as well as the value returned on error, you | |
2234 | should check for errors in the same way as for @code{strtol}, by | |
2235 | examining @var{errno} and @var{tailptr}. | |
28f540f4 RM |
2236 | @end deftypefun |
2237 | ||
2c6fe0bd | 2238 | @comment stdlib.h |
ec751a23 | 2239 | @comment ISO |
2c6fe0bd | 2240 | @deftypefun float strtof (const char *@var{string}, char **@var{tailptr}) |
4260bc74 | 2241 | @comment stdlib.h |
ec751a23 | 2242 | @comment ISO |
7a68c94a UD |
2243 | @deftypefunx {long double} strtold (const char *@var{string}, char **@var{tailptr}) |
2244 | These functions are analogous to @code{strtod}, but return @code{float} | |
2245 | and @code{long double} values respectively. They report errors in the | |
2246 | same way as @code{strtod}. @code{strtof} can be substantially faster | |
2247 | than @code{strtod}, but has less precision; conversely, @code{strtold} | |
2248 | can be much slower but has more precision (on systems where @code{long | |
2249 | double} is a separate type). | |
2250 | ||
ec751a23 | 2251 | These functions have been GNU extensions and are new to @w{ISO C99}. |
2c6fe0bd UD |
2252 | @end deftypefun |
2253 | ||
28f540f4 | 2254 | @comment stdlib.h |
f65fd747 | 2255 | @comment ISO |
28f540f4 RM |
2256 | @deftypefun double atof (const char *@var{string}) |
2257 | This function is similar to the @code{strtod} function, except that it | |
2258 | need not detect overflow and underflow errors. The @code{atof} function | |
2259 | is provided mostly for compatibility with existing code; using | |
2260 | @code{strtod} is more robust. | |
2261 | @end deftypefun | |
880f421f | 2262 | |
49c091e5 | 2263 | The GNU C library also provides @samp{_l} versions of these functions, |
7a68c94a UD |
2264 | which take an additional argument, the locale to use in conversion. |
2265 | @xref{Parsing of Integers}. | |
880f421f | 2266 | |
7a68c94a UD |
2267 | @node System V Number Conversion |
2268 | @section Old-fashioned System V number-to-string functions | |
880f421f | 2269 | |
7a68c94a UD |
2270 | The old @w{System V} C library provided three functions to convert |
2271 | numbers to strings, with unusual and hard-to-use semantics. The GNU C | |
2272 | library also provides these functions and some natural extensions. | |
880f421f | 2273 | |
7a68c94a UD |
2274 | These functions are only available in glibc and on systems descended |
2275 | from AT&T Unix. Therefore, unless these functions do precisely what you | |
2276 | need, it is better to use @code{sprintf}, which is standard. | |
880f421f | 2277 | |
7a68c94a | 2278 | All these functions are defined in @file{stdlib.h}. |
880f421f UD |
2279 | |
2280 | @comment stdlib.h | |
2281 | @comment SVID, Unix98 | |
7a68c94a | 2282 | @deftypefun {char *} ecvt (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}) |
880f421f | 2283 | The function @code{ecvt} converts the floating-point number @var{value} |
0ea5db4f UD |
2284 | to a string with at most @var{ndigit} decimal digits. The |
2285 | returned string contains no decimal point or sign. The first digit of | |
2286 | the string is non-zero (unless @var{value} is actually zero) and the | |
2287 | last digit is rounded to nearest. @code{*@var{decpt}} is set to the | |
7a68c94a | 2288 | index in the string of the first digit after the decimal point. |
0ea5db4f UD |
2289 | @code{*@var{neg}} is set to a nonzero value if @var{value} is negative, |
2290 | zero otherwise. | |
880f421f | 2291 | |
67994d6f UD |
2292 | If @var{ndigit} decimal digits would exceed the precision of a |
2293 | @code{double} it is reduced to a system-specific value. | |
2294 | ||
880f421f UD |
2295 | The returned string is statically allocated and overwritten by each call |
2296 | to @code{ecvt}. | |
2297 | ||
0ea5db4f UD |
2298 | If @var{value} is zero, it is implementation defined whether |
2299 | @code{*@var{decpt}} is @code{0} or @code{1}. | |
880f421f | 2300 | |
0ea5db4f UD |
2301 | For example: @code{ecvt (12.3, 5, &d, &n)} returns @code{"12300"} |
2302 | and sets @var{d} to @code{2} and @var{n} to @code{0}. | |
880f421f UD |
2303 | @end deftypefun |
2304 | ||
880f421f UD |
2305 | @comment stdlib.h |
2306 | @comment SVID, Unix98 | |
0ea5db4f | 2307 | @deftypefun {char *} fcvt (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}) |
7a68c94a UD |
2308 | The function @code{fcvt} is like @code{ecvt}, but @var{ndigit} specifies |
2309 | the number of digits after the decimal point. If @var{ndigit} is less | |
2310 | than zero, @var{value} is rounded to the @math{@var{ndigit}+1}'th place to the | |
2311 | left of the decimal point. For example, if @var{ndigit} is @code{-1}, | |
2312 | @var{value} will be rounded to the nearest 10. If @var{ndigit} is | |
2313 | negative and larger than the number of digits to the left of the decimal | |
2314 | point in @var{value}, @var{value} will be rounded to one significant digit. | |
880f421f | 2315 | |
67994d6f UD |
2316 | If @var{ndigit} decimal digits would exceed the precision of a |
2317 | @code{double} it is reduced to a system-specific value. | |
2318 | ||
880f421f UD |
2319 | The returned string is statically allocated and overwritten by each call |
2320 | to @code{fcvt}. | |
880f421f UD |
2321 | @end deftypefun |
2322 | ||
2323 | @comment stdlib.h | |
2324 | @comment SVID, Unix98 | |
2325 | @deftypefun {char *} gcvt (double @var{value}, int @var{ndigit}, char *@var{buf}) | |
7a68c94a UD |
2326 | @code{gcvt} is functionally equivalent to @samp{sprintf(buf, "%*g", |
2327 | ndigit, value}. It is provided only for compatibility's sake. It | |
2328 | returns @var{buf}. | |
67994d6f UD |
2329 | |
2330 | If @var{ndigit} decimal digits would exceed the precision of a | |
2331 | @code{double} it is reduced to a system-specific value. | |
880f421f UD |
2332 | @end deftypefun |
2333 | ||
7a68c94a UD |
2334 | As extensions, the GNU C library provides versions of these three |
2335 | functions that take @code{long double} arguments. | |
880f421f UD |
2336 | |
2337 | @comment stdlib.h | |
2338 | @comment GNU | |
7a68c94a | 2339 | @deftypefun {char *} qecvt (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}) |
67994d6f UD |
2340 | This function is equivalent to @code{ecvt} except that it takes a |
2341 | @code{long double} for the first parameter and that @var{ndigit} is | |
2342 | restricted by the precision of a @code{long double}. | |
880f421f UD |
2343 | @end deftypefun |
2344 | ||
2345 | @comment stdlib.h | |
2346 | @comment GNU | |
0ea5db4f | 2347 | @deftypefun {char *} qfcvt (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}) |
7a68c94a | 2348 | This function is equivalent to @code{fcvt} except that it |
67994d6f UD |
2349 | takes a @code{long double} for the first parameter and that @var{ndigit} is |
2350 | restricted by the precision of a @code{long double}. | |
880f421f UD |
2351 | @end deftypefun |
2352 | ||
2353 | @comment stdlib.h | |
2354 | @comment GNU | |
2355 | @deftypefun {char *} qgcvt (long double @var{value}, int @var{ndigit}, char *@var{buf}) | |
67994d6f UD |
2356 | This function is equivalent to @code{gcvt} except that it takes a |
2357 | @code{long double} for the first parameter and that @var{ndigit} is | |
2358 | restricted by the precision of a @code{long double}. | |
880f421f UD |
2359 | @end deftypefun |
2360 | ||
2361 | ||
2362 | @cindex gcvt_r | |
7a68c94a UD |
2363 | The @code{ecvt} and @code{fcvt} functions, and their @code{long double} |
2364 | equivalents, all return a string located in a static buffer which is | |
2365 | overwritten by the next call to the function. The GNU C library | |
2366 | provides another set of extended functions which write the converted | |
2367 | string into a user-supplied buffer. These have the conventional | |
2368 | @code{_r} suffix. | |
2369 | ||
2370 | @code{gcvt_r} is not necessary, because @code{gcvt} already uses a | |
2371 | user-supplied buffer. | |
880f421f UD |
2372 | |
2373 | @comment stdlib.h | |
2374 | @comment GNU | |
7a68c94a UD |
2375 | @deftypefun {char *} ecvt_r (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len}) |
2376 | The @code{ecvt_r} function is the same as @code{ecvt}, except | |
2377 | that it places its result into the user-specified buffer pointed to by | |
2378 | @var{buf}, with length @var{len}. | |
880f421f | 2379 | |
7a68c94a | 2380 | This function is a GNU extension. |
880f421f UD |
2381 | @end deftypefun |
2382 | ||
2383 | @comment stdlib.h | |
2384 | @comment SVID, Unix98 | |
0ea5db4f | 2385 | @deftypefun {char *} fcvt_r (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len}) |
7a68c94a UD |
2386 | The @code{fcvt_r} function is the same as @code{fcvt}, except |
2387 | that it places its result into the user-specified buffer pointed to by | |
2388 | @var{buf}, with length @var{len}. | |
880f421f | 2389 | |
7a68c94a | 2390 | This function is a GNU extension. |
880f421f UD |
2391 | @end deftypefun |
2392 | ||
2393 | @comment stdlib.h | |
2394 | @comment GNU | |
7a68c94a UD |
2395 | @deftypefun {char *} qecvt_r (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len}) |
2396 | The @code{qecvt_r} function is the same as @code{qecvt}, except | |
2397 | that it places its result into the user-specified buffer pointed to by | |
2398 | @var{buf}, with length @var{len}. | |
880f421f | 2399 | |
7a68c94a | 2400 | This function is a GNU extension. |
880f421f UD |
2401 | @end deftypefun |
2402 | ||
2403 | @comment stdlib.h | |
2404 | @comment GNU | |
0ea5db4f | 2405 | @deftypefun {char *} qfcvt_r (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len}) |
7a68c94a UD |
2406 | The @code{qfcvt_r} function is the same as @code{qfcvt}, except |
2407 | that it places its result into the user-specified buffer pointed to by | |
2408 | @var{buf}, with length @var{len}. | |
880f421f | 2409 | |
7a68c94a | 2410 | This function is a GNU extension. |
880f421f | 2411 | @end deftypefun |