Change definition of mul macro.
[kopensolaris-gnu/glibc.git] / manual / arith.texi
1 @c We need some definitions here.
2 @ifclear cdot
3 @ifhtml
4 @set cdot ·
5 @macro mul
6 ·
7 @end macro
8 @end ifhtml
9 @iftex
10 @set cdot ·
11 @macro mul
12 @cdot
13 @end macro
14 @end iftex
15 @ifclear cdot
16 @set cdot x
17 @macro mul
18 x
19 @end macro
20 @end ifclear
21 @end ifclear
22
23 @node Arithmetic, Date and Time, Mathematics, Top
24 @chapter Low-Level Arithmetic Functions
25
26 This chapter contains information about functions for doing basic
27 arithmetic operations, such as splitting a float into its integer and
28 fractional parts or retrieving the imaginary part of a complex value.
29 These functions are declared in the header files @file{math.h} and
30 @file{complex.h}.
31
32 @menu
33 * Infinity::                    What is Infinity and how to test for it.
34 * Not a Number::                Making NaNs and testing for NaNs.
35 * Imaginary Unit::              Constructing complex Numbers.
36 * Predicates on Floats::        Testing for infinity and for NaNs.
37 * Floating-Point Classes::      Classify floating-point numbers.
38 * Operations on Complex::       Projections, Conjugates, and Decomposing.
39 * Absolute Value::              Absolute value functions.
40 * Normalization Functions::     Hacks for radix-2 representations.
41 * Rounding and Remainders::     Determining the integer and
42                                  fractional parts of a float.
43 * Arithmetic on FP Values::     Setting and Modifying Single Bits of FP Values.
44 * Special arithmetic on FPs::   Special Arithmetic on FPs.
45 * Integer Division::            Functions for performing integer
46                                  division.
47 * Parsing of Numbers::          Functions for ``reading'' numbers
48                                  from strings.
49 @end menu
50
51 @node Infinity
52 @section Infinity Values
53 @cindex Infinity
54 @cindex IEEE floating point
55
56 Mathematical operations easily can produce as the result values which
57 are not representable by the floating-point format.  The functions in
58 the mathematics library also have this problem.  The situation is
59 generally solved by raising an overflow exception and by returning a
60 huge value.
61
62 The @w{IEEE 754} floating-point defines a special value to be used in
63 these situations.  There is a special value for infinity.
64
65 @comment math.h
66 @comment ISO
67 @deftypevr Macro float INFINITY
68 An expression representing the infinite value.  @code{INFINITY} values are
69 produced by mathematical operations like @code{1.0 / 0.0}.  It is
70 possible to continue the computations with this value since the basic
71 operations as well as the mathematical library functions are prepared to
72 handle values like this.
73
74 Beside @code{INFINITY} also the value @code{-INFINITY} is representable
75 and it is handled differently if needed.  It is possible to test a
76 value for infiniteness using a simple comparison but the
77 recommended way is to use the the @code{isinf} function.
78
79 This macro was introduced in the @w{ISO C 9X} standard.
80 @end deftypevr
81
82 @vindex HUGE_VAL
83 The macros @code{HUGE_VAL}, @code{HUGE_VALF} and @code{HUGE_VALL} are
84 defined in a similar way but they are not required to represent the
85 infinite value, only a very large value (@pxref{Domain and Range Errors}).
86 If actually infinity is wanted, @code{INFINITY} should be used.
87
88
89 @node Not a Number
90 @section ``Not a Number'' Values
91 @cindex NaN
92 @cindex not a number
93 @cindex IEEE floating point
94
95 The IEEE floating point format used by most modern computers supports
96 values that are ``not a number''.  These values are called @dfn{NaNs}.
97 ``Not a number'' values result from certain operations which have no
98 meaningful numeric result, such as zero divided by zero or infinity
99 divided by infinity.
100
101 One noteworthy property of NaNs is that they are not equal to
102 themselves.  Thus, @code{x == x} can be 0 if the value of @code{x} is a
103 NaN.  You can use this to test whether a value is a NaN or not: if it is
104 not equal to itself, then it is a NaN.  But the recommended way to test
105 for a NaN is with the @code{isnan} function (@pxref{Predicates on Floats}).
106
107 Almost any arithmetic operation in which one argument is a NaN returns
108 a NaN.
109
110 @comment math.h
111 @comment GNU
112 @deftypevr Macro float NAN
113 An expression representing a value which is ``not a number''.  This
114 macro is a GNU extension, available only on machines that support ``not
115 a number'' values---that is to say, on all machines that support IEEE
116 floating point.
117
118 You can use @samp{#ifdef NAN} to test whether the machine supports
119 NaNs.  (Of course, you must arrange for GNU extensions to be visible,
120 such as by defining @code{_GNU_SOURCE}, and then you must include
121 @file{math.h}.)
122 @end deftypevr
123
124 @node Imaginary Unit
125 @section Constructing complex Numbers
126
127 @pindex complex.h
128 To construct complex numbers it is necessary have a way to express the
129 imaginary part of the numbers.  In mathematics one uses the symbol ``i''
130 to mark a number as imaginary.  For convenience the @file{complex.h}
131 header defines two macros which allow to use a similar easy notation.
132
133 @deftypevr Macro {const float complex} _Complex_I
134 This macro is a representation of the complex number ``@math{0+1i}''.
135 Computing
136
137 @smallexample
138 _Complex_I * _Complex_I = -1
139 @end smallexample
140
141 @noindent
142 leads to a real-valued result.  If no @code{imaginary} types are
143 available it is easiest to use this value to construct complex numbers
144 from real values:
145
146 @smallexample
147 3.0 - _Complex_I * 4.0
148 @end smallexample
149 @end deftypevr
150
151 @noindent
152 Without an optimizing compiler this is more expensive than the use of
153 @code{_Imaginary_I} but with is better than nothing.  You can avoid all
154 the hassles if you use the @code{I} macro below if the name is not
155 problem.
156
157 @deftypevr Macro {const float imaginary} _Imaginary_I
158 This macro is a representation of the value ``@math{1i}''.  I.e., it is
159 the value for which
160
161 @smallexample
162 _Imaginary_I * _Imaginary_I = -1
163 @end smallexample
164
165 @noindent
166 The result is not of type @code{float imaginary} but instead @code{float}.
167 One can use it to easily construct complex number like in
168
169 @smallexample
170 3.0 - _Imaginary_I * 4.0
171 @end smallexample
172
173 @noindent
174 which results in the complex number with a real part of 3.0 and a
175 imaginary part -4.0.
176 @end deftypevr
177
178 @noindent
179 A more intuitive approach is to use the following macro.
180
181 @deftypevr Macro {const float imaginary} I
182 This macro has exactly the same value as @code{_Imaginary_I}.  The
183 problem is that the name @code{I} very easily can clash with macros or
184 variables in programs and so it might be a good idea to avoid this name
185 and stay at the safe side by using @code{_Imaginary_I}.
186
187 If the implementation does not support the @code{imaginary} types
188 @code{I} is defined as @code{_Complex_I} which is the second best
189 solution.  It still can be used in the same way but requires a most
190 clever compiler to get the same results.
191 @end deftypevr
192
193
194 @node Predicates on Floats
195 @section Predicates on Floats
196
197 @pindex math.h
198 This section describes some miscellaneous test functions on doubles.
199 Prototypes for these functions appear in @file{math.h}.  These are BSD
200 functions, and thus are available if you define @code{_BSD_SOURCE} or
201 @code{_GNU_SOURCE}.
202
203 @comment math.h
204 @comment BSD
205 @deftypefun int isinf (double @var{x})
206 @deftypefunx int isinff (float @var{x})
207 @deftypefunx int isinfl (long double @var{x})
208 This function returns @code{-1} if @var{x} represents negative infinity,
209 @code{1} if @var{x} represents positive infinity, and @code{0} otherwise.
210 @end deftypefun
211
212 @comment math.h
213 @comment BSD
214 @deftypefun int isnan (double @var{x})
215 @deftypefunx int isnanf (float @var{x})
216 @deftypefunx int isnanl (long double @var{x})
217 This function returns a nonzero value if @var{x} is a ``not a number''
218 value, and zero otherwise.  (You can just as well use @code{@var{x} !=
219 @var{x}} to get the same result).
220
221 However, @code{isnan} will not raise an invalid exception if @var{x} is
222 a signalling NaN, while @code{@var{x} != @var{x}} will.  This makes
223 @code{isnan} much slower than the alternative; in code where performance
224 matters and signalling NaNs are unimportant, it's usually better to use
225 @code{@var{x} != @var{x}}, even though this is harder to understand.
226
227 @end deftypefun
228
229 @comment math.h
230 @comment BSD
231 @deftypefun int finite (double @var{x})
232 @deftypefunx int finitef (float @var{x})
233 @deftypefunx int finitel (long double @var{x})
234 This function returns a nonzero value if @var{x} is finite or a ``not a
235 number'' value, and zero otherwise.
236 @end deftypefun
237
238 @comment math.h
239 @comment BSD
240 @deftypefun double infnan (int @var{error})
241 This function is provided for compatibility with BSD.  The other
242 mathematical functions use @code{infnan} to decide what to return on
243 occasion of an error.  Its argument is an error code, @code{EDOM} or
244 @code{ERANGE}; @code{infnan} returns a suitable value to indicate this
245 with.  @code{-ERANGE} is also acceptable as an argument, and corresponds
246 to @code{-HUGE_VAL} as a value.
247
248 In the BSD library, on certain machines, @code{infnan} raises a fatal
249 signal in all cases.  The GNU library does not do likewise, because that
250 does not fit the @w{ISO C} specification.
251 @end deftypefun
252
253 @strong{Portability Note:} The functions listed in this section are BSD
254 extensions.
255
256 @node Floating-Point Classes
257 @section Floating-Point Number Classification Functions
258
259 Instead of using the BSD specific functions from the last section it is
260 better to use those in this section which are introduced in the @w{ISO C
261 9X} standard and are therefore widely available.
262
263 @comment math.h
264 @comment ISO
265 @deftypefn {Macro} int fpclassify (@emph{float-type} @var{x})
266 This is a generic macro which works on all floating-point types and
267 which returns a value of type @code{int}.  The possible values are:
268
269 @vtable @code
270 @item FP_NAN
271 The floating-point number @var{x} is ``Not a Number'' (@pxref{Not a Number})
272 @item FP_INFINITE
273 The value of @var{x} is either plus or minus infinity (@pxref{Infinity})
274 @item FP_ZERO
275 The value of @var{x} is zero.  In floating-point formats like @w{IEEE
276 754} where the zero value can be signed this value is also returned if
277 @var{x} is minus zero.
278 @item FP_SUBNORMAL
279 Some floating-point formats (such as @w{IEEE 754}) allow floating-point
280 numbers to be represented in a denormalized format.  This happens if the
281 absolute value of the number is too small to be represented in the
282 normal format.  @code{FP_SUBNORMAL} is returned for such values of @var{x}.
283 @item FP_NORMAL
284 This value is returned for all other cases which means the number is a
285 plain floating-point number without special meaning.
286 @end vtable
287
288 This macro is useful if more than property of a number must be
289 tested.  If one only has to test for, e.g., a NaN value, there are
290 function which are faster.
291 @end deftypefn
292
293 The remainder of this section introduces some more specific functions.
294 They might be implemented faster than the call to @code{fpclassify} and
295 if the actual need in the program is covered be these functions they
296 should be used (and not @code{fpclassify}).
297
298 @comment math.h
299 @comment ISO
300 @deftypefn {Macro} int isfinite (@emph{float-type} @var{x})
301 The value returned by this macro is nonzero if the value of @var{x} is
302 not plus or minus infinity and not NaN.  I.e., it could be implemented as
303
304 @smallexample
305 (fpclassify (x) != FP_NAN && fpclassify (x) != FP_INFINITE)
306 @end smallexample
307
308 @code{isfinite} is also implemented as a macro which can handle all
309 floating-point types.  Programs should use this function instead of
310 @var{finite} (@pxref{Predicates on Floats}).
311 @end deftypefn
312
313 @comment math.h
314 @comment ISO
315 @deftypefn {Macro} int isnormal (@emph{float-type} @var{x})
316 If @code{isnormal} returns a nonzero value the value or @var{x} is
317 neither a NaN, infinity, zero, nor a denormalized number.  I.e., it
318 could be implemented as
319
320 @smallexample
321 (fpclassify (x) == FP_NORMAL)
322 @end smallexample
323 @end deftypefn
324
325 @comment math.h
326 @comment ISO
327 @deftypefn {Macro} int isnan (@emph{float-type} @var{x})
328 The situation with this macro is a bit complicated.  Here @code{isnan}
329 is a macro which can handle all kinds of floating-point types.  It
330 returns a nonzero value is @var{x} does not represent a NaN value and
331 could be written like this
332
333 @smallexample
334 (fpclassify (x) == FP_NAN)
335 @end smallexample
336
337 The complication is that there is a function of the same name and the
338 same semantic defined for compatibility with BSD (@pxref{Predicates on
339 Floats}).  Fortunately this should not yield to problems in most cases
340 since the macro and the function have the same semantic.  Should in a
341 situation the function be absolutely necessary one can use
342
343 @smallexample
344 (isnan) (x)
345 @end smallexample
346
347 @noindent
348 to avoid the macro expansion.  Using the macro has two big advantages:
349 it is more portable and one does not have to choose the right function
350 among @code{isnan}, @code{isnanf}, and @code{isnanl}.
351 @end deftypefn
352
353
354 @node Operations on Complex
355 @section Projections, Conjugates, and Decomposing of Complex Numbers
356 @cindex project complex numbers
357 @cindex conjugate complex numbers
358 @cindex decompose complex numbers
359
360 This section lists functions performing some of the simple mathematical
361 operations on complex numbers.  Using any of the function requires that
362 the C compiler understands the @code{complex} keyword, introduced to the
363 C language in the @w{ISO C 9X} standard.
364
365 @pindex complex.h
366 The prototypes for all functions in this section can be found in
367 @file{complex.h}.  All functions are available in three variants, one
368 for each of the three floating-point types.
369
370 The easiest operation on complex numbers is the decomposition in the
371 real part and the imaginary part.  This is done by the next two
372 functions.
373
374 @comment complex.h
375 @comment ISO
376 @deftypefun double creal (complex double @var{z})
377 @deftypefunx float crealf (complex float @var{z})
378 @deftypefunx {long double} creall (complex long double @var{z})
379 These functions return the real part of the complex number @var{z}.
380 @end deftypefun
381
382 @comment complex.h
383 @comment ISO
384 @deftypefun double cimag (complex double @var{z})
385 @deftypefunx float cimagf (complex float @var{z})
386 @deftypefunx {long double} cimagl (complex long double @var{z})
387 These functions return the imaginary part of the complex number @var{z}.
388 @end deftypefun
389
390
391 The conjugate complex value of a given complex number has the same value
392 for the real part but the complex part is negated.
393
394 @comment complex.h
395 @comment ISO
396 @deftypefun {complex double} conj (complex double @var{z})
397 @deftypefunx {complex float} conjf (complex float @var{z})
398 @deftypefunx {complex long double} conjl (complex long double @var{z})
399 These functions return the conjugate complex value of the complex number
400 @var{z}.
401 @end deftypefun
402
403 @comment complex.h
404 @comment ISO
405 @deftypefun double carg (complex double @var{z})
406 @deftypefunx float cargf (complex float @var{z})
407 @deftypefunx {long double} cargl (complex long double @var{z})
408 These functions return argument of the complex number @var{z}.
409
410 Mathematically, the argument is the phase angle of @var{z} with a branch
411 cut along the negative real axis.
412 @end deftypefun
413
414 @comment complex.h
415 @comment ISO
416 @deftypefun {complex double} cproj (complex double @var{z})
417 @deftypefunx {complex float} cprojf (complex float @var{z})
418 @deftypefunx {complex long double} cprojl (complex long double @var{z})
419 Return the projection of the complex value @var{z} on the Riemann
420 sphere.  Values with a infinite complex part (even if the real part
421 is NaN) are projected to positive infinite on the real axis.  If the
422 real part is infinite, the result is equivalent to
423
424 @smallexample
425 INFINITY + I * copysign (0.0, cimag (z))
426 @end smallexample
427 @end deftypefun
428
429
430 @node Absolute Value
431 @section Absolute Value
432 @cindex absolute value functions
433
434 These functions are provided for obtaining the @dfn{absolute value} (or
435 @dfn{magnitude}) of a number.  The absolute value of a real number
436 @var{x} is @var{x} is @var{x} is positive, @minus{}@var{x} if @var{x} is
437 negative.  For a complex number @var{z}, whose real part is @var{x} and
438 whose imaginary part is @var{y}, the absolute value is @w{@code{sqrt
439 (@var{x}*@var{x} + @var{y}*@var{y})}}.
440
441 @pindex math.h
442 @pindex stdlib.h
443 Prototypes for @code{abs}, @code{labs} and @code{llabs} are in @file{stdlib.h};
444 @code{fabs}, @code{fabsf} and @code{fabsl} are declared in @file{math.h};
445 @code{cabs}, @code{cabsf} and @code{cabsl} are declared in @file{complex.h}.
446
447 @comment stdlib.h
448 @comment ISO
449 @deftypefun int abs (int @var{number})
450 This function returns the absolute value of @var{number}.
451
452 Most computers use a two's complement integer representation, in which
453 the absolute value of @code{INT_MIN} (the smallest possible @code{int})
454 cannot be represented; thus, @w{@code{abs (INT_MIN)}} is not defined.
455 @end deftypefun
456
457 @comment stdlib.h
458 @comment ISO
459 @deftypefun {long int} labs (long int @var{number})
460 This is similar to @code{abs}, except that both the argument and result
461 are of type @code{long int} rather than @code{int}.
462 @end deftypefun
463
464 @comment stdlib.h
465 @comment ISO
466 @deftypefun {long long int} llabs (long long int @var{number})
467 This is similar to @code{abs}, except that both the argument and result
468 are of type @code{long long int} rather than @code{int}.
469
470 This function is defined in @w{ISO C 9X}.
471 @end deftypefun
472
473 @comment math.h
474 @comment ISO
475 @deftypefun double fabs (double @var{number})
476 @deftypefunx float fabsf (float @var{number})
477 @deftypefunx {long double} fabsl (long double @var{number})
478 This function returns the absolute value of the floating-point number
479 @var{number}.
480 @end deftypefun
481
482 @comment complex.h
483 @comment ISO
484 @deftypefun double cabs (complex double @var{z})
485 @deftypefunx float cabsf (complex float @var{z})
486 @deftypefunx {long double} cabsl (complex long double @var{z})
487 These functions return the absolute value of the complex number @var{z}.
488 The compiler must support complex numbers to use these functions.  The
489 value is:
490
491 @smallexample
492 sqrt (creal (@var{z}) * creal (@var{z}) + cimag (@var{z}) * cimag (@var{z}))
493 @end smallexample
494
495 This function should always be used instead of the direct formula since
496 using the simple straight-forward method can mean to lose accuracy.  If
497 one of the squared values is neglectable in size compared to the other
498 value the result should be the same as the larger value.  But squaring
499 the value and afterwards using the square root function leads to
500 inaccuracy.  See @code{hypot} in @xref{Exponents and Logarithms}.
501 @end deftypefun
502
503 @node Normalization Functions
504 @section Normalization Functions
505 @cindex normalization functions (floating-point)
506
507 The functions described in this section are primarily provided as a way
508 to efficiently perform certain low-level manipulations on floating point
509 numbers that are represented internally using a binary radix;
510 see @ref{Floating Point Concepts}.  These functions are required to
511 have equivalent behavior even if the representation does not use a radix
512 of 2, but of course they are unlikely to be particularly efficient in
513 those cases.
514
515 @pindex math.h
516 All these functions are declared in @file{math.h}.
517
518 @comment math.h
519 @comment ISO
520 @deftypefun double frexp (double @var{value}, int *@var{exponent})
521 @deftypefunx float frexpf (float @var{value}, int *@var{exponent})
522 @deftypefunx {long double} frexpl (long double @var{value}, int *@var{exponent})
523 These functions are used to split the number @var{value}
524 into a normalized fraction and an exponent.
525
526 If the argument @var{value} is not zero, the return value is @var{value}
527 times a power of two, and is always in the range 1/2 (inclusive) to 1
528 (exclusive).  The corresponding exponent is stored in
529 @code{*@var{exponent}}; the return value multiplied by 2 raised to this
530 exponent equals the original number @var{value}.
531
532 For example, @code{frexp (12.8, &exponent)} returns @code{0.8} and
533 stores @code{4} in @code{exponent}.
534
535 If @var{value} is zero, then the return value is zero and
536 zero is stored in @code{*@var{exponent}}.
537 @end deftypefun
538
539 @comment math.h
540 @comment ISO
541 @deftypefun double ldexp (double @var{value}, int @var{exponent})
542 @deftypefunx float ldexpf (float @var{value}, int @var{exponent})
543 @deftypefunx {long double} ldexpl (long double @var{value}, int @var{exponent})
544 These functions return the result of multiplying the floating-point
545 number @var{value} by 2 raised to the power @var{exponent}.  (It can
546 be used to reassemble floating-point numbers that were taken apart
547 by @code{frexp}.)
548
549 For example, @code{ldexp (0.8, 4)} returns @code{12.8}.
550 @end deftypefun
551
552 The following functions which come from BSD provide facilities
553 equivalent to those of @code{ldexp} and @code{frexp}:
554
555 @comment math.h
556 @comment BSD
557 @deftypefun double scalb (double @var{value}, int @var{exponent})
558 @deftypefunx float scalbf (float @var{value}, int @var{exponent})
559 @deftypefunx {long double} scalbl (long double @var{value}, int @var{exponent})
560 The @code{scalb} function is the BSD name for @code{ldexp}.
561 @end deftypefun
562
563 @comment math.h
564 @comment BSD
565 @deftypefun double logb (double @var{x})
566 @deftypefunx float logbf (float @var{x})
567 @deftypefunx {long double} logbl (long double @var{x})
568 These BSD functions return the integer part of the base-2 logarithm of
569 @var{x}, an integer value represented in type @code{double}.  This is
570 the highest integer power of @code{2} contained in @var{x}.  The sign of
571 @var{x} is ignored.  For example, @code{logb (3.5)} is @code{1.0} and
572 @code{logb (4.0)} is @code{2.0}.
573
574 When @code{2} raised to this power is divided into @var{x}, it gives a
575 quotient between @code{1} (inclusive) and @code{2} (exclusive).
576
577 If @var{x} is zero, the value is minus infinity (if the machine supports
578 such a value), or else a very small number.  If @var{x} is infinity, the
579 value is infinity.
580
581 The value returned by @code{logb} is one less than the value that
582 @code{frexp} would store into @code{*@var{exponent}}.
583 @end deftypefun
584
585 @node Rounding and Remainders
586 @section Rounding and Remainder Functions
587 @cindex rounding functions
588 @cindex remainder functions
589 @cindex converting floats to integers
590
591 @pindex math.h
592 The functions listed here perform operations such as rounding,
593 truncation, and remainder in division of floating point numbers.  Some
594 of these functions convert floating point numbers to integer values.
595 They are all declared in @file{math.h}.
596
597 You can also convert floating-point numbers to integers simply by
598 casting them to @code{int}.  This discards the fractional part,
599 effectively rounding towards zero.  However, this only works if the
600 result can actually be represented as an @code{int}---for very large
601 numbers, this is impossible.  The functions listed here return the
602 result as a @code{double} instead to get around this problem.
603
604 @comment math.h
605 @comment ISO
606 @deftypefun double ceil (double @var{x})
607 @deftypefunx float ceilf (float @var{x})
608 @deftypefunx {long double} ceill (long double @var{x})
609 These functions round @var{x} upwards to the nearest integer,
610 returning that value as a @code{double}.  Thus, @code{ceil (1.5)}
611 is @code{2.0}.
612 @end deftypefun
613
614 @comment math.h
615 @comment ISO
616 @deftypefun double floor (double @var{x})
617 @deftypefunx float floorf (float @var{x})
618 @deftypefunx {long double} floorl (long double @var{x})
619 These functions round @var{x} downwards to the nearest
620 integer, returning that value as a @code{double}.  Thus, @code{floor
621 (1.5)} is @code{1.0} and @code{floor (-1.5)} is @code{-2.0}.
622 @end deftypefun
623
624 @comment math.h
625 @comment ISO
626 @deftypefun double rint (double @var{x})
627 @deftypefunx float rintf (float @var{x})
628 @deftypefunx {long double} rintl (long double @var{x})
629 These functions round @var{x} to an integer value according to the
630 current rounding mode.  @xref{Floating Point Parameters}, for
631 information about the various rounding modes.  The default
632 rounding mode is to round to the nearest integer; some machines
633 support other modes, but round-to-nearest is always used unless
634 you explicit select another.
635 @end deftypefun
636
637 @comment math.h
638 @comment ISO
639 @deftypefun double nearbyint (double @var{x})
640 @deftypefunx float nearbyintf (float @var{x})
641 @deftypefunx {long double} nearbyintl (long double @var{x})
642 These functions return the same value as the @code{rint} functions but
643 even some rounding actually takes place @code{nearbyint} does @emph{not}
644 raise the inexact exception.
645 @end deftypefun
646
647 @comment math.h
648 @comment ISO
649 @deftypefun double modf (double @var{value}, double *@var{integer-part})
650 @deftypefunx float modff (float @var{value}, float *@var{integer-part})
651 @deftypefunx {long double} modfl (long double @var{value}, long double *@var{integer-part})
652 These functions break the argument @var{value} into an integer part and a
653 fractional part (between @code{-1} and @code{1}, exclusive).  Their sum
654 equals @var{value}.  Each of the parts has the same sign as @var{value},
655 so the rounding of the integer part is towards zero.
656
657 @code{modf} stores the integer part in @code{*@var{integer-part}}, and
658 returns the fractional part.  For example, @code{modf (2.5, &intpart)}
659 returns @code{0.5} and stores @code{2.0} into @code{intpart}.
660 @end deftypefun
661
662 @comment math.h
663 @comment ISO
664 @deftypefun double fmod (double @var{numerator}, double @var{denominator})
665 @deftypefunx float fmodf (float @var{numerator}, float @var{denominator})
666 @deftypefunx {long double} fmodl (long double @var{numerator}, long double @var{denominator})
667 These functions compute the remainder from the division of
668 @var{numerator} by @var{denominator}.  Specifically, the return value is
669 @code{@var{numerator} - @w{@var{n} * @var{denominator}}}, where @var{n}
670 is the quotient of @var{numerator} divided by @var{denominator}, rounded
671 towards zero to an integer.  Thus, @w{@code{fmod (6.5, 2.3)}} returns
672 @code{1.9}, which is @code{6.5} minus @code{4.6}.
673
674 The result has the same sign as the @var{numerator} and has magnitude
675 less than the magnitude of the @var{denominator}.
676
677 If @var{denominator} is zero, @code{fmod} fails and sets @code{errno} to
678 @code{EDOM}.
679 @end deftypefun
680
681 @comment math.h
682 @comment BSD
683 @deftypefun double drem (double @var{numerator}, double @var{denominator})
684 @deftypefunx float dremf (float @var{numerator}, float @var{denominator})
685 @deftypefunx {long double} dreml (long double @var{numerator}, long double @var{denominator})
686 These functions are like @code{fmod} etc except that it rounds the
687 internal quotient @var{n} to the nearest integer instead of towards zero
688 to an integer.  For example, @code{drem (6.5, 2.3)} returns @code{-0.4},
689 which is @code{6.5} minus @code{6.9}.
690
691 The absolute value of the result is less than or equal to half the
692 absolute value of the @var{denominator}.  The difference between
693 @code{fmod (@var{numerator}, @var{denominator})} and @code{drem
694 (@var{numerator}, @var{denominator})} is always either
695 @var{denominator}, minus @var{denominator}, or zero.
696
697 If @var{denominator} is zero, @code{drem} fails and sets @code{errno} to
698 @code{EDOM}.
699 @end deftypefun
700
701
702 @node Arithmetic on FP Values
703 @section Setting and modifying Single Bits of FP Values
704 @cindex FP arithmetic
705
706 In certain situations it is too complicated (or expensive) to modify a
707 floating-point value by the normal operations.  For a few operations
708 @w{ISO C 9X} defines functions to modify the floating-point value
709 directly.
710
711 @comment math.h
712 @comment ISO
713 @deftypefun double copysign (double @var{x}, double @var{y})
714 @deftypefunx float copysignf (float @var{x}, float @var{y})
715 @deftypefunx {long double} copysignl (long double @var{x}, long double @var{y})
716 The @code{copysign} function allows to specifiy the sign of the
717 floating-point value given in the parameter @var{x} by discarding the
718 prior content and replacing it with the sign of the value @var{y}.
719 The so found value is returned.
720
721 This function also works and throws no exception if the parameter
722 @var{x} is a @code{NaN}.  If the platform supports the signed zero
723 representation @var{x} might also be zero.
724
725 This function is defined in @w{IEC 559} (and the appendix with
726 recommended functions in @w{IEEE 754}/@w{IEEE 854}).
727 @end deftypefun
728
729 @comment math.h
730 @comment ISO
731 @deftypefun int signbit (@emph{float-type} @var{x})
732 @code{signbit} is a generic macro which can work on all floating-point
733 types.  It returns a nonzero value if the value of @var{x} has its sign
734 bit set.
735
736 This is not the same as @code{x < 0.0} since in some floating-point
737 formats (e.g., @w{IEEE 754}) the zero value is optionally signed.  The
738 comparison @code{-0.0 < 0.0} will not be true while @code{signbit
739 (-0.0)} will return a nonzero value.
740 @end deftypefun
741
742 @comment math.h
743 @comment ISO
744 @deftypefun double nextafter (double @var{x}, double @var{y})
745 @deftypefunx float nextafterf (float @var{x}, float @var{y})
746 @deftypefunx {long double} nextafterl (long double @var{x}, long double @var{y})
747 The @code{nextafter} function returns the next representable neighbor of
748 @var{x} in the direction towards @var{y}.  Depending on the used data
749 type the steps make have a different size.  If @math{@var{x} = @var{y}}
750 the function simply returns @var{x}.  If either value is a @code{NaN}
751 one the @code{NaN} values is returned.  Otherwise a value corresponding
752 to the value of the least significant bit in the mantissa is
753 added/subtracted (depending on the direction).  If the resulting value
754 is not finite but @var{x} is, overflow is signaled.  Underflow is
755 signaled if the resulting value is a denormalized number (if the @w{IEEE
756 754}/@w{IEEE 854} representation is used).
757
758 This function is defined in @w{IEC 559} (and the appendix with
759 recommended functions in @w{IEEE 754}/@w{IEEE 854}).
760 @end deftypefun
761
762 @cindex NaN
763 @comment math.h
764 @comment ISO
765 @deftypefun double nan (const char *@var{tagp})
766 @deftypefunx float nanf (const char *@var{tagp})
767 @deftypefunx {long double} nanl (const char *@var{tagp})
768 The @code{nan} function returns a representation of the NaN value.  If
769 quiet NaNs are supported by the platform a call like @code{nan
770 ("@var{n-char-sequence}")} is equivalent to @code{strtod
771 ("NAN(@var{n-char-sequence})")}.  The exact implementation is left
772 unspecified but on systems using IEEE arithmethic the
773 @var{n-char-sequence} specifies the bits of the mantissa for the NaN
774 value.
775 @end deftypefun
776
777
778 @node Special arithmetic on FPs
779 @section Special Arithmetic on FPs
780 @cindex positive difference
781 @cindex minimum
782 @cindex maximum
783
784 A frequent operation of numbers is the determination of mimuma, maxima,
785 or the difference between numbers.  The @w{ISO C 9X} standard introduces
786 three functions which implement this efficiently while also providing
787 some useful functions which is not so efficient to implement.  Machine
788 specific implementation might perform this very efficient.
789
790 @comment math.h
791 @comment ISO
792 @deftypefun double fmin (double @var{x}, double @var{y})
793 @deftypefunx float fminf (float @var{x}, float @var{y})
794 @deftypefunx {long double} fminl (long double @var{x}, long double @var{y})
795 The @code{fmin} function determine the minimum of the two values @var{x}
796 and @var{y} and returns it.
797
798 If an argument is NaN it as treated as missing and the other value is
799 returned.  If both values are NaN one of the values is returned.
800 @end deftypefun
801
802 @comment math.h
803 @comment ISO
804 @deftypefun double fmax (double @var{x}, double @var{y})
805 @deftypefunx float fmaxf (float @var{x}, float @var{y})
806 @deftypefunx {long double} fmaxl (long double @var{x}, long double @var{y})
807 The @code{fmax} function determine the maximum of the two values @var{x}
808 and @var{y} and returns it.
809
810 If an argument is NaN it as treated as missing and the other value is
811 returned.  If both values are NaN one of the values is returned.
812 @end deftypefun
813
814 @comment math.h
815 @comment ISO
816 @deftypefun double fdim (double @var{x}, double @var{y})
817 @deftypefunx float fdimf (float @var{x}, float @var{y})
818 @deftypefunx {long double} fdiml (long double @var{x}, long double @var{y})
819 The @code{fdim} function computes the positive difference between
820 @var{x} and @var{y} and returns this value.  @dfn{Positive difference}
821 means that if @var{x} is greater than @var{y} the value @math{@var{x} -
822 @var{y}} is returned.  Otherwise the return value is @math{+0}.
823
824 If any of the arguments is NaN this value is returned.  If both values
825 are NaN, one of the values is returned.
826 @end deftypefun
827
828 @comment math.h
829 @comment ISO
830 @deftypefun double fma (double @var{x}, double @var{y}, double @var{z})
831 @deftypefunx float fmaf (float @var{x}, float @var{y}, float @var{z})
832 @deftypefunx {long double} fmal (long double @var{x}, long double @var{y}, long double @var{z})
833 @cindex butterfly
834 The name of the function @code{fma} means floating-point multiply-add.
835 I.e., the operation performed is @math{(@var{x} @mul{} @var{y}) +
836 @var{z}}.  The speciality of this function is that the intermediate
837 result is not rounded and the addition is performed with the full
838 precision of the multiplcation.
839
840 This function was introduced because some processors provide such a
841 function in their FPU implementation.  Since compilers cannot optimize
842 code which performs the operation in single steps using this opcode
843 because of rounding differences the operation is available separately so
844 the programmer can select when the rounding of the intermediate result
845 is not important.
846
847 @vindex FP_FAST_FMA
848 If the @file{math.h} header defines the symbol @code{FP_FAST_FMA} (or
849 @code{FP_FAST_FMAF} and @code{FP_FAST_FMAL} for @code{float} and
850 @code{long double} respectively) the processor typically defines the
851 operation in hardware.  The symbols might also be defined if the
852 software implementation is as fast as a multiply and an add but in the
853 GNU C Library the macros indicate hardware support.
854 @end deftypefun
855
856
857 @node Integer Division
858 @section Integer Division
859 @cindex integer division functions
860
861 This section describes functions for performing integer division.  These
862 functions are redundant in the GNU C library, since in GNU C the @samp{/}
863 operator always rounds towards zero.  But in other C implementations,
864 @samp{/} may round differently with negative arguments.  @code{div} and
865 @code{ldiv} are useful because they specify how to round the quotient:
866 towards zero.  The remainder has the same sign as the numerator.
867
868 These functions are specified to return a result @var{r} such that the value
869 @code{@var{r}.quot*@var{denominator} + @var{r}.rem} equals
870 @var{numerator}.
871
872 @pindex stdlib.h
873 To use these facilities, you should include the header file
874 @file{stdlib.h} in your program.
875
876 @comment stdlib.h
877 @comment ISO
878 @deftp {Data Type} div_t
879 This is a structure type used to hold the result returned by the @code{div}
880 function.  It has the following members:
881
882 @table @code
883 @item int quot
884 The quotient from the division.
885
886 @item int rem
887 The remainder from the division.
888 @end table
889 @end deftp
890
891 @comment stdlib.h
892 @comment ISO
893 @deftypefun div_t div (int @var{numerator}, int @var{denominator})
894 This function @code{div} computes the quotient and remainder from
895 the division of @var{numerator} by @var{denominator}, returning the
896 result in a structure of type @code{div_t}.
897
898 If the result cannot be represented (as in a division by zero), the
899 behavior is undefined.
900
901 Here is an example, albeit not a very useful one.
902
903 @smallexample
904 div_t result;
905 result = div (20, -6);
906 @end smallexample
907
908 @noindent
909 Now @code{result.quot} is @code{-3} and @code{result.rem} is @code{2}.
910 @end deftypefun
911
912 @comment stdlib.h
913 @comment ISO
914 @deftp {Data Type} ldiv_t
915 This is a structure type used to hold the result returned by the @code{ldiv}
916 function.  It has the following members:
917
918 @table @code
919 @item long int quot
920 The quotient from the division.
921
922 @item long int rem
923 The remainder from the division.
924 @end table
925
926 (This is identical to @code{div_t} except that the components are of
927 type @code{long int} rather than @code{int}.)
928 @end deftp
929
930 @comment stdlib.h
931 @comment ISO
932 @deftypefun ldiv_t ldiv (long int @var{numerator}, long int @var{denominator})
933 The @code{ldiv} function is similar to @code{div}, except that the
934 arguments are of type @code{long int} and the result is returned as a
935 structure of type @code{ldiv_t}.
936 @end deftypefun
937
938 @comment stdlib.h
939 @comment GNU
940 @deftp {Data Type} lldiv_t
941 This is a structure type used to hold the result returned by the @code{lldiv}
942 function.  It has the following members:
943
944 @table @code
945 @item long long int quot
946 The quotient from the division.
947
948 @item long long int rem
949 The remainder from the division.
950 @end table
951
952 (This is identical to @code{div_t} except that the components are of
953 type @code{long long int} rather than @code{int}.)
954 @end deftp
955
956 @comment stdlib.h
957 @comment GNU
958 @deftypefun lldiv_t lldiv (long long int @var{numerator}, long long int @var{denominator})
959 The @code{lldiv} function is like the @code{div} function, but the
960 arguments are of type @code{long long int} and the result is returned as
961 a structure of type @code{lldiv_t}.
962
963 The @code{lldiv} function is a GNU extension but it will eventually be
964 part of the next ISO C standard.
965 @end deftypefun
966
967
968 @node Parsing of Numbers
969 @section Parsing of Numbers
970 @cindex parsing numbers (in formatted input)
971 @cindex converting strings to numbers
972 @cindex number syntax, parsing
973 @cindex syntax, for reading numbers
974
975 This section describes functions for ``reading'' integer and
976 floating-point numbers from a string.  It may be more convenient in some
977 cases to use @code{sscanf} or one of the related functions; see
978 @ref{Formatted Input}.  But often you can make a program more robust by
979 finding the tokens in the string by hand, then converting the numbers
980 one by one.
981
982 @menu
983 * Parsing of Integers::         Functions for conversion of integer values.
984 * Parsing of Floats::           Functions for conversion of floating-point
985                                  values.
986 @end menu
987
988 @node Parsing of Integers
989 @subsection Parsing of Integers
990
991 @pindex stdlib.h
992 These functions are declared in @file{stdlib.h}.
993
994 @comment stdlib.h
995 @comment ISO
996 @deftypefun {long int} strtol (const char *@var{string}, char **@var{tailptr}, int @var{base})
997 The @code{strtol} (``string-to-long'') function converts the initial
998 part of @var{string} to a signed integer, which is returned as a value
999 of type @code{long int}.
1000
1001 This function attempts to decompose @var{string} as follows:
1002
1003 @itemize @bullet
1004 @item
1005 A (possibly empty) sequence of whitespace characters.  Which characters
1006 are whitespace is determined by the @code{isspace} function
1007 (@pxref{Classification of Characters}).  These are discarded.
1008
1009 @item
1010 An optional plus or minus sign (@samp{+} or @samp{-}).
1011
1012 @item
1013 A nonempty sequence of digits in the radix specified by @var{base}.
1014
1015 If @var{base} is zero, decimal radix is assumed unless the series of
1016 digits begins with @samp{0} (specifying octal radix), or @samp{0x} or
1017 @samp{0X} (specifying hexadecimal radix); in other words, the same
1018 syntax used for integer constants in C.
1019
1020 Otherwise @var{base} must have a value between @code{2} and @code{35}.
1021 If @var{base} is @code{16}, the digits may optionally be preceded by
1022 @samp{0x} or @samp{0X}.  If base has no legal value the value returned
1023 is @code{0l} and the global variable @code{errno} is set to @code{EINVAL}.
1024
1025 @item
1026 Any remaining characters in the string.  If @var{tailptr} is not a null
1027 pointer, @code{strtol} stores a pointer to this tail in
1028 @code{*@var{tailptr}}.
1029 @end itemize
1030
1031 If the string is empty, contains only whitespace, or does not contain an
1032 initial substring that has the expected syntax for an integer in the
1033 specified @var{base}, no conversion is performed.  In this case,
1034 @code{strtol} returns a value of zero and the value stored in
1035 @code{*@var{tailptr}} is the value of @var{string}.
1036
1037 In a locale other than the standard @code{"C"} locale, this function
1038 may recognize additional implementation-dependent syntax.
1039
1040 If the string has valid syntax for an integer but the value is not
1041 representable because of overflow, @code{strtol} returns either
1042 @code{LONG_MAX} or @code{LONG_MIN} (@pxref{Range of Type}), as
1043 appropriate for the sign of the value.  It also sets @code{errno}
1044 to @code{ERANGE} to indicate there was overflow.
1045
1046 Because the value @code{0l} is a correct result for @code{strtol} the
1047 user who is interested in handling errors should set the global variable
1048 @code{errno} to @code{0} before calling this function, so that the program
1049 can later test whether an error occurred.
1050
1051 There is an example at the end of this section.
1052 @end deftypefun
1053
1054 @comment stdlib.h
1055 @comment ISO
1056 @deftypefun {unsigned long int} strtoul (const char *@var{string}, char **@var{tailptr}, int @var{base})
1057 The @code{strtoul} (``string-to-unsigned-long'') function is like
1058 @code{strtol} except it deals with unsigned numbers, and returns its
1059 value with type @code{unsigned long int}.  No @samp{+} or @samp{-} sign
1060 may appear before the number, but the syntax is otherwise the same as
1061 described above for @code{strtol}.  The value returned in case of
1062 overflow is @code{ULONG_MAX} (@pxref{Range of Type}).
1063
1064 Like @code{strtol} this function sets @code{errno} and returns the value
1065 @code{0ul} in case the value for @var{base} is not in the legal range.
1066 For @code{strtoul} this can happen in another situation.  In case the
1067 number to be converted is negative @code{strtoul} also sets @code{errno}
1068 to @code{EINVAL} and returns @code{0ul}.
1069 @end deftypefun
1070
1071 @comment stdlib.h
1072 @comment GNU
1073 @deftypefun {long long int} strtoll (const char *@var{string}, char **@var{tailptr}, int @var{base})
1074 The @code{strtoll} function is like @code{strtol} except that is deals
1075 with extra long numbers and it returns its value with type @code{long
1076 long int}.
1077
1078 If the string has valid syntax for an integer but the value is not
1079 representable because of overflow, @code{strtoll} returns either
1080 @code{LONG_LONG_MAX} or @code{LONG_LONG_MIN} (@pxref{Range of Type}), as
1081 appropriate for the sign of the value.  It also sets @code{errno} to
1082 @code{ERANGE} to indicate there was overflow.
1083
1084 The @code{strtoll} function is a GNU extension but it will eventually be
1085 part of the next ISO C standard.
1086 @end deftypefun
1087
1088 @comment stdlib.h
1089 @comment BSD
1090 @deftypefun {long long int} strtoq (const char *@var{string}, char **@var{tailptr}, int @var{base})
1091 @code{strtoq} (``string-to-quad-word'') is only an commonly used other
1092 name for the @code{strtoll} function.  Everything said for
1093 @code{strtoll} applies to @code{strtoq} as well.
1094 @end deftypefun
1095
1096 @comment stdlib.h
1097 @comment GNU
1098 @deftypefun {unsigned long long int} strtoull (const char *@var{string}, char **@var{tailptr}, int @var{base})
1099 The @code{strtoull} function is like @code{strtoul} except that is deals
1100 with extra long numbers and it returns its value with type
1101 @code{unsigned long long int}.  The value returned in case of overflow
1102 is @code{ULONG_LONG_MAX} (@pxref{Range of Type}).
1103
1104 The @code{strtoull} function is a GNU extension but it will eventually be
1105 part of the next ISO C standard.
1106 @end deftypefun
1107
1108 @comment stdlib.h
1109 @comment BSD
1110 @deftypefun {unsigned long long int} strtouq (const char *@var{string}, char **@var{tailptr}, int @var{base})
1111 @code{strtouq} (``string-to-unsigned-quad-word'') is only an commonly
1112 used other name for the @code{strtoull} function.  Everything said for
1113 @code{strtoull} applies to @code{strtouq} as well.
1114 @end deftypefun
1115
1116 @comment stdlib.h
1117 @comment ISO
1118 @deftypefun {long int} atol (const char *@var{string})
1119 This function is similar to the @code{strtol} function with a @var{base}
1120 argument of @code{10}, except that it need not detect overflow errors.
1121 The @code{atol} function is provided mostly for compatibility with
1122 existing code; using @code{strtol} is more robust.
1123 @end deftypefun
1124
1125 @comment stdlib.h
1126 @comment ISO
1127 @deftypefun int atoi (const char *@var{string})
1128 This function is like @code{atol}, except that it returns an @code{int}
1129 value rather than @code{long int}.  The @code{atoi} function is also
1130 considered obsolete; use @code{strtol} instead.
1131 @end deftypefun
1132
1133 @comment stdlib.h
1134 @comment GNU
1135 @deftypefun {long long int} atoll (const char *@var{string})
1136 This function is similar to @code{atol}, except it returns a @code{long
1137 long int} value rather than @code{long int}.
1138
1139 The @code{atoll} function is a GNU extension but it will eventually be
1140 part of the next ISO C standard.
1141 @end deftypefun
1142
1143 The POSIX locales contain some information about how to format numbers
1144 (@pxref{General Numeric}).  This mainly deals with representing numbers
1145 for better readability for humans.  The functions present so far in this
1146 section cannot handle numbers in this form.
1147
1148 If this functionality is needed in a program one can use the functions
1149 from the @code{scanf} family which know about the flag @samp{'} for
1150 parsing numeric input (@pxref{Numeric Input Conversions}).  Sometimes it
1151 is more desirable to have finer control.
1152
1153 In these situation one could use the function
1154 @code{__strto@var{XXX}_internal}.  @var{XXX} here stands for any of the
1155 above forms.  All numeric conversion functions (including the functions
1156 to process floating-point numbers) have such a counterpart.  The
1157 difference to the normal form is the extra argument at the end of the
1158 parameter list.  If this value has an non-zero value the handling of
1159 number grouping is enabled.  The advantage of using these functions is
1160 that the @var{tailptr} parameters allow to determine which part of the
1161 input is processed.  The @code{scanf} functions don't provide this
1162 information.  The drawback of using these functions is that they are not
1163 portable.  They only exist in the GNU C library.
1164
1165
1166 Here is a function which parses a string as a sequence of integers and
1167 returns the sum of them:
1168
1169 @smallexample
1170 int
1171 sum_ints_from_string (char *string)
1172 @{
1173   int sum = 0;
1174
1175   while (1) @{
1176     char *tail;
1177     int next;
1178
1179     /* @r{Skip whitespace by hand, to detect the end.}  */
1180     while (isspace (*string)) string++;
1181     if (*string == 0)
1182       break;
1183
1184     /* @r{There is more nonwhitespace,}  */
1185     /* @r{so it ought to be another number.}  */
1186     errno = 0;
1187     /* @r{Parse it.}  */
1188     next = strtol (string, &tail, 0);
1189     /* @r{Add it in, if not overflow.}  */
1190     if (errno)
1191       printf ("Overflow\n");
1192     else
1193       sum += next;
1194     /* @r{Advance past it.}  */
1195     string = tail;
1196   @}
1197
1198   return sum;
1199 @}
1200 @end smallexample
1201
1202 @node Parsing of Floats
1203 @subsection Parsing of Floats
1204
1205 @pindex stdlib.h
1206 These functions are declared in @file{stdlib.h}.
1207
1208 @comment stdlib.h
1209 @comment ISO
1210 @deftypefun double strtod (const char *@var{string}, char **@var{tailptr})
1211 The @code{strtod} (``string-to-double'') function converts the initial
1212 part of @var{string} to a floating-point number, which is returned as a
1213 value of type @code{double}.
1214
1215 This function attempts to decompose @var{string} as follows:
1216
1217 @itemize @bullet
1218 @item
1219 A (possibly empty) sequence of whitespace characters.  Which characters
1220 are whitespace is determined by the @code{isspace} function
1221 (@pxref{Classification of Characters}).  These are discarded.
1222
1223 @item
1224 An optional plus or minus sign (@samp{+} or @samp{-}).
1225
1226 @item
1227 A nonempty sequence of digits optionally containing a decimal-point
1228 character---normally @samp{.}, but it depends on the locale
1229 (@pxref{Numeric Formatting}).
1230
1231 @item
1232 An optional exponent part, consisting of a character @samp{e} or
1233 @samp{E}, an optional sign, and a sequence of digits.
1234
1235 @item
1236 Any remaining characters in the string.  If @var{tailptr} is not a null
1237 pointer, a pointer to this tail of the string is stored in
1238 @code{*@var{tailptr}}.
1239 @end itemize
1240
1241 If the string is empty, contains only whitespace, or does not contain an
1242 initial substring that has the expected syntax for a floating-point
1243 number, no conversion is performed.  In this case, @code{strtod} returns
1244 a value of zero and the value returned in @code{*@var{tailptr}} is the
1245 value of @var{string}.
1246
1247 In a locale other than the standard @code{"C"} or @code{"POSIX"} locales,
1248 this function may recognize additional locale-dependent syntax.
1249
1250 If the string has valid syntax for a floating-point number but the value
1251 is not representable because of overflow, @code{strtod} returns either
1252 positive or negative @code{HUGE_VAL} (@pxref{Mathematics}), depending on
1253 the sign of the value.  Similarly, if the value is not representable
1254 because of underflow, @code{strtod} returns zero.  It also sets @code{errno}
1255 to @code{ERANGE} if there was overflow or underflow.
1256
1257 There are two more special inputs which are recognized by @code{strtod}.
1258 The string @code{"inf"} or @code{"infinity"} (without consideration of
1259 case and optionally preceded by a @code{"+"} or @code{"-"} sign) is
1260 changed to the floating-point value for infinity if the floating-point
1261 format supports this; and to the largest representable value otherwise.
1262
1263 If the input string is @code{"nan"} or
1264 @code{"nan(@var{n-char-sequence})"} the return value of @code{strtod} is
1265 the representation of the NaN (not a number) value (if the
1266 floating-point format supports this).  In the second form the part
1267 @var{n-char-sequence} allows to specify the form of the NaN value in an
1268 implementation specific way.  When using the @w{IEEE 754}
1269 floating-point format, the NaN value can have a lot of forms since only
1270 at least one bit in the mantissa must be set.  In the GNU C library
1271 implementation of @code{strtod} the @var{n-char-sequence} is interpreted
1272 as a number (as recognized by @code{strtol}, @pxref{Parsing of Integers}).
1273 The mantissa of the return value corresponds to this given number.
1274
1275 Since the value zero which is returned in the error case is also a valid
1276 result the user should set the global variable @code{errno} to zero
1277 before calling this function.  So one can test for failures after the
1278 call since all failures set @code{errno} to a non-zero value.
1279 @end deftypefun
1280
1281 @comment stdlib.h
1282 @comment GNU
1283 @deftypefun float strtof (const char *@var{string}, char **@var{tailptr})
1284 This function is similar to the @code{strtod} function but it returns a
1285 @code{float} value instead of a @code{double} value.  If the precision
1286 of a @code{float} value is sufficient this function should be used since
1287 it is much faster than @code{strtod} on some architectures.  The reasons
1288 are obvious: @w{IEEE 754} defines @code{float} to have a mantissa of 23
1289 bits while @code{double} has 53 bits and every additional bit of
1290 precision can require additional computation.
1291
1292 If the string has valid syntax for a floating-point number but the value
1293 is not representable because of overflow, @code{strtof} returns either
1294 positive or negative @code{HUGE_VALF} (@pxref{Mathematics}), depending on
1295 the sign of the value.
1296
1297 This function is a GNU extension.
1298 @end deftypefun
1299
1300 @comment stdlib.h
1301 @comment GNU
1302 @deftypefun {long double} strtold (const char *@var{string}, char **@var{tailptr})
1303 This function is similar to the @code{strtod} function but it returns a
1304 @code{long double} value instead of a @code{double} value.  It should be
1305 used when high precision is needed.  On systems which define a @code{long
1306 double} type (i.e., on which it is not the same as @code{double})
1307 running this function might take significantly more time since more bits
1308 of precision are required.
1309
1310 If the string has valid syntax for a floating-point number but the value
1311 is not representable because of overflow, @code{strtold} returns either
1312 positive or negative @code{HUGE_VALL} (@pxref{Mathematics}), depending on
1313 the sign of the value.
1314
1315 This function is a GNU extension.
1316 @end deftypefun
1317
1318 As for the integer parsing functions there are additional functions
1319 which will handle numbers represented using the grouping scheme of the
1320 current locale (@pxref{Parsing of Integers}).
1321
1322 @comment stdlib.h
1323 @comment ISO
1324 @deftypefun double atof (const char *@var{string})
1325 This function is similar to the @code{strtod} function, except that it
1326 need not detect overflow and underflow errors.  The @code{atof} function
1327 is provided mostly for compatibility with existing code; using
1328 @code{strtod} is more robust.
1329 @end deftypefun