1 @node Arithmetic, Date and Time, Mathematics, Top
2 @chapter Low-Level Arithmetic Functions
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
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
18 * Parsing of Numbers:: Functions for ``reading'' numbers
23 @section ``Not a Number'' Values
26 @cindex IEEE floating point
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
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}).
40 Almost any arithmetic operation in which one argument is a NaN returns
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
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
57 @node Predicates on Floats
58 @section Predicates on Floats
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
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.
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).
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.
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.
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.
103 @strong{Portability Note:} The functions listed in this section are BSD
107 @section Absolute Value
108 @cindex absolute value functions
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})}}.
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}.
124 @deftypefun int abs (int @var{number})
125 This function returns the absolute value of @var{number}.
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.
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}.
141 @deftypefun double fabs (double @var{number})
142 This function returns the absolute value of the floating-point number
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:
155 sqrt (@var{z}.real*@var{z}.real + @var{z}.imag*@var{z}.imag)
159 @node Normalization Functions
160 @section Normalization Functions
161 @cindex normalization functions (floating-point)
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
172 All these functions are declared in @file{math.h}.
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.
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}.
186 For example, @code{frexp (12.8, &exponent)} returns @code{0.8} and
187 stores @code{4} in @code{exponent}.
189 If @var{value} is zero, then the return value is zero and
190 zero is stored in @code{*@var{exponent}}.
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
201 For example, @code{ldexp (0.8, 4)} returns @code{12.8}.
204 The following functions which come from BSD provide facilities
205 equivalent to those of @code{ldexp} and @code{frexp}:
209 @deftypefun double scalb (double @var{value}, int @var{exponent})
210 The @code{scalb} function is the BSD name for @code{ldexp}.
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}.
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).
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
229 The value returned by @code{logb} is one less than the value that
230 @code{frexp} would store into @code{*@var{exponent}}.
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.
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
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}.
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.
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)}
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}.
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.
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.
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}.
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}.
310 The result has the same sign as the @var{numerator} and has magnitude
311 less than the magnitude of the @var{denominator}.
313 If @var{denominator} is zero, @code{fmod} fails and sets @code{errno} to
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}.
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.
331 If @var{denominator} is zero, @code{drem} fails and sets @code{errno} to
336 @node Integer Division
337 @section Integer Division
338 @cindex integer division functions
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.
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
352 To use these facilities, you should include the header file
353 @file{stdlib.h} in your program.
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:
363 The quotient from the division.
366 The remainder from the division.
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}.
377 If the result cannot be represented (as in a division by zero), the
378 behavior is undefined.
380 Here is an example, albeit not a very useful one.
384 result = div (20, -6);
388 Now @code{result.quot} is @code{-3} and @code{result.rem} is @code{2}.
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:
399 The quotient from the division.
402 The remainder from the division.
405 (This is identical to @code{div_t} except that the components are of
406 type @code{long int} rather than @code{int}.)
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}.
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
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
433 * Parsing of Integers:: Functions for conversion of integer values.
434 * Parsing of Floats:: Functions for conversion of floating-point
438 @node Parsing of Integers
439 @subsection Parsing of Integers
442 These functions are declared in @file{stdlib.h}.
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}.
451 This function attempts to decompose @var{string} as follows:
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.
460 An optional plus or minus sign (@samp{+} or @samp{-}).
463 A nonempty sequence of digits in the radix specified by @var{base}.
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.
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}.
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}}.
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}.
487 In a locale other than the standard @code{"C"} locale, this function
488 may recognize additional implementation-dependent syntax.
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.
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.
501 There is an example at the end of this section.
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}).
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}.
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}.
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.
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}
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}).
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}
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.
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.
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.
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.
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.
600 Here is a function which parses a string as a sequence of integers and
601 returns the sum of them:
605 sum_ints_from_string (char *string)
613 /* @r{Skip whitespace by hand, to detect the end.} */
614 while (isspace (*string)) string++;
618 /* @r{There is more nonwhitespace,} */
619 /* @r{so it ought to be another number.} */
622 next = strtol (string, &tail, 0);
623 /* @r{Add it in, if not overflow.} */
625 printf ("Overflow\n");
628 /* @r{Advance past it.} */
636 @node Parsing of Floats
637 @subsection Parsing of Floats
640 These functions are declared in @file{stdlib.h}.
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}.
649 This function attempts to decompose @var{string} as follows:
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.
658 An optional plus or minus sign (@samp{+} or @samp{-}).
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}).
666 An optional exponent part, consisting of a character @samp{e} or
667 @samp{E}, an optional sign, and a sequence of digits.
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}}.
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}.
681 In a locale other than the standard @code{"C"} or @code{"POSIX"} locales,
682 this function may recognize additional locale-dependent syntax.
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.
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.
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.
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.
713 This function is a GNU extension.
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.
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.
731 This function is a GNU extension.
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}).
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.