e60216ed11d0212e7c95a72b0665b913ff1d7916
[kopensolaris-gnu/glibc.git] / manual / arith.texi
1 @node Arithmetic, Date and Time, Mathematics, Top
2 @chapter Low-Level Arithmetic Functions
3
4 This chapter contains information about functions for doing basic
5 arithmetic operations, such as splitting a float into its integer and
6 fractional parts.  These functions are declared in the header file
7 @file{math.h}.
8
9 @menu
10 * Not a Number::                Making NaNs and testing for NaNs.
11 * Predicates on Floats::        Testing for infinity and for NaNs.
12 * Absolute Value::              Absolute value functions.
13 * Normalization Functions::     Hacks for radix-2 representations.
14 * Rounding and Remainders::     Determinining the integer and
15                                  fractional parts of a float.
16 * Integer Division::            Functions for performing integer
17                                  division.
18 * Parsing of Numbers::          Functions for ``reading'' numbers
19                                  from strings.
20 @end menu
21
22 @node Not a Number
23 @section ``Not a Number'' Values
24 @cindex NaN
25 @cindex not a number
26 @cindex IEEE floating point
27
28 The IEEE floating point format used by most modern computers supports
29 values that are ``not a number''.  These values are called @dfn{NaNs}.
30 ``Not a number'' values result from certain operations which have no
31 meaningful numeric result, such as zero divided by zero or infinity
32 divided by infinity.
33
34 One noteworthy property of NaNs is that they are not equal to
35 themselves.  Thus, @code{x == x} can be 0 if the value of @code{x} is a
36 NaN.  You can use this to test whether a value is a NaN or not: if it is
37 not equal to itself, then it is a NaN.  But the recommended way to test
38 for a NaN is with the @code{isnan} function (@pxref{Predicates on Floats}).
39
40 Almost any arithmetic operation in which one argument is a NaN returns
41 a NaN.
42
43 @comment math.h
44 @comment GNU
45 @deftypevr Macro double NAN
46 An expression representing a value which is ``not a number''.  This
47 macro is a GNU extension, available only on machines that support ``not
48 a number'' values---that is to say, on all machines that support IEEE
49 floating point.
50
51 You can use @samp{#ifdef NAN} to test whether the machine supports
52 NaNs.  (Of course, you must arrange for GNU extensions to be visible,
53 such as by defining @code{_GNU_SOURCE}, and then you must include
54 @file{math.h}.)
55 @end deftypevr
56
57 @node Predicates on Floats
58 @section Predicates on Floats
59
60 @pindex math.h
61 This section describes some miscellaneous test functions on doubles.
62 Prototypes for these functions appear in @file{math.h}.  These are BSD
63 functions, and thus are available if you define @code{_BSD_SOURCE} or
64 @code{_GNU_SOURCE}.
65
66 @comment math.h
67 @comment BSD
68 @deftypefun int isinf (double @var{x})
69 This function returns @code{-1} if @var{x} represents negative infinity,
70 @code{1} if @var{x} represents positive infinity, and @code{0} otherwise.
71 @end deftypefun
72
73 @comment math.h
74 @comment BSD
75 @deftypefun int isnan (double @var{x})
76 This function returns a nonzero value if @var{x} is a ``not a number''
77 value, and zero otherwise.  (You can just as well use @code{@var{x} !=
78 @var{x}} to get the same result).
79 @end deftypefun
80
81 @comment math.h
82 @comment BSD
83 @deftypefun int finite (double @var{x})
84 This function returns a nonzero value if @var{x} is finite or a ``not a
85 number'' value, and zero otherwise.
86 @end deftypefun
87
88 @comment math.h
89 @comment BSD
90 @deftypefun double infnan (int @var{error})
91 This function is provided for compatibility with BSD.  The other
92 mathematical functions use @code{infnan} to decide what to return on
93 occasion of an error.  Its argument is an error code, @code{EDOM} or
94 @code{ERANGE}; @code{infnan} returns a suitable value to indicate this
95 with.  @code{-ERANGE} is also acceptable as an argument, and corresponds
96 to @code{-HUGE_VAL} as a value.
97
98 In the BSD library, on certain machines, @code{infnan} raises a fatal
99 signal in all cases.  The GNU library does not do likewise, because that
100 does not fit the @w{ISO C} specification.
101 @end deftypefun
102
103 @strong{Portability Note:} The functions listed in this section are BSD
104 extensions.
105
106 @node Absolute Value
107 @section Absolute Value
108 @cindex absolute value functions
109
110 These functions are provided for obtaining the @dfn{absolute value} (or
111 @dfn{magnitude}) of a number.  The absolute value of a real number
112 @var{x} is @var{x} is @var{x} is positive, @minus{}@var{x} if @var{x} is
113 negative.  For a complex number @var{z}, whose real part is @var{x} and
114 whose imaginary part is @var{y}, the absolute value is @w{@code{sqrt
115 (@var{x}*@var{x} + @var{y}*@var{y})}}.
116
117 @pindex math.h
118 @pindex stdlib.h
119 Prototypes for @code{abs} and @code{labs} are in @file{stdlib.h};
120 @code{fabs} and @code{cabs} are declared in @file{math.h}.
121
122 @comment stdlib.h
123 @comment ISO
124 @deftypefun int abs (int @var{number})
125 This function returns the absolute value of @var{number}.
126
127 Most computers use a two's complement integer representation, in which
128 the absolute value of @code{INT_MIN} (the smallest possible @code{int})
129 cannot be represented; thus, @w{@code{abs (INT_MIN)}} is not defined.
130 @end deftypefun
131
132 @comment stdlib.h
133 @comment ISO
134 @deftypefun {long int} labs (long int @var{number})
135 This is similar to @code{abs}, except that both the argument and result
136 are of type @code{long int} rather than @code{int}.
137 @end deftypefun
138
139 @comment math.h
140 @comment ISO
141 @deftypefun double fabs (double @var{number})
142 This function returns the absolute value of the floating-point number
143 @var{number}.
144 @end deftypefun
145
146 @comment math.h
147 @comment BSD
148 @deftypefun double cabs (struct @{ double real, imag; @} @var{z})
149 The @code{cabs} function returns the absolute value of the complex
150 number @var{z}, whose real part is @code{@var{z}.real} and whose
151 imaginary part is @code{@var{z}.imag}.  (See also the function
152 @code{hypot} in @ref{Exponents and Logarithms}.)  The value is:
153
154 @smallexample
155 sqrt (@var{z}.real*@var{z}.real + @var{z}.imag*@var{z}.imag)
156 @end smallexample
157 @end deftypefun
158
159 @node Normalization Functions
160 @section Normalization Functions
161 @cindex normalization functions (floating-point)
162
163 The functions described in this section are primarily provided as a way
164 to efficiently perform certain low-level manipulations on floating point
165 numbers that are represented internally using a binary radix;
166 see @ref{Floating Point Concepts}.  These functions are required to
167 have equivalent behavior even if the representation does not use a radix
168 of 2, but of course they are unlikely to be particularly efficient in
169 those cases.
170
171 @pindex math.h
172 All these functions are declared in @file{math.h}.
173
174 @comment math.h
175 @comment ISO
176 @deftypefun double frexp (double @var{value}, int *@var{exponent})
177 The @code{frexp} function is used to split the number @var{value}
178 into a normalized fraction and an exponent.
179
180 If the argument @var{value} is not zero, the return value is @var{value}
181 times a power of two, and is always in the range 1/2 (inclusive) to 1
182 (exclusive).  The corresponding exponent is stored in
183 @code{*@var{exponent}}; the return value multiplied by 2 raised to this
184 exponent equals the original number @var{value}.
185
186 For example, @code{frexp (12.8, &exponent)} returns @code{0.8} and
187 stores @code{4} in @code{exponent}.
188
189 If @var{value} is zero, then the return value is zero and
190 zero is stored in @code{*@var{exponent}}.
191 @end deftypefun
192
193 @comment math.h
194 @comment ISO
195 @deftypefun double ldexp (double @var{value}, int @var{exponent})
196 This function returns the result of multiplying the floating-point
197 number @var{value} by 2 raised to the power @var{exponent}.  (It can
198 be used to reassemble floating-point numbers that were taken apart
199 by @code{frexp}.)
200
201 For example, @code{ldexp (0.8, 4)} returns @code{12.8}.
202 @end deftypefun
203
204 The following functions which come from BSD provide facilities
205 equivalent to those of @code{ldexp} and @code{frexp}:
206
207 @comment math.h
208 @comment BSD
209 @deftypefun double scalb (double @var{value}, int @var{exponent})
210 The @code{scalb} function is the BSD name for @code{ldexp}.
211 @end deftypefun
212
213 @comment math.h
214 @comment BSD
215 @deftypefun double logb (double @var{x})
216 This BSD function returns the integer part of the base-2 logarithm of
217 @var{x}, an integer value represented in type @code{double}.  This is
218 the highest integer power of @code{2} contained in @var{x}.  The sign of
219 @var{x} is ignored.  For example, @code{logb (3.5)} is @code{1.0} and
220 @code{logb (4.0)} is @code{2.0}.
221
222 When @code{2} raised to this power is divided into @var{x}, it gives a
223 quotient between @code{1} (inclusive) and @code{2} (exclusive).
224
225 If @var{x} is zero, the value is minus infinity (if the machine supports
226 such a value), or else a very small number.  If @var{x} is infinity, the
227 value is infinity.
228
229 The value returned by @code{logb} is one less than the value that
230 @code{frexp} would store into @code{*@var{exponent}}.
231 @end deftypefun
232
233 @comment math.h
234 @comment BSD
235 @deftypefun double copysign (double @var{value}, double @var{sign})
236 The @code{copysign} function returns a value whose absolute value is the
237 same as that of @var{value}, and whose sign matches that of @var{sign}.
238 This is a BSD function.
239 @end deftypefun
240
241 @node Rounding and Remainders
242 @section Rounding and Remainder Functions
243 @cindex rounding functions
244 @cindex remainder functions
245 @cindex converting floats to integers
246
247 @pindex math.h
248 The functions listed here perform operations such as rounding,
249 truncation, and remainder in division of floating point numbers.  Some
250 of these functions convert floating point numbers to integer values.
251 They are all declared in @file{math.h}.
252
253 You can also convert floating-point numbers to integers simply by
254 casting them to @code{int}.  This discards the fractional part,
255 effectively rounding towards zero.  However, this only works if the
256 result can actually be represented as an @code{int}---for very large
257 numbers, this is impossible.  The functions listed here return the
258 result as a @code{double} instead to get around this problem.
259
260 @comment math.h
261 @comment ISO
262 @deftypefun double ceil (double @var{x})
263 The @code{ceil} function rounds @var{x} upwards to the nearest integer,
264 returning that value as a @code{double}.  Thus, @code{ceil (1.5)}
265 is @code{2.0}.
266 @end deftypefun
267
268 @comment math.h
269 @comment ISO
270 @deftypefun double floor (double @var{x})
271 The @code{ceil} function rounds @var{x} downwards to the nearest
272 integer, returning that value as a @code{double}.  Thus, @code{floor
273 (1.5)} is @code{1.0} and @code{floor (-1.5)} is @code{-2.0}.
274 @end deftypefun
275
276 @comment math.h
277 @comment BSD
278 @deftypefun double rint (double @var{x})
279 This function rounds @var{x} to an integer value according to the
280 current rounding mode.  @xref{Floating Point Parameters}, for
281 information about the various rounding modes.  The default
282 rounding mode is to round to the nearest integer; some machines
283 support other modes, but round-to-nearest is always used unless
284 you explicit select another.
285 @end deftypefun
286
287 @comment math.h
288 @comment ISO
289 @deftypefun double modf (double @var{value}, double *@var{integer-part})
290 This function breaks the argument @var{value} into an integer part and a
291 fractional part (between @code{-1} and @code{1}, exclusive).  Their sum
292 equals @var{value}.  Each of the parts has the same sign as @var{value},
293 so the rounding of the integer part is towards zero.
294
295 @code{modf} stores the integer part in @code{*@var{integer-part}}, and
296 returns the fractional part.  For example, @code{modf (2.5, &intpart)}
297 returns @code{0.5} and stores @code{2.0} into @code{intpart}.
298 @end deftypefun
299
300 @comment math.h
301 @comment ISO
302 @deftypefun double fmod (double @var{numerator}, double @var{denominator})
303 This function computes the remainder from the division of
304 @var{numerator} by @var{denominator}.  Specifically, the return value is
305 @code{@var{numerator} - @w{@var{n} * @var{denominator}}}, where @var{n}
306 is the quotient of @var{numerator} divided by @var{denominator}, rounded
307 towards zero to an integer.  Thus, @w{@code{fmod (6.5, 2.3)}} returns
308 @code{1.9}, which is @code{6.5} minus @code{4.6}.
309
310 The result has the same sign as the @var{numerator} and has magnitude
311 less than the magnitude of the @var{denominator}.
312
313 If @var{denominator} is zero, @code{fmod} fails and sets @code{errno} to
314 @code{EDOM}.
315 @end deftypefun
316
317 @comment math.h
318 @comment BSD
319 @deftypefun double drem (double @var{numerator}, double @var{denominator})
320 The function @code{drem} is like @code{fmod} except that it rounds the
321 internal quotient @var{n} to the nearest integer instead of towards zero
322 to an integer.  For example, @code{drem (6.5, 2.3)} returns @code{-0.4},
323 which is @code{6.5} minus @code{6.9}.
324
325 The absolute value of the result is less than or equal to half the
326 absolute value of the @var{denominator}.  The difference between
327 @code{fmod (@var{numerator}, @var{denominator})} and @code{drem
328 (@var{numerator}, @var{denominator})} is always either
329 @var{denominator}, minus @var{denominator}, or zero.
330
331 If @var{denominator} is zero, @code{drem} fails and sets @code{errno} to
332 @code{EDOM}.
333 @end deftypefun
334
335
336 @node Integer Division
337 @section Integer Division
338 @cindex integer division functions
339
340 This section describes functions for performing integer division.  These
341 functions are redundant in the GNU C library, since in GNU C the @samp{/}
342 operator always rounds towards zero.  But in other C implementations,
343 @samp{/} may round differently with negative arguments.  @code{div} and
344 @code{ldiv} are useful because they specify how to round the quotient:
345 towards zero.  The remainder has the same sign as the numerator.
346
347 These functions are specified to return a result @var{r} such that the value
348 @code{@var{r}.quot*@var{denominator} + @var{r}.rem} equals
349 @var{numerator}.
350
351 @pindex stdlib.h
352 To use these facilities, you should include the header file
353 @file{stdlib.h} in your program.
354
355 @comment stdlib.h
356 @comment ISO
357 @deftp {Data Type} div_t
358 This is a structure type used to hold the result returned by the @code{div}
359 function.  It has the following members:
360
361 @table @code
362 @item int quot
363 The quotient from the division.
364
365 @item int rem
366 The remainder from the division.
367 @end table
368 @end deftp
369
370 @comment stdlib.h
371 @comment ISO
372 @deftypefun div_t div (int @var{numerator}, int @var{denominator})
373 This function @code{div} computes the quotient and remainder from
374 the division of @var{numerator} by @var{denominator}, returning the
375 result in a structure of type @code{div_t}.
376
377 If the result cannot be represented (as in a division by zero), the
378 behavior is undefined.
379
380 Here is an example, albeit not a very useful one.
381
382 @smallexample
383 div_t result;
384 result = div (20, -6);
385 @end smallexample
386
387 @noindent
388 Now @code{result.quot} is @code{-3} and @code{result.rem} is @code{2}.
389 @end deftypefun
390
391 @comment stdlib.h
392 @comment ISO
393 @deftp {Data Type} ldiv_t
394 This is a structure type used to hold the result returned by the @code{ldiv}
395 function.  It has the following members:
396
397 @table @code
398 @item long int quot
399 The quotient from the division.
400
401 @item long int rem
402 The remainder from the division.
403 @end table
404
405 (This is identical to @code{div_t} except that the components are of
406 type @code{long int} rather than @code{int}.)
407 @end deftp
408
409 @comment stdlib.h
410 @comment ISO
411 @deftypefun ldiv_t ldiv (long int @var{numerator}, long int @var{denominator})
412 The @code{ldiv} function is similar to @code{div}, except that the
413 arguments are of type @code{long int} and the result is returned as a
414 structure of type @code{ldiv}.
415 @end deftypefun
416
417
418 @node Parsing of Numbers
419 @section Parsing of Numbers
420 @cindex parsing numbers (in formatted input)
421 @cindex converting strings to numbers
422 @cindex number syntax, parsing
423 @cindex syntax, for reading numbers
424
425 This section describes functions for ``reading'' integer and
426 floating-point numbers from a string.  It may be more convenient in some
427 cases to use @code{sscanf} or one of the related functions; see
428 @ref{Formatted Input}.  But often you can make a program more robust by
429 finding the tokens in the string by hand, then converting the numbers
430 one by one.
431
432 @menu
433 * Parsing of Integers::         Functions for conversion of integer values.
434 * Parsing of Floats::           Functions for conversion of floating-point
435                                  values.
436 @end menu
437
438 @node Parsing of Integers
439 @subsection Parsing of Integers
440
441 @pindex stdlib.h
442 These functions are declared in @file{stdlib.h}.
443
444 @comment stdlib.h
445 @comment ISO
446 @deftypefun {long int} strtol (const char *@var{string}, char **@var{tailptr}, int @var{base})
447 The @code{strtol} (``string-to-long'') function converts the initial
448 part of @var{string} to a signed integer, which is returned as a value
449 of type @code{long int}.
450
451 This function attempts to decompose @var{string} as follows:
452
453 @itemize @bullet
454 @item
455 A (possibly empty) sequence of whitespace characters.  Which characters
456 are whitespace is determined by the @code{isspace} function
457 (@pxref{Classification of Characters}).  These are discarded.
458
459 @item
460 An optional plus or minus sign (@samp{+} or @samp{-}).
461
462 @item
463 A nonempty sequence of digits in the radix specified by @var{base}.
464
465 If @var{base} is zero, decimal radix is assumed unless the series of
466 digits begins with @samp{0} (specifying octal radix), or @samp{0x} or
467 @samp{0X} (specifying hexadecimal radix); in other words, the same
468 syntax used for integer constants in C.
469
470 Otherwise @var{base} must have a value between @code{2} and @code{35}.
471 If @var{base} is @code{16}, the digits may optionally be preceded by
472 @samp{0x} or @samp{0X}.  If base has no legal value the value returned
473 is @code{0l} and the global variable @code{errno} is set to @code{EINVAL}.
474
475 @item
476 Any remaining characters in the string.  If @var{tailptr} is not a null
477 pointer, @code{strtol} stores a pointer to this tail in
478 @code{*@var{tailptr}}.
479 @end itemize
480
481 If the string is empty, contains only whitespace, or does not contain an
482 initial substring that has the expected syntax for an integer in the
483 specified @var{base}, no conversion is performed.  In this case,
484 @code{strtol} returns a value of zero and the value stored in
485 @code{*@var{tailptr}} is the value of @var{string}.
486
487 In a locale other than the standard @code{"C"} locale, this function
488 may recognize additional implementation-dependent syntax.
489
490 If the string has valid syntax for an integer but the value is not
491 representable because of overflow, @code{strtol} returns either
492 @code{LONG_MAX} or @code{LONG_MIN} (@pxref{Range of Type}), as
493 appropriate for the sign of the value.  It also sets @code{errno}
494 to @code{ERANGE} to indicate there was overflow.
495
496 Because the value @code{0l} is a correct result for @code{strtol} the
497 user who is interested in handling errors should set the global variable
498 @code{errno} to @code{0} before calling this function.  So it can be
499 tested whether an error occured or not.
500
501 There is an example at the end of this section.
502 @end deftypefun
503
504 @comment stdlib.h
505 @comment ISO
506 @deftypefun {unsigned long int} strtoul (const char *@var{string}, char **@var{tailptr}, int @var{base})
507 The @code{strtoul} (``string-to-unsigned-long'') function is like
508 @code{strtol} except it deals with unsigned numbers, and returns its
509 value with type @code{unsigned long int}.  No @samp{+} or @samp{-} sign
510 may appear before the number, but the syntax is otherwise the same as
511 described above for @code{strtol}.  The value returned in case of
512 overflow is @code{ULONG_MAX} (@pxref{Range of Type}).
513
514 Like @code{strtol} this function sets @code{errno} and returns the value
515 @code{0ul} in case the value for @var{base} is not in the legal range.
516 For @code{strtoul} this can happen in another situation.  In case the
517 number to be converted is negative @code{strtoul} also sets @code{errno}
518 to @code{EINVAL} and returns @code{0ul}.
519 @end deftypefun
520
521 @comment stdlib.h
522 @comment BSD
523 @deftypefun {long long int} strtoq (const char *@var{string}, char **@var{tailptr}, int @var{base})
524 The @code{strtoq} (``string-to-quad-word'') function is like
525 @code{strtol} except that is deals with extra long numbers and it
526 returns its value with type @code{long long int}.
527
528 If the string has valid syntax for an integer but the value is not
529 representable because of overflow, @code{strtoq} returns either
530 @code{LONG_LONG_MAX} or @code{LONG_LONG_MIN} (@pxref{Range of Type}), as
531 appropriate for the sign of the value.  It also sets @code{errno} to
532 @code{ERANGE} to indicate there was overflow.
533 @end deftypefun
534
535 @comment stdlib.h
536 @comment GNU
537 @deftypefun {long long int} strtoll (const char *@var{string}, char **@var{tailptr}, int @var{base})
538 @code{strtoll} is only an commonly used other name for the @code{strtoq}
539 function.  Everything said for @code{strtoq} applies to @code{strtoll}
540 as well.
541 @end deftypefun
542
543 @comment stdlib.h
544 @comment BSD
545 @deftypefun {unsigned long long int} strtouq (const char *@var{string}, char **@var{tailptr}, int @var{base})
546 The @code{strtouq} (``string-to-unsigned-quad-word'') function is like
547 @code{strtoul} except that is deals with extra long numbers and it
548 returns its value with type @code{unsigned long long int}.  The value
549 returned in case of overflow is @code{ULONG_LONG_MAX} (@pxref{Range of Type}).
550 @end deftypefun
551
552 @comment stdlib.h
553 @comment GNU
554 @deftypefun {unsigned long long int} strtoull (const char *@var{string}, char **@var{tailptr}, int @var{base})
555 @code{strtoull} is only an commonly used other name for the @code{strtouq}
556 function.  Everything said for @code{strtouq} applies to @code{strtoull}
557 as well.
558 @end deftypefun
559
560 @comment stdlib.h
561 @comment ISO
562 @deftypefun {long int} atol (const char *@var{string})
563 This function is similar to the @code{strtol} function with a @var{base}
564 argument of @code{10}, except that it need not detect overflow errors.
565 The @code{atol} function is provided mostly for compatibility with
566 existing code; using @code{strtol} is more robust.
567 @end deftypefun
568
569 @comment stdlib.h
570 @comment ISO
571 @deftypefun int atoi (const char *@var{string})
572 This function is like @code{atol}, except that it returns an @code{int}
573 value rather than @code{long int}.  The @code{atoi} function is also
574 considered obsolete; use @code{strtol} instead.
575 @end deftypefun
576
577 The POSIX locales contain some information about how to format numbers
578 (@pxref{General Numeric}).  This mainly deals with representing numbers
579 for better readability for humans.  The functions present so far in this
580 section cannot handle numbers in this form.
581
582 If this functionality is needed in a program one can use the functions
583 from the @code{scanf} family which know about the flag @samp{'} for
584 parsing numeric input (@pxref{Numeric Input Conversions}).  Sometimes it
585 is more desirable to have finer control.
586
587 In these situation one could use the function
588 @code{__strto@var{XXX}_internal}.  @var{XXX} here stands for any of the
589 above forms.  All numeric conversion functions (including the functions
590 to process floating-point numbers) have such a counterpart.  The
591 difference to the normal form is the extra argument at the end of the
592 parameter list.  If this value has an non-zero value the handling of
593 number grouping is enabled.  The advantage of using these functions is
594 that the @var{tailptr} parameters allow to determine which part of the
595 input is processed.  The @code{scanf} functions don't provide this
596 information.  The drawback of using these functions is that they are not
597 portable.  They only exist in the GNU C library.
598
599
600 Here is a function which parses a string as a sequence of integers and
601 returns the sum of them:
602
603 @smallexample
604 int
605 sum_ints_from_string (char *string)
606 @{
607   int sum = 0;
608
609   while (1) @{
610     char *tail;
611     int next;
612
613     /* @r{Skip whitespace by hand, to detect the end.}  */
614     while (isspace (*string)) string++;
615     if (*string == 0)
616       break;
617
618     /* @r{There is more nonwhitespace,}  */
619     /* @r{so it ought to be another number.}  */
620     errno = 0;
621     /* @r{Parse it.}  */
622     next = strtol (string, &tail, 0);
623     /* @r{Add it in, if not overflow.}  */
624     if (errno)
625       printf ("Overflow\n");
626     else
627       sum += next;
628     /* @r{Advance past it.}  */
629     string = tail;
630   @}
631
632   return sum;
633 @}
634 @end smallexample
635
636 @node Parsing of Floats
637 @subsection Parsing of Floats
638
639 @pindex stdlib.h
640 These functions are declared in @file{stdlib.h}.
641
642 @comment stdlib.h
643 @comment ISO
644 @deftypefun double strtod (const char *@var{string}, char **@var{tailptr})
645 The @code{strtod} (``string-to-double'') function converts the initial
646 part of @var{string} to a floating-point number, which is returned as a
647 value of type @code{double}.
648
649 This function attempts to decompose @var{string} as follows:
650
651 @itemize @bullet
652 @item
653 A (possibly empty) sequence of whitespace characters.  Which characters
654 are whitespace is determined by the @code{isspace} function
655 (@pxref{Classification of Characters}).  These are discarded.
656
657 @item
658 An optional plus or minus sign (@samp{+} or @samp{-}).
659
660 @item
661 A nonempty sequence of digits optionally containing a decimal-point
662 character---normally @samp{.}, but it depends on the locale
663 (@pxref{Numeric Formatting}).
664
665 @item
666 An optional exponent part, consisting of a character @samp{e} or
667 @samp{E}, an optional sign, and a sequence of digits.
668
669 @item
670 Any remaining characters in the string.  If @var{tailptr} is not a null
671 pointer, a pointer to this tail of the string is stored in
672 @code{*@var{tailptr}}.
673 @end itemize
674
675 If the string is empty, contains only whitespace, or does not contain an
676 initial substring that has the expected syntax for a floating-point
677 number, no conversion is performed.  In this case, @code{strtod} returns
678 a value of zero and the value returned in @code{*@var{tailptr}} is the
679 value of @var{string}.
680
681 In a locale other than the standard @code{"C"} or @code{"POSIX"} locales,
682 this function may recognize additional locale-dependent syntax.
683
684 If the string has valid syntax for a floating-point number but the value
685 is not representable because of overflow, @code{strtod} returns either
686 positive or negative @code{HUGE_VAL} (@pxref{Mathematics}), depending on
687 the sign of the value.  Similarly, if the value is not representable
688 because of underflow, @code{strtod} returns zero.  It also sets @code{errno}
689 to @code{ERANGE} if there was overflow or underflow.
690
691 Since the value zero which is returned in the error case is also a valid
692 result the user should set the global variable @code{errno} to zero
693 before calling this function.  So one can test for failures after the
694 call since all failures set @code{errno} to a non-zero value.
695 @end deftypefun
696
697 @comment stdlib.h
698 @comment GNU
699 @deftypefun float strtof (const char *@var{string}, char **@var{tailptr})
700 This function is similar to the @code{strtod} function but it returns a
701 @code{float} value instead of a @code{double} value.  If the precision
702 of a @code{float} value is sufficent this function should be used since
703 it is much faster than @code{strtod} on some architectures.  The reasons
704 are obvious: @w{IEEE 754} defines @code{float} to have a mantissa of 23
705 bits while @code{double} has 53 bits and every additional bit of
706 precision can require additional computation.
707
708 If the string has valid syntax for a floating-point number but the value
709 is not representable because of overflow, @code{strtof} returns either
710 positive or negative @code{HUGE_VALf} (@pxref{Mathematics}), depending on
711 the sign of the value.
712
713 This function is a GNU extension.
714 @end deftypefun
715
716 @comment stdlib.h
717 @comment GNU
718 @deftypefun {long double} strtold (const char *@var{string}, char **@var{tailptr})
719 This function is similar to the @code{strtod} function but it returns a
720 @code{long double} value instead of a @code{double} value.  It should be
721 used when high presision is used.  On systems which define a @code{long
722 double} type (i.e., on which it is not the same as @code{double})
723 running this function might take significently more time since more bits
724 of precision are required.
725
726 If the string has valid syntax for a floating-point number but the value
727 is not representable because of overflow, @code{strtold} returns either
728 positive or negative @code{HUGE_VALl} (@pxref{Mathematics}), depending on
729 the sign of the value.
730
731 This function is a GNU extension.
732 @end deftypefun
733
734 As for the integer parsing functions there are additional functions
735 which will handle numbers represented using the grouping scheme of the
736 current locale (@pxref{Parsing of Integers}).
737
738 @comment stdlib.h
739 @comment ISO
740 @deftypefun double atof (const char *@var{string})
741 This function is similar to the @code{strtod} function, except that it
742 need not detect overflow and underflow errors.  The @code{atof} function
743 is provided mostly for compatibility with existing code; using
744 @code{strtod} is more robust.
745 @end deftypefun