Fixed some formatting and indexing problems.
[kopensolaris-gnu/glibc.git] / manual / math.texi
1 @node Mathematics
2 @chapter Mathematics
3
4 This chapter contains information about functions for performing
5 mathematical computations, such as trigonometric functions.  Most
6 of these functions have prototypes declared in the header file
7 @file{math.h}.
8 @pindex math.h
9
10 @strong{Incomplete:}  This chapter doesn't have any examples.
11
12 @menu
13 * Domain and Range Errors::             How overflow conditions and the like
14                                          are reported.
15 * Trigonometric Functions::             Sine, cosine, and tangent.
16 * Inverse Trigonometric Functions::     Arc sine, arc cosine, and arc tangent.
17 * Exponentiation and Logarithms::       Also includes square root.
18 * Hyperbolic Functions::                Hyperbolic sine and friends.
19 * Normalization Functions::             Hacks for radix-2 representations.
20 * Rounding and Remainder Functions::    Determinining the integer and
21                                          fractional parts of a float.
22 * Pseudo-Random Numbers::               Functions for generating pseudo-random
23                                          numbers.
24 * Integer Division::                    Functions for performing integer
25                                          division.
26 * Absolute Value::                      Absolute value functions.
27 * Predicates on Floats::                Some miscellaneous test functions.
28 * Parsing of Numbers::                  Functions for ``reading'' numbers
29                                          from strings.
30 @end menu
31
32 @node Domain and Range Errors
33 @section Domain and Range Errors
34
35 @cindex domain error
36 Many of the functions listed in this chapter are defined mathematically
37 over a domain that is only a subset of real numbers.  For example, the
38 @code{acos} function is defined over the domain between @code{-1} and
39 @code{1}.  If you pass an argument to one of these functions that is
40 outside the domain over which it is defined, the function returns
41 an unspecified value and sets @code{errno} to @code{EDOM} to indicate
42 a @dfn{domain error}.
43
44 Some of these functions are defined mathematically to result in a
45 complex value over parts of their domains.  The most familiar example of
46 this is taking the square root of a negative number.  Since the C
47 language has no support for complex numbers, this is treated like a
48 domain error.
49
50 @cindex range error
51 A related problem is that the mathematical result of a function may not
52 be representable as a floating point number.  If magnitude of the result
53 is too large to be represented, the value of the macro @code{HUGE_VAL}
54 is returned (with the appropriate sign), and @code{errno} is set to
55 @code{ERANGE} to indicate a @dfn{range error}.  If the magnitude of the
56 result is too small, a value of zero is returned instead.  In the case
57 of underflow, @code{errno} might or might not be set to @code{ERANGE}.
58
59 None of these functions ever generate externally visible exceptions
60 as a result of domain or range errors.  In particular, this means that
61 you won't see @code{SIGFPE} signals generated within these functions.
62 @xref{Signal Handling}, for more information about signals.
63
64 All of the functions that operate on floating-point numbers accept
65 arguments and return results of type @code{double}.  In future revisions
66 of the ANSI C standard, additional functions may be added that operate
67 on @code{float} and @code{long double} values.  For example, @code{cosf}
68 and @code{cosl} would be versions of the @code{cos} function that
69 operate on @code{float} and @code{long double} arguments, respectively.
70 In the meantime, you should avoid using these names yourself.
71 @xref{Reserved Names}.
72
73 @comment math.h
74 @comment ANSI
75 @defvr Macro HUGE_VAL
76 This macro expands into a (possibly non-constant) expression of type
77 @code{double} representing a very large positive number.  This is
78 typically either the largest representable floating-point number, or a
79 value indicating infinity if the floating-point representation has one.
80 (The IEEE floating-point does have such a reserved value.)
81
82 The value of this macro is used as the return value from various 
83 mathematical functions in overflow situations.
84 @end defvr
85
86 For more information about floating-point representations and limits,
87 @xref{Floating-Point Limits}.  In particular, the macro @code{DBL_MAX}
88 might be more appropriate than @code{HUGE_VAL} for many uses.
89
90
91 @node Trigonometric Functions
92 @section Trigonometric Functions
93
94 @strong{Incomplete:}  What font convention should be used for things
95 like ``pi'' and ``e''?
96
97 These are the familiar @code{sin}, @code{cos}, and @code{tan} functions.
98 The arguments to all of these functions are specified in radians; recall
99 that pi radians is equivalent to 180 degrees.  
100
101 @cindex pi (trigonometric constant)
102 The math library doesn't define a symbolic constant for pi, but you can
103 define your own if you need one:
104
105 @example
106 #define PI 3.14159265358979323846264338327
107 @end example
108
109 @noindent
110 You can also compute the value of pi with the expression @samp{acos (-1.0)}.
111
112
113 @comment math.h
114 @comment ANSI
115 @deftypefun double sin (double @var{x})
116 This function returns the sine of @var{x}, which is given in radians.
117 The return value is in the range @code{-1} to @code{1}.
118 @end deftypefun
119
120 @comment math.h
121 @comment ANSI
122 @deftypefun double cos (double @var{x})
123 This function returns the cosine of @var{x}, which is given in radians.
124 The return value is in the range @code{-1} to @code{1}.
125 @end deftypefun
126
127 @comment math.h
128 @comment ANSI
129 @deftypefun double tan (double @var{x})
130 This function returns the tangent of @var{x}, which is given in radians.
131
132 The following @code{errno} error conditions are defined for this function:
133
134 @table @code
135 @item ERANGE
136 Mathematically, the tangent function has singularities at odd multiples of
137 pi/2.  If the argument @var{x} is too close to one of these singularities,
138 @code{tan} sets this error condition and returns either positive or
139 negative @code{HUGE_VAL}.
140 @end table
141 @end deftypefun
142
143
144 @node Inverse Trigonometric Functions
145 @section Inverse Trigonometric Functions
146
147 These are the usual arc sine, arc cosine, and arc tangent functions.
148
149 @comment math.h
150 @comment ANSI
151 @deftypefun double asin (double @var{x})
152 This function computes the arc sine of @var{x}.  The return value is
153 given in radians and is in the range -pi/2 to pi/2 (inclusive).
154
155 The following @code{errno} error conditions are defined for this function:
156
157 @table @code
158 @item EDOM
159 The argument @var{x} is out of range.  The arc sine function is defined
160 mathematically only over the domain -1 to 1.
161 @end table
162 @end deftypefun
163
164 @comment math.h
165 @comment ANSI
166 @deftypefun double acos (double @var{x})
167 This function computes the arc cosine of @var{x}.  The return value is
168 given in radians and is in the range 0 to pi (inclusive).
169
170 The following @code{errno} error conditions are defined for this function:
171
172 @table @code
173 @item EDOM
174 The argument @var{x} is out of range.  The arc cosine function is defined
175 mathematically only over the domain -1 to 1.
176 @end table
177 @end deftypefun
178
179
180 @comment math.h
181 @comment ANSI
182 @deftypefun double atan (double @var{x})
183 This function returns the arc tangent of @var{x}.  The return value is
184 given in radians and is in the range -pi/2 to pi/2 (inclusive).
185 @end deftypefun
186
187 @comment math.h
188 @comment ANSI
189 @deftypefun double atan2 (double @var{y}, double @var{x})
190 This is the two argument arc tangent function.  It is similar to computing
191 the arc tangent of @var{y}/@var{x}, except that the signs of both arguments
192 are used to determine the quadrant of the result, and @var{x} is
193 permitted to be zero.  The return value is given in radians and is in
194 the range -pi to pi (inclusive).
195
196 The following @code{errno} error conditions are defined for this function:
197
198 @table @code
199 @item EDOM
200 Both the @var{x} and @var{y} arguments are zero; the value of the
201 function is not defined in this case.
202 @end table
203 @end deftypefun
204
205
206 @node Exponentiation and Logarithms
207 @section Exponentiation and Logarithms
208
209 @comment math.h
210 @comment ANSI
211 @deftypefun double exp (double @var{x})
212 The @code{exp} function returns the value of e (the base of natural
213 logarithms) raised to power @var{x}.
214
215 The following @code{errno} error conditions are defined for this function:
216
217 @table @code
218 @item ERANGE
219 The magnitude of the result is too large to be representable.
220 @end table
221 @end deftypefun
222
223 @comment math.h
224 @comment ANSI
225 @deftypefun double log (double @var{x})
226 This function returns the natural logarithm of @var{x}.
227
228 The following @code{errno} error conditions are defined for this function:
229
230 @table @code
231 @item EDOM
232 The log function is defined mathematically to return a non-complex
233 result only on positive arguments.  This error is used to report a
234 negative argument @var{x}.
235
236 @item ERANGE
237 The result of the function on an argument of zero is not defined.
238 @end table
239 @end deftypefun
240
241 @comment math.h
242 @comment ANSI
243 @deftypefun double log10 (double @var{x})
244 This function returns the base-10 logarithm of @var{x}.  Except for the
245 different base, it is similar to the @code{log} function.
246 @end deftypefun
247
248 @comment math.h
249 @comment ANSI
250 @deftypefun double pow (double @var{base}, double @var{power})
251 This is a general exponentiation function, returning @var{base} raised
252 to @var{power}.
253
254 The following @code{errno} error conditions are defined for this function:
255
256 @table @code
257 @item EDOM
258 The argument @var{base} is negative and @var{power} is not an integral
259 value.  Mathematically, the result would be a complex number in this case.
260
261 @item ERANGE
262 An underflow or overflow condition was detected in the result.
263 @end table
264 @end deftypefun
265
266 @comment math.h
267 @comment ANSI
268 @deftypefun double sqrt (double @var{x})
269 This function returns the nonnegative square root of @var{x}.
270
271 The following @code{errno} error conditions are defined for this function:
272
273 @table @code
274 @item EDOM
275 The argument @var{x} is negative.  Mathematically, the square root would
276 be a complex number.
277 @end table
278 @end deftypefun
279
280 @comment math.h
281 @comment GNU
282 @deftypefun double cbrt (double @var{x})
283 This function returns the cube root of @var{x}.
284 @end deftypefun
285
286 @comment math.h
287 @comment GNU
288 @deftypefun double hypot (double @var{x}, double @var{y})
289 The @code{hypot} function returns @code{sqrt (@var{x}*@var{x} +
290 @var{y}*@var{y})}.  (This is the length of the hypotenuse of a right
291 triangle with sides of length @var{x} and @var{y}, or the distance
292 of the point (@var{x}, @var{y}) from the origin.)
293 @end deftypefun
294
295 @comment math.h
296 @comment GNU
297 @deftypefun double cabs (struct @{ double x, y; @} @var{z})
298 The @code{cabs} function is similar to @code{hypot}, but the argument
299 is specified as a @code{struct} representing a complex number.
300 @end deftypefun
301
302
303 @comment math.h
304 @comment GNU
305 @deftypefun double expm1 (double @var{x})
306 This function returns a value equivalent to @code{exp (@var{x}) - 1}.
307 It is computed in a way that is accurate even if the value of @var{x}
308 is very small.
309 @end deftypefun
310
311
312 @comment math.h
313 @comment GNU
314 @deftypefun double log1p (double @var{x})
315 This function returns a value equivalent to @code{log (1 + @var{x})}.
316 It is computed in a way that is accurate even if the value of @var{x}
317 is very small.
318 @end deftypefun
319
320
321
322 @node Hyperbolic Functions
323 @section Hyperbolic Functions
324
325 The functions in this section are related to the exponential and
326 functions; @pxref{Exponentiation and Logarithms}.
327
328 @comment math.h
329 @comment ANSI
330 @deftypefun double sinh (double @var{x})
331 The @code{sinh} function returns the hyperbolic sine of @var{x}.  The
332 following @code{errno} error conditions are defined for this function:
333
334 @table @code
335 @item ERANGE
336 The value of the argument @var{x} is too large; an overflow condition
337 was detected.
338 @end table
339 @end deftypefun
340
341 @comment math.h
342 @comment ANSI
343 @deftypefun double cosh (double @var{x})
344 The @code{cosh} function returns the hyperbolic cosine of @var{x}.  The
345 following @code{errno} error conditions are defined for this function:
346
347 @table @code
348 @item ERANGE
349 The value of the argument @var{x} is too large; an overflow condition
350 was detected.
351 @end table
352 @end deftypefun
353
354 @comment math.h
355 @comment ANSI
356 @deftypefun double tanh (double @var{x})
357 This function returns the hyperbolic tangent of @var{x}.
358 @end deftypefun
359
360 @comment math.h
361 @comment GNU
362 @deftypefun double asinh (double @var{x})
363 This function returns the inverse hyperbolic cosine of @var{x}.
364 @end deftypefun
365
366 @comment math.h
367 @comment GNU
368 @deftypefun double acosh (double @var{x})
369 This function returns the inverse hyperbolic cosine of @var{x}.  If
370 the argument is less than @code{1}, @code{acosh} returns @code{HUGE_VAL}.
371 @end deftypefun
372
373 @comment math.h
374 @comment GNU
375 @deftypefun double atanh (double @var{x})
376 This function returns the inverse hyperbolic cosine of @var{x}.  If
377 the absolute value of the argument is greater than or equal to @code{1},
378 @code{atanh} returns @code{HUGE_VAL}.
379 @end deftypefun
380
381
382 @node Normalization Functions
383 @section Normalization Functions
384
385 The functions described in this section are primarily provided as a way
386 to efficiently perform certain low-level manipulations on floating point
387 numbers that are represented internally using a binary radix;
388 @pxref{Floating-Point Representation}.  These functions are required to
389 have equivalent behavior even if the representation does not use a radix
390 of 2, but of course they are unlikely to be particularly efficient in
391 those cases.
392
393 @comment math.h
394 @comment GNU
395 @deftypefun double copysign (double @var{value}, double @var{sign})
396 The @code{copysign} function returns a value whose absolute value is the
397 same as that of @var{value}, and whose sign matches that of @var{sign}.
398 @end deftypefun
399
400 @comment math.h
401 @comment ANSI
402 @deftypefun double frexp (double @var{value}, int *@var{exponent})
403 The @code{frexp} function is used to normalize the number @var{value}.
404
405 If the argument @var{value} is not zero, the return value is a
406 floating-point number with magnitude in the range 1/2 (inclusive) to 1
407 (exclusive).  The corresponding exponent is stored in the location
408 pointed at by @var{exponent}; the return value multiplied by 2 raised to
409 this exponent is equal to the original number @var{value}.
410
411 If @var{value} is zero, then both parts of the result are zero.
412 @end deftypefun
413
414 @comment math.h
415 @comment ANSI
416 @deftypefun double ldexp (double @var{value}, int @var{exponent})
417 This function returns the result of multiplying the floating-point
418 number @var{value} by 2 raised to the power @var{exponent}.  (It can
419 be used to reassemble floating-point numbers that were taken apart
420 by @code{frexp}.)
421 @end deftypefun
422
423 @comment math.h
424 @comment GNU
425 @deftypefun double scalb (double @var{value}, int @var{exponent})
426 The @code{scalb} function does the same thing as @code{ldexp}.
427 @end deftypefun
428
429 @comment math.h
430 @comment GNU
431 @deftypefun double logb (double @var{x})
432 This function returns the base-2 exponent of @var{x}, an integer value
433 converted to a @code{double}.  The return value is such that dividing
434 the absolute value of @var{x} by @code{2} raised to this power is
435 greater than or equal to @code{1}, but less than @code{2}.
436
437 @strong{Incomplete:}  What happens if @var{x} is zero?
438 @end deftypefun
439
440
441 @node Rounding and Remainder Functions
442 @section Rounding and Remainder Functions
443
444 The functions listed here perform operations such as rounding, 
445 truncation, and remainder computation.
446
447 You can also convert floating-point numbers to integers simply by
448 casting them to @code{int}.  This discards the fractional part,
449 effectively rounding towards zero.  However, this only works if the
450 result can actually be represented as an @code{int} --- for very large
451 numbers, the result is undefined.  The functions listed here return the
452 result as a @code{double} instead to get around this problem.
453
454 @comment math.h
455 @comment ANSI
456 @deftypefun double ceil (double @var{x})
457 The @code{ceil} function rounds @var{x} upwards to the nearest integer,
458 returning that value as a @code{double}.
459 @end deftypefun
460
461 @comment math.h
462 @comment ANSI
463 @deftypefun double floor (double @var{x})
464 The @code{ceil} function rounds @var{x} downwards to the nearest
465 integer, returning that value as a @code{double}.
466 @end deftypefun
467
468 @comment math.h
469 @comment GNU
470 @deftypefun double rint (double @var{x})
471 This function returns the integer nearest @var{x} according to the
472 current rounding mode.  @xref{Floating-Point Parameters}, for information
473 about the @code{FLT_ROUNDS} macro.
474 @end deftypefun
475
476 @comment math.h
477 @comment ANSI
478 @deftypefun double modf (double @var{value}, double *@var{integer_part})
479 This function breaks the argument @var{value} into an integer part and a
480 fractional part.  Each of the parts has the same sign as the original
481 @var{value}, so the rounding of the integer part is towards zero.  The
482 integer part is stored at the location pointed at by @var{integer_part},
483 and the fractional part is returned.
484 @end deftypefun
485
486
487 @comment math.h
488 @comment ANSI
489 @deftypefun double fmod (double @var{numerator}, double @var{denominator})
490 This function computes the remainder from dividing @var{numerator} by
491 @var{denominator}.  The result has the same sign as the @var{numerator}
492 and has magnitude less than the magnitude of the @var{denominator}.
493 (Recall that the built-in @samp{%} operator isn't defined on
494 floating-point values.)
495
496 The following @code{errno} error conditions are defined for this function:
497
498 @table @code
499 @item EDOM
500 The @var{denominator} is zero.
501 @end table
502 @end deftypefun
503
504 @comment math.h
505 @comment GNU
506 @deftypefun double drem (double @var{numerator}, double @var{denominator})
507 This function returns the remainder from dividing @var{numerator} by
508 @var{denominator}.  Specifically, the return value is @code{@var{numerator}
509 - @var{n} * @var{denominator}}, where @var{n} is the integer closest to
510 the exact quotient of @var{numerator} and @var{denominator}.  The absolute
511 value of the result is less than or equal to one half the absolute value
512 of the @var{denominator}.
513
514 The following @code{errno} error conditions are defined for this function:
515
516 @table @code
517 @item EDOM
518 The @var{denominator} is zero.
519 @end table
520 @end deftypefun
521
522
523 @node Pseudo-Random Numbers
524 @section Pseudo-Random Numbers
525
526 This section describes the GNU facilities for generating a series of
527 pseudo-random numbers.  The numbers generated are not necessarily truly
528 random; typically, the sequences repeat periodically, with the period
529 being a function of the number of bits in the @dfn{seed} or initial
530 state.
531 @cindex random numbers
532 @cindex pseudo-random numbers
533 @cindex seed (for random numbers)
534
535 There are actually two sets of random number functions provided.
536
537 @itemize @bullet
538 @item 
539 The @code{rand} and @code{srand} functions, described in @ref{ANSI C
540 Random Number Functions}, are part of the ANSI C standard.  You can use
541 these functions portably in many C implementations.
542
543 @item 
544 The @code{random} and @code{srandom} functions, described in @ref{BSD
545 Random Number Functions}, are derived from BSD Unix.  This uses a better
546 random number generator (producing numbers that are more random), but
547 is less portable.
548 @end itemize
549
550 For both sets of functions, you can get repeatable sequences of numbers
551 within a single implementation on a single machine type by specifying
552 the same initial seed value for the random number generator.  However,
553 the actual algorithm used to generate the random number series may be
554 implementation-dependent or implementation-dependent.
555
556
557 @menu
558 * ANSI C Random Number Functions::      @code{rand} and friends.
559 * BSD Random Number Functions::         @code{random} and friends.
560 @end menu
561
562 @node ANSI C Random Number Functions
563 @subsection ANSI C Random Number Functions
564
565 This section describes the random number functions that are part of
566 the ANSI C standard.  These functions represent the state of the
567 random number generator as an @code{int}.
568
569 To use these facilities, you should include the header file
570 @file{stdlib.h} in your program.
571 @pindex stdlib.h
572
573 @comment stdlib.h
574 @comment ANSI
575 @defvr Macro RAND_MAX
576 The value of this macro is an integer constant expression that
577 represents the maximum possible value returned by the @code{rand}
578 function.  It is guaranteed to be at least @code{32767}.
579 @end defvr
580
581 @comment stdlib.h
582 @comment ANSI
583 @deftypefun int rand (void)
584 The @code{rand} function returns the next pseudo-random number in the
585 series.  The value is in the range from @code{0} to @code{RAND_MAX}.
586 @end deftypefun
587
588 @comment stdlib.h
589 @comment ANSI
590 @deftypefun void srand (unsigned int @var{seed})
591 This function establishes @var{seed} as the seed for a new series of
592 pseudo-random numbers.  If @code{rand} is called before a seed has been
593 established with @code{srand}, it is equivalent to having specified an
594 initial seed value of @code{1}.
595 @end deftypefun
596
597 @node BSD Random Number Functions
598 @subsection BSD Random Number Functions
599
600 This section describes a set of random number generation functions
601 that are derived from BSD Unix.  The @code{random} function can generate
602 better random numbers than @code{rand}, because it maintains more bits
603 of internal state.
604
605 The prototypes for these functions are in @file{stdlib.h}.
606 @pindex stdlib.h
607
608 @comment stdlib.h
609 @comment BSD
610 @deftypefun long int random (void)
611 This function returns the next pseudo-random number in the sequence.
612 The range of values returned is from @code{0} to @code{RAND_MAX}.
613 @end deftypefun
614
615 @comment stdlib.h
616 @comment BSD
617 @deftypefun void srandom (unsigned int @var{seed})
618 The @code{srandom} function sets the seed for the current random number
619 state to @var{seed}.  If you supply a @var{seed} value of @code{1}, this
620 will cause @code{random} to reproduce the default set of random numbers.
621 @end deftypefun
622
623 Because this random number generator uses more state information than
624 will fit in an @code{int}, @code{srandom} does not return a value that
625 is useful for saving and restoring the random number state.  Instead,
626 you should use the @code{initstate} and @code{setstate} functions to do
627 this.
628
629 @comment stdlib.h
630 @comment BSD
631 @deftypefun {void *} initstate (unsigned int @var{seed}, void *@var{state}, size_t @var{size})
632 The @code{initstate} function is used to initialize the random number
633 generator state.  The @var{state} is an array of @var{size} bytes, used to
634 hold the state information.  The size must be at least 8 bytes, and optimal
635 sizes are 8, 16, 32, 64, 128, and 256.  The bigger the @var{state} array,
636 the better.
637
638 The return value is the previous value of the state information array.
639 @end deftypefun
640
641 @comment stdlib.h
642 @comment BSD
643 @deftypefun {void *} setstate (void *@var{state})
644 The @code{setstate} function restores the random number state
645 information @var{state}.  The argument must have been the result of
646 a previous call to @var{initstate} or @var{setstate}.  
647
648 The return value is the previous value of the state information array.
649 @end deftypefun
650
651
652
653
654
655 @node Integer Division
656 @section Integer Division
657
658 This section describes functions for performing integer division.
659 To use these facilities, you should include the header file
660 @file{stdlib.h} in your program.
661 @pindex stdlib.h
662
663 These functions are not necessarily equivalent to the division performed
664 by the built-in @code{/} and @code{%} operators.  While the built-in
665 division operator is permitted to round in either direction if the
666 quotient is negative, the @code{div} and @code{ldiv} functions are
667 required to round towards zero.  It is also required that these
668 functions return a result @var{r} such that
669 @code{@var{r}.quot*@var{denominator} + @var{r}.rem} be equal to
670 @var{numerator}.
671
672 @comment stdlib.h
673 @comment ANSI
674 @deftp {Data Type} div_t
675 This is a structure type used to hold the result returned by the @code{div}
676 function.  It has the following members:
677
678 @table @code
679 @item {int quot}
680 The quotient from the division.
681
682 @item {int rem}
683 The remainder from the division.
684 @end table
685 @end deftp
686
687 @comment stdlib.h
688 @comment ANSI
689 @deftypefun div_t div (int @var{numerator}, int @var{denominator})
690 This function @code{div} computes the quotient and remainder from
691 the division of @var{numerator} by @var{denominator}, returning the
692 result in a structure of type @code{div_t}.
693
694 If the result cannot be represented (as in a division by zero), the
695 behavior is undefined.
696 @end deftypefun
697
698
699 @comment stdlib.h
700 @comment ANSI
701 @deftp {Data Type} ldiv_t
702 This is a structure type used to hold the result returned by the @code{ldiv}
703 function.  It has the following members:
704
705 @table @code
706 @item {long int quot}
707 The quotient from the division.
708
709 @item {long int rem}
710 The remainder from the division.
711 @end table
712
713 (This is identical to the type @code{div_t} except that the components
714 are of type @code{long int} rather than @code{int}.)
715 @end deftp
716
717 @comment stdlib.h
718 @comment ANSI
719 @deftypefun ldiv_t ldiv (long int @var{numerator}, long int @var{denominator})
720 The @code{ldiv} function is similar to @code{div}, except that the
721 arguments are of type @code{long int} and the result is returned as a
722 structure of type @code{ldiv}.
723 @end deftypefun
724
725
726 @node Absolute Value
727 @section Absolute Value
728
729 These functions are provided for obtaining the absolute value of
730 integer values.  Prototypes for @code{abs} and @code{abs} are declared
731 in @file{stdlib.h}; @code{fabs} is declared in @file{math.h}.
732 @pindex math.h
733 @pindex stdlib.h
734
735 @comment stdlib.h
736 @comment ANSI
737 @deftypefun int abs (int @var{number})
738 This function returns the absolute value (or magnitude) of @var{number}.
739 In a two's complement integer representation, the absolute value of
740 @code{INT_MIN} (the smallest possible @code{int}) cannot be represented;
741 in this case, the behavior of @code{abs} is undefined.
742 @end deftypefun
743
744 @comment stdlib.h
745 @comment ANSI
746 @deftypefun {long int} labs (long int @var{number})
747 This is similar to @code{abs}, except that both the argument and result
748 are of type @code{long int} rather than @code{int}.
749 @end deftypefun
750
751 @comment math.h
752 @comment ANSI
753 @deftypefun double fabs (double @var{number})
754 This function returns the absolute value of the floating-point number
755 @var{number}.
756 @end deftypefun
757
758 There is also the function @code{cabs} for computing the absolute value
759 of a complex number; @pxref{Exponentiation and Logarithms}.
760
761 @node Parsing of Numbers
762 @section Parsing of Numbers
763 @cindex parsing of numbers
764 @cindex string conversion
765 @cindex number syntax
766
767 This section describes functions for ``reading'' integer and
768 floating-point numbers from a string.  In many cases, it is more
769 appropriate to use @code{sscanf} or one of the related functions;
770 @pxref{Formatted Input}.  The syntax recognized by the formatted input
771 functions for the numeric conversions is exactly the same as the syntax
772 recognized by the functions described in this section.
773
774 These functions are declared in @file{stdlib.h}.
775 @pindex stdlib.h
776
777 @menu
778 * Parsing of Integers::         Functions for conversion of integer values.
779 * Parsing of Floats::           Functions for conversion of floating-point
780                                  values.
781 @end menu
782
783 @node Parsing of Integers
784 @subsection Parsing of Integers
785 @cindex parsing of integers
786
787 @comment stdlib.h
788 @comment ANSI
789 @deftypefun {long int} strtol (const char *@var{string}, char **@var{tailptr}, int @var{base})
790 The @code{strtol} (``string-to-long'') function converts the initial
791 part of @var{string} to a signed integer, which is returned as a value
792 of type @code{long int}.  
793
794 This function attempts to decompose @var{string} as follows:
795
796 @itemize @bullet
797 @item 
798 A (possibly empty) sequence of whitespace characters, as determined by
799 the @code{isspace} function (@pxref{Classification of Characters}).
800 These are discarded.
801
802 @item 
803 An optional plus or minus sign (@samp{+} or @samp{-}).
804
805 @item 
806 A nonempty sequence of digits in the radix specified by @var{base}.  If
807 @var{base} is zero, decimal radix is assumed unless the series of digits
808 begins with @samp{0} (specifying octal radix), or @samp{0x} or @samp{0X}
809 (specifying hexadecimal radix); in other words, the same syntax that is
810 used for integer constants in the C language is recognized.  Otherwise
811 @var{base} must have a value between @code{2} and @code{35}.  If
812 @var{base} is @code{16}, the digits may optionally be preceeded by
813 @samp{0x} or @samp{0X}.
814
815 @item 
816 Any remaining characters in the string.  If @var{tailptr} is not a null
817 pointer, a pointer to this tail of the string is stored in the object
818 it points to.
819 @end itemize
820
821 If the string is empty, contains only whitespace, or does not contain an
822 initial substring that has the expected syntax for an integer in the
823 specified @var{base}, no conversion is performed.  In this case,
824 @code{strtol} returns a value of zero and the value returned in
825 @var{tailptr} is the value of @var{string}.
826
827 In a locale other than the standard @code{"C"} locale, this function
828 may recognize additional implementation-dependent syntax.
829
830 If the string has valid syntax for an integer but the value is not
831 representable because of overflow, @code{strtol} returns either
832 @code{LONG_MAX} or @code{LONG_MIN} (@pxref{Integer Representation
833 Limits}), as appropriate for the sign of the value.
834
835 The following @code{errno} error conditions are defined for this
836 function:
837
838 @table @code
839 @item ERANGE
840 An overflow condition was detected.
841 @end table
842 @end deftypefun
843
844 @comment stdlib.h
845 @comment ANSI
846 @deftypefun {unsigned long int} strtoul (const char *@var{string}, char **@var{tailptr}, int @var{base})
847 The @code{strtoul} (``string-to-unsigned-long'') function is similar to
848 @code{strtol} except that it returns its value as an object of type
849 @code{unsigned long int}.  The value returned in case of overflow is
850 @code{ULONG_MAX} (@pxref{Integer Representation Limits}).
851 @end deftypefun
852
853 @comment stdlib.h
854 @comment ANSI
855 @deftypefun {long int} atol (const char *@var{string})
856 This function is similar to the @code{strtol} function with a @var{base}
857 argument of @code{10}, except that it need not detect overflow errors.
858 The @code{atol} function is provided mostly for compatibility with
859 existing code; using @code{strtol} is considered better style.
860 @end deftypefun
861
862 @comment stdlib.h
863 @comment ANSI
864 @deftypefun int atoi (const char *@var{string})
865 This function is similar to the @code{atol} function, except that
866 returns its value as an @code{int} rather than @code{long int}.  The
867 @code{atoi} function is also considered obsolete; use @code{strtol}
868 instead.
869 @end deftypefun
870
871 @node Predicates on Floats
872 @subsection Predicates on Floats
873
874 This section describes some miscellaneous test functions on doubles.
875 Prototypes for these functions appear in @file{math.h}.
876 @pindex math.h
877
878 @comment math.h
879 @comment GNU
880 @deftypefun int isinf (double @var{x})
881 This function returns @code{-1} if @var{x} represents negative infinity,
882 @code{1} if @var{x} represents positive infinity, and @code{0} otherwise.
883 @end deftypefun
884
885 @comment math.h
886 @comment GNU
887 @deftypefun int isnan (double @var{x})
888 This function returns a nonzero value if @var{x} is the ``not a number''
889 value, and zero otherwise.
890 @end deftypefun
891
892 @comment math.h
893 @comment GNU
894 @deftypefun int finite (double @var{x})
895 This function returns a nonzero value if @var{x} is finite or the ``not
896 a number'' value, and zero otherwise.
897 @end deftypefun
898
899 @comment math.h
900 @comment GNU
901 @deftypefun double infnan (int @var{error})
902 @strong{Incomplete:}  I don't understand what this function does.
903 @end deftypefun
904
905
906
907 @strong{Portability Note:} The functions listed in this section are GNU
908 extensions.
909
910 @node Parsing of Floats
911 @subsection Parsing of Floats
912
913 @comment stdlib.h
914 @comment ANSI
915 @deftypefun double strtod (const char *@var{string}, char **@var{tailptr})
916 The @code{strtod} (``string-to-double'') function converts the initial
917 part of @var{string} to a floating-point number, which is returned as a
918 value of type @code{double}.  
919
920 This function attempts to decompose @var{string} as follows:
921
922 @itemize @bullet
923 @item 
924 A (possibly empty) sequence of whitespace characters, as determined
925 by the @code{isspace} function.  These are discarded.
926
927 @item
928 An optional plus or minus sign (@samp{+} or @samp{-}).
929
930 @item
931 A nonempty sequence of digits optionally containing a decimal-point
932 character (@samp{.}).
933
934 @item
935 An optional exponent part, consisting of a character @samp{e} or
936 @samp{E}, an optional sign, and a sequence of digits.
937
938 @item
939 Any remaining characters in the string.  If @var{tailptr} is not a null
940 pointer, a pointer to this tail of the string is stored in the object it
941 points to.
942 @end itemize
943
944 If the string is empty, contains only whitespace, or does not contain
945 an initial substring that has the expected syntax for a floating-point
946 number, no conversion is performed.  In this case, @code{strtod} returns
947 a value of zero and the value returned in @var{tailptr} is the value of
948 @var{string}.
949
950 In a locale other than the standard @code{"C"} locale, this function
951 may recognize additional implementation-dependent syntax.
952
953 If the string has valid syntax for a floating-point number but the value
954 is not representable because of overflow, @code{strtod} returns either
955 positive or negative @code{HUGE_VAL} (@pxref{Mathematics}), depending on
956 the sign of the value.  Similarly, if the value is not representable
957 because of underflow, @code{strtod} returns zero.
958
959 The following @code{errno} error conditions are defined for this
960 function:
961
962 @table @code
963 @item ERANGE
964 An overflow or underflow condition was detected.
965 @end table
966 @end deftypefun
967
968 @comment stdlib.h
969 @comment ANSI
970 @deftypefun double atof (const char *@var{string})
971 This function is similar to the @code{strtod} function, except that it
972 need not detect overflow and underflow errors.  The @code{atof} function
973 is provided mostly for compatibility with existing code; using
974 @code{strtod} is considered better style.
975 @end deftypefun
976