1 @node Mathematics
2 @chapter Mathematics
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
10 All of the functions that operate on floating-point numbers accept
11 arguments and return results of type @code{double}.  In future revisions
12 of the ANSI C standard, additional functions may be added that operate
13 on @code{float} and @code{long double} values.  For example, @code{cosf}
14 and @code{cosl} would be versions of the @code{cos} function that
15 operate on @code{float} and @code{long double} arguments, respectively.
16 In the meantime, you should avoid using these names yourself.
17 @xref{Reserved Names}.
19 @strong{Incomplete:}  This chapter doesn't have any examples.
22 * Domain and Range Errors::             How overflow conditions and the like
23                                          are reported.
24 * Not a Number::                        Making NANs and testing for NANs.
25 * Trigonometric Functions::             Sine, cosine, and tangent.
26 * Inverse Trigonometric Functions::     Arc sine, arc cosine, and arc tangent.
27 * Exponentiation and Logarithms::       Also includes square root.
28 * Hyperbolic Functions::                Hyperbolic sine and friends.
29 * Pseudo-Random Numbers::               Functions for generating pseudo-random
30                                          numbers.
31 * Absolute Value::                      Absolute value functions.
34 @node Domain and Range Errors
35 @section Domain and Range Errors
37 @cindex domain error
38 Many of the functions listed in this chapter are defined mathematically
39 over a domain that is only a subset of real numbers.  For example, the
40 @code{acos} function is defined over the domain between @code{-1} and
41 @code{1}.  If you pass an argument to one of these functions that is
42 outside the domain over which it is defined, the function returns
43 an unspecified value and sets @code{errno} to @code{EDOM} to indicate
44 a @dfn{domain error}.
46 Some of these functions are defined mathematically to result in a
47 complex value over parts of their domains.  The most familiar example of
48 this is taking the square root of a negative number.  Since the C
49 language has no support for complex numbers, this is considered a
50 domain error.
52 @cindex range error
53 A related problem is that the mathematical result of a function may not
54 be representable as a floating point number.  If magnitude of the
55 correct result is too large to be represented, the function sets
56 @code{errno} to @code{ERANGE} to indicate a @dfn{range error}, and
57 returns a particular very large value (named by the macro
58 @code{HUGE_VAL}) or its negation.
60 If the magnitude of the result is too small, a value of zero is returned
61 instead.  In this case, @code{errno} might or might not be
62 set to @code{ERANGE}.
64 None of the mathematical functions ever generates signals as a result of
65 domain or range errors.  In particular, this means that you won't see
66 @code{SIGFPE} signals generated within these functions.  (@xref{Signal
67 Handling}, for more information about signals.)
69 The only completely reliable way to check for domain and range errors is
70 to set @code{errno} to @code{0} before you call the mathematical function
71 and test @code{errno} afterward.  As a consequence of this use of
72 @code{errno}, use of the mathematical functions is not reentrant if you
73 check for errors.
75 @comment math.h
76 @comment ANSI
77 @deftypevr Macro double HUGE_VAL
78 An expression representing a particular very large number.  On machines
79 that use IEEE floating point format, the value is ``infinity''.  On
80 other machines, it's typically the largest positive number that can be
81 represented.
83 The value of this macro is used as the return value from various
84 mathematical functions in overflow situations.
85 @end deftypevr
87 For more information about floating-point representations and limits,
88 @xref{Floating-Point Limits}.  In particular, the macro @code{DBL_MAX}
89 might be more appropriate than @code{HUGE_VAL} for many uses.
91 @node Not a Number
92 @section ``Not a Number'' Values
93 @cindex NAN
94 @cindex not a number
95 @cindex IEEE floating point
97 The IEEE floating point format used by most modern computers supports
98 values that are ``not a number''.  These values are called @dfn{NANs}.
99 ``Not a number'' values result from certain operations which have no
100 meaningful numeric result, such as zero divided by zero or infinity
101 divided by infinity.
103 One noteworthy property of NANs is that they are not equal to
104 themselves.  Thus, @code{x == x} can be 0 if the value of @code{x} is a
105 NAN.  In fact, this is the way to test whether a value is a NAN or not:
106 if it is not equal to itself, then it is a NAN.
108 Almost any arithmetic operation in which one argument is a NAN returns
109 a NAN.
111 @comment math.h
112 @comment GNU
113 @deftypevr Macro double NAN
114 An expression representing a value which is ``not a number''.  This
115 macro is a GNU extension, available only on machines that support ``not
116 a number'' values---that is to say, on all machines that support IEEE
117 floating point.
118 @end deftypevr
120 @node Trigonometric Functions
121 @section Trigonometric Functions
122 @cindex trignometric functions
124 These are the familiar @code{sin}, @code{cos}, and @code{tan} functions.
125 The arguments to all of these functions are in units of radians; recall
126 that pi radians equals 180 degrees.
128 @cindex pi (trigonometric constant)
129 The math library doesn't define a symbolic constant for pi, but you can
130 define your own if you need one:
132 @example
133 #define PI 3.14159265358979323846264338327
134 @end example
136 @noindent
137 You can also compute the value of pi with the expression @code{acos
138 (-1.0)}.
141 @comment math.h
142 @comment ANSI
143 @deftypefun double sin (double @var{x})
144 This function returns the sine of @var{x}, where @var{x} is given in
145 radians.  The return value is in the range @code{-1} to @code{1}.
146 @end deftypefun
148 @comment math.h
149 @comment ANSI
150 @deftypefun double cos (double @var{x})
151 This function returns the cosine of @var{x}, where @var{x} is given in
152 radians.  The return value is in the range @code{-1} to @code{1}.
153 @end deftypefun
155 @comment math.h
156 @comment ANSI
157 @deftypefun double tan (double @var{x})
158 This function returns the tangent of @var{x}, where @var{x} is given in
161 The following @code{errno} error conditions are defined for this function:
163 @table @code
164 @item ERANGE
165 Mathematically, the tangent function has singularities at odd multiples of
166 pi/2.  If the argument @var{x} is too close to one of these singularities,
167 @code{tan} sets this error condition and returns either positive or
168 negative @code{HUGE_VAL}.
169 @end table
170 @end deftypefun
173 @node Inverse Trigonometric Functions
174 @section Inverse Trigonometric Functions
175 @cindex inverse trigonmetric functions
177 These are the usual arc sine, arc cosine and arc tangent functions,
178 which are the inverses of the sine, cosine and tangent functions,
179 respectively.
181 @comment math.h
182 @comment ANSI
183 @deftypefun double asin (double @var{x})
184 This function computes the arc sine of @var{x}---that is, the value whose
185 sine is @var{x}.  The value is in units of radians.  Mathematically,
186 there are infinitely many such values; the one actually returned is the
187 one between @code{-pi/2} and @code{pi/2} (inclusive).
189 The following @code{errno} error conditions are defined for this function:
191 @table @code
192 @item EDOM
193 The argument @var{x} is out of range.  The arc sine function is defined
194 mathematically only over the domain @code{-1} to @code{1}.
195 @end table
196 @end deftypefun
198 @comment math.h
199 @comment ANSI
200 @deftypefun double acos (double @var{x})
201 This function computes the arc cosine of @var{x}---that is, the value
202 whose cosine is @var{x}.  The value is in units of radians.
203 Mathematically, there are infinitely many such values; the one actually
204 returned is the one between @code{0} and @code{pi} (inclusive).
206 The following @code{errno} error conditions are defined for this function:
208 @table @code
209 @item EDOM
210 The argument @var{x} is out of range.  The arc cosine function is defined
211 mathematically only over the domain @code{-1} to @code{1}.
212 @end table
213 @end deftypefun
216 @comment math.h
217 @comment ANSI
218 @deftypefun double atan (double @var{x})
219 This function computes the arc tangent of @var{x}---that is, the value
220 whose tangent is @var{x}.  The value is in units of radians.
221 Mathematically, there are infinitely many such values; the one actually
222 returned is the one between @code{-pi/2} and @code{pi/2}
223 (inclusive).
224 @end deftypefun
226 @comment math.h
227 @comment ANSI
228 @deftypefun double atan2 (double @var{y}, double @var{x})
229 This is the two argument arc tangent function.  It is similar to computing
230 the arc tangent of @var{y}/@var{x}, except that the signs of both arguments
231 are used to determine the quadrant of the result, and @var{x} is
232 permitted to be zero.  The return value is given in radians and is in
233 the range @code{-pi} to @code{pi}, inclusive.
235 If @var{x} and @var{y} are coordinates of a point in the plane,
236 @code{atan2} returns the signed angle between the line from the origin
237 to that point and the x-axis.  Thus, @code{atan2} is useful for
238 converting Cartesian coordinates to polar coordinates.  (To compute the
239 radial coordinate, use @code{hypot}; see @ref{Exponentiation and
240 Logarithms}.)
242 The following @code{errno} error conditions are defined for this function:
244 @table @code
245 @item EDOM
246 Both the @var{x} and @var{y} arguments are zero; the value of the
247 function is not defined in this case.
248 @end table
249 @end deftypefun
252 @node Exponentiation and Logarithms
253 @section Exponentiation and Logarithms
254 @cindex exponentiation functions
255 @cindex power functions
256 @cindex logarithm functions
258 @comment math.h
259 @comment ANSI
260 @deftypefun double exp (double @var{x})
261 The @code{exp} function returns the value of e (the base of natural
262 logarithms) raised to power @var{x}.
264 The following @code{errno} error conditions are defined for this function:
266 @table @code
267 @item ERANGE
268 The magnitude of the result is too large to be representable.
269 @end table
270 @end deftypefun
272 @comment math.h
273 @comment ANSI
274 @deftypefun double log (double @var{x})
275 This function returns the natural logarithm of @var{x}.  @code{exp (log
276 (@var{x}))} equals @var{x}, exactly in mathematics and approximately in
277 C.
279 The following @code{errno} error conditions are defined for this function:
281 @table @code
282 @item EDOM
283 The log function is defined mathematically to return a non-complex
284 result only on positive arguments.  This error is used to report a
285 negative argument @var{x}.
287 @item ERANGE
288 The result of the function on an argument of zero is not defined.
289 @end table
290 @end deftypefun
292 @comment math.h
293 @comment ANSI
294 @deftypefun double log10 (double @var{x})
295 This function returns the base-10 logarithm of @var{x}.  Except for the
296 different base, it is similar to the @code{log} function.  In fact,
297 @code{log10 (@var{x})} equals @code{log (@var{x}) / log (10)}.
298 @end deftypefun
300 @comment math.h
301 @comment ANSI
302 @deftypefun double pow (double @var{base}, double @var{power})
303 This is a general exponentiation function, returning @var{base} raised
304 to @var{power}.
306 The following @code{errno} error conditions are defined for this function:
308 @table @code
309 @item EDOM
310 The argument @var{base} is negative and @var{power} is not an integral
311 value.  Mathematically, the result would be a complex number in this case.
313 @item ERANGE
314 An underflow or overflow condition was detected in the result.
315 @end table
316 @end deftypefun
318 @cindex square root function
319 @comment math.h
320 @comment ANSI
321 @deftypefun double sqrt (double @var{x})
322 This function returns the nonnegative square root of @var{x}.
324 The following @code{errno} error conditions are defined for this function:
326 @table @code
327 @item EDOM
328 The argument @var{x} is negative.  Mathematically, the square root would
329 be a complex number.
330 @end table
331 @end deftypefun
333 @cindex cube root function
334 @comment math.h
335 @comment GNU
336 @deftypefun double cbrt (double @var{x})
337 This function returns the cube root of @var{x}.
338 @end deftypefun
340 @comment math.h
341 @comment GNU
342 @deftypefun double hypot (double @var{x}, double @var{y})
343 The @code{hypot} function returns @code{sqrt (@var{x}*@var{x} +
344 @var{y}*@var{y})}.  (This is the length of the hypotenuse of a right
345 triangle with sides of length @var{x} and @var{y}, or the distance
346 of the point (@var{x}, @var{y}) from the origin.)
347 @end deftypefun
349 @comment math.h
350 @comment GNU
351 @deftypefun double cabs (struct @{ double x, y; @} @var{z})
352 The @code{cabs} function is similar to @code{hypot}, but the argument
353 is specified as a @code{struct} representing a complex number.
354 @end deftypefun
357 @comment math.h
358 @comment GNU
359 @deftypefun double expm1 (double @var{x})
360 This function returns a value equivalent to @code{exp (@var{x}) - 1}.
361 It is computed in a way that is accurate even if the value of @var{x} is
362 near zero---a case where @code{exp (@var{x}) - 1} would be inaccurate due
363 to subtraction of two numbers that are nearly equal.
364 @end deftypefun
366 @comment math.h
367 @comment GNU
368 @deftypefun double log1p (double @var{x})
369 This function returns a value equivalent to @code{log (1 + @var{x})}.
370 It is computed in a way that is accurate even if the value of @var{x} is
371 near zero.
372 @end deftypefun
374 @node Hyperbolic Functions
375 @section Hyperbolic Functions
376 @cindex hyperbolic functions
378 The functions in this section are related to the exponential functions;
379 see @ref{Exponentiation and Logarithms}.
381 @comment math.h
382 @comment ANSI
383 @deftypefun double sinh (double @var{x})
384 The @code{sinh} function returns the hyperbolic sine of @var{x}, defined
385 mathematically as @code{(exp (@var{x}) - exp (-@var{x}) / 2}.
386 The following @code{errno} error conditions are defined for this
387 function:
389 @table @code
390 @item ERANGE
391 The value of the argument @var{x} is too large; an overflow condition
392 was detected.
393 @end table
394 @end deftypefun
396 @comment math.h
397 @comment ANSI
398 @deftypefun double cosh (double @var{x})
399 The @code{cosh} function returns the hyperbolic cosine of @var{x},
400 defined mathematically as @code{(exp (@var{x}) + exp (-@var{x}) /
401 2}.  The following @code{errno} error conditions are defined for this
402 function:
404 @table @code
405 @item ERANGE
406 The value of the argument @var{x} is too large; an overflow condition
407 was detected.
408 @end table
409 @end deftypefun
411 @comment math.h
412 @comment ANSI
413 @deftypefun double tanh (double @var{x})
414 This function returns the hyperbolic tangent of @var{x}, defined
415 mathematically as @code{sinh (@var{x}) / cosh (@var{x})}.
416 @end deftypefun
418 @cindex inverse hyperbolic functions
420 @comment math.h
421 @comment GNU
422 @deftypefun double asinh (double @var{x})
423 This function returns the inverse hyperbolic sine of @var{x}---the
424 value whose hyperbolic sine is @var{x}.
425 @end deftypefun
427 @comment math.h
428 @comment GNU
429 @deftypefun double acosh (double @var{x})
430 This function returns the inverse hyperbolic cosine of @var{x}---the
431 value whose hyperbolic cosine is @var{x}.  If @var{x} is less than
432 @code{1}, @code{acosh} returns @code{HUGE_VAL}.
433 @end deftypefun
435 @comment math.h
436 @comment GNU
437 @deftypefun double atanh (double @var{x})
438 This function returns the inverse hyperbolic tangent of @var{x}---the
439 value whose hyperbolic tangent is @var{x}.  If the absolute value of
440 @var{x} is greater than or equal to @code{1}, @code{atanh} returns
441 @code{HUGE_VAL}.
442 @end deftypefun
444 @node Pseudo-Random Numbers
445 @section Pseudo-Random Numbers
447 This section describes the GNU facilities for generating a series of
448 pseudo-random numbers.  The numbers generated are not necessarily truly
449 random; typically, the sequences repeat periodically, with the period
450 being a function of the number of bits in the @dfn{seed} or initial
451 state.
452 @cindex random numbers
453 @cindex pseudo-random numbers
454 @cindex seed (for random numbers)
456 There are actually two sets of random number functions provided.
458 @itemize @bullet
459 @item
460 The @code{rand} and @code{srand} functions, described in @ref{ANSI C
461 Random Number Functions}, are part of the ANSI C standard.  You can use
462 these functions portably in many C implementations.
464 @item
465 The @code{random} and @code{srandom} functions, described in @ref{BSD
466 Random Number Functions}, are derived from BSD Unix.  This uses a better
467 random number generator (producing numbers that are more random), but
468 is less portable.
469 @end itemize
471 For both sets of functions, you can get repeatable sequences of numbers
472 within a single implementation on a single machine type by specifying
473 the same initial seed value for the random number generator.  Other C
474 libraries may produce different sequences of values for the same seed.
478 * ANSI C Random Number Functions::      @code{rand} and friends.
479 * BSD Random Number Functions::         @code{random} and friends.
482 @node ANSI C Random Number Functions
483 @subsection ANSI C Random Number Functions
485 This section describes the random number functions that are part of
486 the ANSI C standard.  These functions represent the state of the
487 random number generator as an @code{int}.
489 To use these facilities, you should include the header file
490 @file{stdlib.h} in your program.
491 @pindex stdlib.h
493 @comment stdlib.h
494 @comment ANSI
495 @deftypevr Macro int RAND_MAX
496 The value of this macro is an integer constant expression that
497 represents the maximum possible value returned by the @code{rand}
498 function.  In the GNU library, it is @code{037777777}.  In other
499 libraries, it may be as low as @code{32767}.
500 @end deftypevr
502 @comment stdlib.h
503 @comment ANSI
504 @deftypefun int rand (void)
505 The @code{rand} function returns the next pseudo-random number in the
506 series.  The value is in the range from @code{0} to @code{RAND_MAX}.
507 @end deftypefun
509 @comment stdlib.h
510 @comment ANSI
511 @deftypefun void srand (unsigned int @var{seed})
512 This function establishes @var{seed} as the seed for a new series of
513 pseudo-random numbers.  If you call @code{rand} before a seed has been
514 established with @code{srand}, it uses the value @code{1} as a default
515 seed.
517 To produce truly random numbers (not just pseudo-random), do @code{srand
518 (time (0))}.
519 @end deftypefun
521 @node BSD Random Number Functions
522 @subsection BSD Random Number Functions
524 This section describes a set of random number generation functions
525 that are derived from BSD Unix.  The @code{random} function can generate
526 better random numbers than @code{rand}, because it maintains more bits
527 of internal state.
529 The prototypes for these functions are in @file{stdlib.h}.
530 @pindex stdlib.h
532 @comment stdlib.h
533 @comment BSD
534 @deftypefun {long int} random (void)
535 This function returns the next pseudo-random number in the sequence.
536 The range of values returned is from @code{0} to @code{RAND_MAX}.
537 @end deftypefun
539 @comment stdlib.h
540 @comment BSD
541 @deftypefun void srandom (unsigned int @var{seed})
542 The @code{srandom} function sets the seed for the current random number
543 state based on the integer @var{seed}.  If you supply a @var{seed} value
544 of @code{1}, this will cause @code{random} to reproduce the default set
545 of random numbers.
547 To produce truly random numbers (not just pseudo-random), do
548 @code{srandom (time (0))}.
549 @end deftypefun
551 Because this random number generator uses more state information than
552 will fit in an @code{int}, @code{srandom} does not return a value that
553 is useful for saving and restoring the random number state.  Instead,
554 you should use the @code{initstate} and @code{setstate} functions to do
555 this.
557 @comment stdlib.h
558 @comment BSD
559 @deftypefun {void *} initstate (unsigned int @var{seed}, void *@var{state}, size_t @var{size})
560 The @code{initstate} function is used to initialize the random number
561 generator state.  The argument @var{state} is an array of @var{size}
562 bytes, used to hold the state information.  The size must be at least 8
563 bytes, and optimal sizes are 8, 16, 32, 64, 128, and 256.  The bigger
564 the @var{state} array, the better.
566 The return value is the previous value of the state information array.
567 You can use this value later as an argument to @code{setstate} to
568 restore that state.
569 @end deftypefun
571 @comment stdlib.h
572 @comment BSD
573 @deftypefun {void *} setstate (void *@var{state})
574 The @code{setstate} function restores the random number state
575 information @var{state}.  The argument must have been the result of
576 a previous call to @var{initstate} or @var{setstate}.
578 The return value is the previous value of the state information array.
579 You can use thise value later as an argument to @code{setstate} to
580 restore that state.
581 @end deftypefun
583 @node Absolute Value
584 @section Absolute Value
585 @cindex absolute value functions
587 These functions are provided for obtaining the @dfn{absolute value} (or
588 @dfn{magnitude}) of a number.  The absolute value of @var{x} is @var{x}
589 is @var{x} is positive, @minus{}@var{x} if @var{x} is negative.
591 Prototypes for @code{abs} and @code{abs} are declared in
592 @file{stdlib.h}; @code{fabs} is declared in @file{math.h}.
593 @pindex math.h
594 @pindex stdlib.h
596 @comment stdlib.h
597 @comment ANSI
598 @deftypefun int abs (int @var{number})
599 This function returns the absolute value of @var{number}.
601 Most computers use a two's complement integer representation, in which
602 the absolute value of @code{INT_MIN} (the smallest possible @code{int})
603 cannot be represented; thus, @code{abs (INT_MIN)} is not defined.
604 @end deftypefun
606 @comment stdlib.h
607 @comment ANSI
608 @deftypefun {long int} labs (long int @var{number})
609 This is similar to @code{abs}, except that both the argument and result
610 are of type @code{long int} rather than @code{int}.
611 @end deftypefun
613 @comment math.h
614 @comment ANSI
615 @deftypefun double fabs (double @var{number})
616 This function returns the absolute value of the floating-point number
617 @var{number}.
618 @end deftypefun
620 There is also the function @code{cabs} for computing the absolute value
621 of a complex number; see @ref{Exponentiation and Logarithms}.
623 @node Arithmetic
624 @chapter Low-Level Arithmetic Functions
626 This chapter contains information about functions for doing basic
627 arithmetic operations, such as splitting a float into its integer and
628 fractional parts.  These functions are declared in the header file
629 @file{math.h}.
632 * Normalization Functions::             Hacks for radix-2 representations.
633 * Rounding and Remainder Functions::    Determinining the integer and
634                                          fractional parts of a float.
635 * Integer Division::                    Functions for performing integer
636                                          division.
637 * Parsing of Numbers::                  Functions for ``reading'' numbers
638                                          from strings.
639 * Predicates on Floats::                Some miscellaneous test functions.
642 @node Normalization Functions
643 @section Normalization Functions
644 @cindex normalization functions (floating-point)
646 The functions described in this section are primarily provided as a way
647 to efficiently perform certain low-level manipulations on floating point
648 numbers that are represented internally using a binary radix;
649 see @ref{Floating-Point Representation}.  These functions are required to
650 have equivalent behavior even if the representation does not use a radix
651 of 2, but of course they are unlikely to be particularly efficient in
652 those cases.
654 @comment math.h
655 @comment GNU
656 @deftypefun double copysign (double @var{value}, double @var{sign})
657 The @code{copysign} function returns a value whose absolute value is the
658 same as that of @var{value}, and whose sign matches that of @var{sign}.
659 @end deftypefun
661 @comment math.h
662 @comment ANSI
663 @deftypefun double frexp (double @var{value}, int *@var{exponent})
664 The @code{frexp} function is used to normalize the number @var{value}.
666 If the argument @var{value} is not zero, the return value is a
667 floating-point number with magnitude in the range 1/2 (inclusive) to 1
668 (exclusive).  The corresponding exponent is stored in the location
669 pointed at by @var{exponent}; the return value multiplied by 2 raised to
670 this exponent would equal the original number @var{value}.
672 If @var{value} is zero, then both parts of the result are zero.
673 @end deftypefun
675 @comment math.h
676 @comment ANSI
677 @deftypefun double ldexp (double @var{value}, int @var{exponent})
678 This function returns the result of multiplying the floating-point
679 number @var{value} by 2 raised to the power @var{exponent}.  (It can
680 be used to reassemble floating-point numbers that were taken apart
681 by @code{frexp}.)
682 @end deftypefun
684 @c ??? Where does this come from?
685 @comment math.h
686 @comment GNU
687 @deftypefun double scalb (double @var{value}, int @var{exponent})
688 The @code{scalb} function does the same thing as @code{ldexp}.
689 @end deftypefun
691 @c ??? Where does this come from?
692 @comment math.h
693 @comment GNU
694 @deftypefun double logb (double @var{x})
695 This function returns the integer part of the base-2 logarithm of
696 @var{x}, an integer value represented in type @code{double}.  This is
697 the highest integer power of @code{2} contained in @var{x}.
699 When @code{2} raised to this power is divided into @var{x}, it gives a
700 quotient between @code{1} (inclusive) and @code{2} (exclusive).
702 @strong{Incomplete:}  What happens if @var{x} is zero?
703 @end deftypefun
706 @node Rounding and Remainder Functions
707 @section Rounding and Remainder Functions
708 @cindex rounding functions
709 @cindex remainder functions
710 @cindex converting floats to integers
712 The functions listed here perform operations such as rounding,
713 truncation, and remainder in division of floating point numbers.  Some
714 of these functions convert floating point numbers to integer values.
716 You can also convert floating-point numbers to integers simply by
717 casting them to @code{int}.  This discards the fractional part,
718 effectively rounding towards zero.  However, this only works if the
719 result can actually be represented as an @code{int}---for very large
720 numbers, this is impossible.  The functions listed here return the
721 result as a @code{double} instead to get around this problem.
723 @comment math.h
724 @comment ANSI
725 @deftypefun double ceil (double @var{x})
726 The @code{ceil} function rounds @var{x} upwards to the nearest integer,
727 returning that value as a @code{double}.
728 @end deftypefun
730 @comment math.h
731 @comment ANSI
732 @deftypefun double floor (double @var{x})
733 The @code{ceil} function rounds @var{x} downwards to the nearest
734 integer, returning that value as a @code{double}.
735 @end deftypefun
737 @comment math.h
738 @comment GNU
739 @deftypefun double rint (double @var{x})
740 This function returns the integer nearest @var{x} according to the
741 current rounding mode.  @xref{Floating-Point Parameters}, for information
743 @end deftypefun
745 @comment math.h
746 @comment ANSI
747 @deftypefun double modf (double @var{value}, double *@var{integer_part})
748 This function breaks the argument @var{value} into an integer part and a
749 fractional part (between @code{-1} and @code{1}, exclusive).  The
750 integer part is stored at the location pointed at by @var{integer_part},
751 and the fractional part is returned.  Their sum equals @var{value}.
752 Each of the parts has the same sign as @var{value}, so the rounding of
753 the integer part is towards zero.
754 @end deftypefun
757 @comment math.h
758 @comment ANSI
759 @deftypefun double fmod (double @var{numerator}, double @var{denominator})
760 This function computes the remainder of dividing @var{numerator} by
761 @var{denominator}.  Specifically, the return value is
762 @code{@var{numerator} - @var{n} * @var{denominator}}, where @var{n} is
763 the quotient of @var{numerator} by @var{denominator}, rounded down to
764 the next lower integer.
766 The result has the same sign as the @var{numerator} and has magnitude
767 less than the magnitude of the @var{denominator}.  (Recall that the
768 built-in @samp{%} operator isn't defined on floating-point values.)
770 The following @code{errno} error conditions are defined for this function:
772 @table @code
773 @item EDOM
774 The @var{denominator} is zero.
775 @end table
776 @end deftypefun
778 @comment math.h
779 @comment GNU
780 @deftypefun double drem (double @var{numerator}, double @var{denominator})
781 This function returns the remainder from dividing @var{numerator} by
782 @var{denominator}.  Specifically, the return value is @code{@var{numerator}
783 - @var{n} * @var{denominator}}, where @var{n} is the integer closest to
784 the exact quotient of @var{numerator} and @var{denominator}.  The absolute
785 value of the result is less than or equal to one half the absolute value
786 of the @var{denominator}.
788 The following @code{errno} error conditions are defined for this function:
790 @table @code
791 @item EDOM
792 The @var{denominator} is zero.
793 @end table
794 @end deftypefun
797 @node Integer Division
798 @section Integer Division
799 @cindex integer division functions
801 This section describes functions for performing integer division.  These
802 functions are redundant in the GNU C library, since in GNU C the @samp{/}
803 operator always rounds towards zero.  But in other C implementations,
804 @samp{/} may round differently with negative arguments.  @code{div} and
805 @code{ldiv} are useful because they specify how to round the quotient.
807 These functions are specified to return a result @var{r} such that
808 @code{@var{r}.quot*@var{denominator} + @var{r}.rem} equals
809 @var{numerator}.
811 To use these facilities, you should include the header file
812 @file{stdlib.h} in your program.
813 @pindex stdlib.h
815 @comment stdlib.h
816 @comment ANSI
817 @deftp {Data Type} div_t
818 This is a structure type used to hold the result returned by the @code{div}
819 function.  It has the following members:
821 @table @code
822 @item {int quot}
823 The quotient from the division.
825 @item {int rem}
826 The remainder from the division.
827 @end table
828 @end deftp
830 @comment stdlib.h
831 @comment ANSI
832 @deftypefun div_t div (int @var{numerator}, int @var{denominator})
833 This function @code{div} computes the quotient and remainder from
834 the division of @var{numerator} by @var{denominator}, returning the
835 result in a structure of type @code{div_t}.
837 If the result cannot be represented (as in a division by zero), the
838 behavior is undefined.
839 @end deftypefun
842 @comment stdlib.h
843 @comment ANSI
844 @deftp {Data Type} ldiv_t
845 This is a structure type used to hold the result returned by the @code{ldiv}
846 function.  It has the following members:
848 @table @code
849 @item {long int quot}
850 The quotient from the division.
852 @item {long int rem}
853 The remainder from the division.
854 @end table
856 (This is identical to the type @code{div_t} except that the components
857 are of type @code{long int} rather than @code{int}.)
858 @end deftp
860 @comment stdlib.h
861 @comment ANSI
862 @deftypefun ldiv_t ldiv (long int @var{numerator}, long int @var{denominator})
863 The @code{ldiv} function is similar to @code{div}, except that the
864 arguments are of type @code{long int} and the result is returned as a
865 structure of type @code{ldiv}.
866 @end deftypefun
869 @node Parsing of Numbers
870 @section Parsing of Numbers
871 @cindex parsing numbers (in formatted input)
872 @cindex converting strings to numbers
873 @cindex number syntax, parsing
874 @cindex syntax, for reading numbers
876 This section describes functions for ``reading'' integer and
877 floating-point numbers from a string.  In many cases, it is more
878 appropriate to use @code{sscanf} or one of the related functions;
879 see @ref{Formatted Input}.  The syntax recognized by the formatted input
880 functions for the numeric conversions is exactly the same as the syntax
881 recognized by the functions described in this section.
883 These functions are declared in @file{stdlib.h}.
884 @pindex stdlib.h
887 * Parsing of Integers::         Functions for conversion of integer values.
888 * Parsing of Floats::           Functions for conversion of floating-point
889                                  values.
892 @node Parsing of Integers
893 @subsection Parsing of Integers
895 @comment stdlib.h
896 @comment ANSI
897 @deftypefun {long int} strtol (const char *@var{string}, char **@var{tailptr}, int @var{base})
898 The @code{strtol} (``string-to-long'') function converts the initial
899 part of @var{string} to a signed integer, which is returned as a value
900 of type @code{long int}.
902 This function attempts to decompose @var{string} as follows:
904 @itemize @bullet
905 @item
906 A (possibly empty) sequence of whitespace characters.  Which characters
907 are whitespace is determined by the @code{isspace} function
908 (@pxref{Classification of Characters}).  These are discarded.
910 @item
911 An optional plus or minus sign (@samp{+} or @samp{-}).
913 @item
914 A nonempty sequence of digits in the radix specified by @var{base}.  If
915 @var{base} is zero, decimal radix is assumed unless the series of digits
916 begins with @samp{0} (specifying octal radix), or @samp{0x} or @samp{0X}
917 (specifying hexadecimal radix); in other words, the same syntax that is
918 used for integer constants in the C language is recognized.  Otherwise
919 @var{base} must have a value between @code{2} and @code{35}.  If
920 @var{base} is @code{16}, the digits may optionally be preceeded by
921 @samp{0x} or @samp{0X}.
923 @item
924 Any remaining characters in the string.  If @var{tailptr} is not a null
925 pointer, a pointer to this tail of the string is stored in
926 @code{*@var{tailptr}}.
927 @end itemize
929 If the string is empty, contains only whitespace, or does not contain an
930 initial substring that has the expected syntax for an integer in the
931 specified @var{base}, no conversion is performed.  In this case,
932 @code{strtol} returns a value of zero and the value returned in
933 @code{*@var{tailptr}} is the value of @var{string}.
935 In a locale other than the standard @code{"C"} locale, this function
936 may recognize additional implementation-dependent syntax.
938 If the string has valid syntax for an integer but the value is not
939 representable because of overflow, @code{strtol} returns either
940 @code{LONG_MAX} or @code{LONG_MIN} (@pxref{Integer Representation
941 Limits}), as appropriate for the sign of the value.
943 The following @code{errno} error conditions are defined for this
944 function:
946 @table @code
947 @item ERANGE
948 An overflow condition was detected.
949 @end table
950 @end deftypefun
952 @comment stdlib.h
953 @comment ANSI
954 @deftypefun {unsigned long int} strtoul (const char *@var{string}, char **@var{tailptr}, int @var{base})
955 The @code{strtoul} (``string-to-unsigned-long'') function is similar to
956 @code{strtol} except that it returns its value as an object of type
957 @code{unsigned long int}.  The value returned in case of overflow is
958 @code{ULONG_MAX} (@pxref{Integer Representation Limits}).
959 @end deftypefun
961 @comment stdlib.h
962 @comment ANSI
963 @deftypefun {long int} atol (const char *@var{string})
964 This function is similar to the @code{strtol} function with a @var{base}
965 argument of @code{10}, except that it need not detect overflow errors.
966 The @code{atol} function is provided mostly for compatibility with
967 existing code; using @code{strtol} is more robust.
968 @end deftypefun
970 @comment stdlib.h
971 @comment ANSI
972 @deftypefun int atoi (const char *@var{string})
973 This function is similar to the @code{atol} function, except that
974 returns its value as an @code{int} rather than @code{long int}.  The
975 @code{atoi} function is also considered obsolete; use @code{strtol}
977 @end deftypefun
980 @node Parsing of Floats
981 @subsection Parsing of Floats
983 @comment stdlib.h
984 @comment ANSI
985 @deftypefun double strtod (const char *@var{string}, char **@var{tailptr})
986 The @code{strtod} (``string-to-double'') function converts the initial
987 part of @var{string} to a floating-point number, which is returned as a
988 value of type @code{double}.
990 This function attempts to decompose @var{string} as follows:
992 @itemize @bullet
993 @item
994 A (possibly empty) sequence of whitespace characters.  Which characters
995 are whitespace is determined by the @code{isspace} function
996 (@pxref{Classification of Characters}).  These are discarded.
998 @item
999 An optional plus or minus sign (@samp{+} or @samp{-}).
1001 @item
1002 A nonempty sequence of digits optionally containing a decimal-point
1003 character (@samp{.}).
1005 @item
1006 An optional exponent part, consisting of a character @samp{e} or
1007 @samp{E}, an optional sign, and a sequence of digits.
1009 @item
1010 Any remaining characters in the string.  If @var{tailptr} is not a null
1011 pointer, a pointer to this tail of the string is stored in
1012 @code{*@var{tailptr}}.
1013 @end itemize
1015 If the string is empty, contains only whitespace, or does not contain an
1016 initial substring that has the expected syntax for a floating-point
1017 number, no conversion is performed.  In this case, @code{strtod} returns
1018 a value of zero and the value returned in @code{*@var{tailptr}} is the
1019 value of @var{string}.
1021 In a locale other than the standard @code{"C"} locale, this function may
1024 If the string has valid syntax for a floating-point number but the value
1025 is not representable because of overflow, @code{strtod} returns either
1026 positive or negative @code{HUGE_VAL} (@pxref{Mathematics}), depending on
1027 the sign of the value.  Similarly, if the value is not representable
1028 because of underflow, @code{strtod} returns zero.
1030 The following @code{errno} error conditions are defined for this
1031 function:
1033 @table @code
1034 @item ERANGE
1035 An overflow or underflow condition was detected.
1036 @end table
1037 @end deftypefun
1039 @comment stdlib.h
1040 @comment ANSI
1041 @deftypefun double atof (const char *@var{string})
1042 This function is similar to the @code{strtod} function, except that it
1043 need not detect overflow and underflow errors.  The @code{atof} function
1044 is provided mostly for compatibility with existing code; using
1045 @code{strtod} is more robust.
1046 @end deftypefun
1048 @node Predicates on Floats
1049 @section Predicates on Floats
1050 @cindex predicates on floats
1052 This section describes some miscellaneous test functions on doubles.
1053 Prototypes for these functions appear in @file{math.h}.
1054 @pindex math.h
1056 @comment math.h
1057 @comment GNU
1058 @deftypefun int isinf (double @var{x})
1059 This function returns @code{-1} if @var{x} represents negative infinity,
1060 @code{1} if @var{x} represents positive infinity, and @code{0} otherwise.
1061 @end deftypefun
1063 @comment math.h
1064 @comment GNU
1065 @deftypefun int isnan (double @var{x})
1066 This function returns a nonzero value if @var{x} is a ``not a number''
1067 value, and zero otherwise.
1068 @end deftypefun
1070 @comment math.h
1071 @comment GNU
1072 @deftypefun int finite (double @var{x})
1073 This function returns a nonzero value if @var{x} is finite or a ``not a
1074 number'' value, and zero otherwise.
1075 @end deftypefun
1077 @comment math.h
1078 @comment GNU
1079 @deftypefun double infnan (int @var{error})
1080 @strong{Incomplete:}  I don't understand what this function does.
1081 @end deftypefun
1083 @strong{Portability Note:} The functions listed in this section are GNU
1084 extensions.