Low-Level Arithmetic Functions
******************************

This chapter contains information about functions for doing basic arithmetic operations, such as splitting a float into its integer and fractional parts or retrieving the imaginary part of a complex value. These functions are declared in the header files math.h and complex.h.

Infinity Values
===============

Mathematical operations easily can produce as the result values which are not representable by the floating-point format.  The functions in the mathematics library also have this problem.  The situation is generally solved by raising an overflow exception and by returning a huge value.

The IEEE 754 floating-point defines a special value to be used in these situations.  There is a special value for infinity.

 -- Macro: float_t INFINITY
     An expression representing the infinite value.  INFINITY values are produced by mathematical operations like 1.0 / 0.0.  It is possible to continue the computations with this value since the basic operations as well as the mathematical library functions are prepared to handle values like this.

     Beside INFINITY also the value -INFINITY is representable and it is handled differently if needed.  It is possible to test a value for infiniteness using a simple comparison but the recommended way is to use the the isinf function.

     This macro was introduced in the ISO C 9X standard.

The macros HUGE_VAL, HUGE_VALF and HUGE_VALL are defined in a similar way but they are not required to represent the infinite value, only a very large value (see Domain and Range Errors). If actually infinity is wanted, INFINITY should be used.

``Not a Number'' Values
=======================

The IEEE floating point format used by most modern computers supports values that are ``not a number''.  These values are called NaNs. ``Not a number'' values result from certain operations which have no meaningful numeric result, such as zero divided by zero or infinity divided by infinity.

One noteworthy property of NaNs is that they are not equal to themselves.  Thus, x == x can be 0 if the value of x is a NaN.  You can use this to test whether a value is a NaN or not: if it is not equal to itself, then it is a NaN.  But the recommended way to test for a NaN is with the isnan function (see Predicates on Floats).

Almost any arithmetic operation in which one argument is a NaN returns a NaN.

 -- Macro: double NAN
     An expression representing a value which is ``not a number''.  This macro is a GNU extension, available only on machines that support ``not a number'' values---that is to say, on all machines that support IEEE floating point.

     You can use #ifdef NAN to test whether the machine supports NaNs.  (Of course, you must arrange for GNU extensions to be visible, such as by defining _GNU_SOURCE, and then you must include math.h.)

Constructing complex Numbers
============================

To construct complex numbers it is necessary have a way to express the imaginary part of the numbers.  In mathematics one uses the symbol ``i'' to mark a number as imaginary.  For convenience the complex.h header defines two macros which allow to use a similar easy notation.

 -- Macro: float_t _Imaginary_I
     This macro is a (compiler specific) representation of the value ``1i''. I.e., it is the value for which

          _Imaginary_I * _Imaginary_I = -1

     One can use it to easily construct complex number like in

          3.0 - _Imaginary_I * 4.0

     which results in the complex number with a real part of 3.0 and a imaginary part -4.0.

A more intuitive approach is to use the following macro.

 -- Macro: float_t I
     This macro has exactly the same value as _Imaginary_I.  The problem is that the name I very easily can clash with macros or variables in programs and so it might be a good idea to avoid this name and stay at the safe side by using _Imaginary_I.

Predicates on Floats
====================

This section describes some miscellaneous test functions on doubles. Prototypes for these functions appear in math.h.  These are BSD functions, and thus are available if you define _BSD_SOURCE or _GNU_SOURCE.

 -- Function: int isinf (double X)
 -- Function: int isinff (float X)
 -- Function: int isinfl (long double X)
     This function returns -1 if X represents negative infinity, 1 if X represents positive infinity, and 0 otherwise.

 -- Function: int isnan (double X)
 -- Function: int isnanf (float X)
 -- Function: int isnanl (long double X)
     This function returns a nonzero value if X is a ``not a number'' value, and zero otherwise.  (You can just as well use X != X to get the same result).

 -- Function: int finite (double X)
 -- Function: int finitef (float X)
 -- Function: int finitel (long double X)
     This function returns a nonzero value if X is finite or a ``not a number'' value, and zero otherwise.

 -- Function: double infnan (int ERROR)
     This function is provided for compatibility with BSD.  The other mathematical functions use infnan to decide what to return on occasion of an error.  Its argument is an error code, EDOM or ERANGE; infnan returns a suitable value to indicate this with.  -ERANGE is also acceptable as an argument, and corresponds to -HUGE_VAL as a value.

     In the BSD library, on certain machines, infnan raises a fatal signal in all cases.  The GNU library does not do likewise, because that does not fit the ISO C specification.

Portability Note: The functions listed in this section are BSD extensions.

Floating-Point Number Classification Functions
==============================================

Instead of using the BSD specific functions from the last section it is better to use those in this section which are introduced in the ISO C 9X standard and are therefore widely available.

 -- Macro: int fpclassify (float-type X)
     This is a generic macro which works on all floating-point types and which returns a value of type int.  The possible values are:

     FP_NAN
          The floating-point number X is ``Not a Number'' (see Not a Number)

     FP_INFINITE
          The value of X is either plus or minus infinity (see Infinity)

     FP_ZERO
          The value of X is zero.  In floating-point formats like IEEE 754 where the zero value can be signed this value is also returned if X is minus zero.

     FP_SUBNORMAL
          Some floating-point formats (such as IEEE 754) allow floating-point numbers to be represented in a denormalized format.  This happens if the absolute value of the number is too small to be represented in the normal format.  FP_SUBNORMAL is returned for such values of X.

     FP_NORMAL
          This value is returned for all other cases which means the number is a plain floating-point number without special meaning.

     This macro is useful if more than property of a number must be tested.  If one only has to test for, e.g., a NaN value, there are function which are faster.

The remainder of this section introduces some more specific functions. They might be implemented faster than the call to fpclassify and if the actual need in the program is covered be these functions they should be used (and not fpclassify).

 -- Macro: int isfinite (float-type X)
     The value returned by this macro is nonzero if the value of X is not plus or minus infinity and not NaN.  I.e., it could be implemented as

          (fpclassify (x) != FP_NAN && fpclassify (x) != FP_INFINITE)

     isfinite is also implemented as a macro which can handle all floating-point types.  Programs should use this function instead of FINITE (see Predicates on Floats).

 -- Macro: int isnormal (float-type X)
     If isnormal returns a nonzero value the value or X is neither a NaN, infinity, zero, nor a denormalized number.  I.e., it could be implemented as

          (fpclassify (x) == FP_NORMAL)

 -- Macro: int isnan (float-type X)
     The situation with this macro is a bit complicated.  Here isnan is a macro which can handle all kinds of floating-point types.  It returns a nonzero value is X does not represent a NaN value and could be written like this

          (fpclassify (x) == FP_NAN)

     The complication is that there is a function of the same name and the same semantic defined for compatibility with BSD (see Predicates on Floats).  Fortunately this should not yield to problems in most cases since the macro and the function have the same semantic.  Should in a situation the function be absolutely necessary one can use

          (isnan) (x)

     to avoid the macro expansion.  Using the macro has two big advantages: it is more portable and one does not have to choose the right function among isnan, isnanf, and isnanl.

Projections, Conjugates, and Decomposing of Complex Numbers
===========================================================

This section lists functions performing some of the simple mathematical operations on complex numbers.  Using any of the function requires that the C compiler understands the complex keyword, introduced to the C language in the ISO C 9X standard.

The prototypes for all functions in this section can be found in complex.h.  All functions are available in three variants, one for each of the three floating-point types.

The easiest operation on complex numbers is the decomposition in the real part and the imaginary part.  This is done by the next two functions.

 -- Function: double creal (complex double Z)
 -- Function: float crealf (complex float Z)
 -- Function: long double creall (complex long double Z)
     These functions return the real part of the complex number Z.

 -- Function: double cimag (complex double Z)
 -- Function: float cimagf (complex float Z)
 -- Function: long double cimagl (complex long double Z)
     These functions return the imaginary part of the complex number Z.

The conjugate complex value of a given complex number has the same value for the real part but the complex part is negated.

 -- Function: complex double conj (complex double Z)
 -- Function: complex float conjf (complex float Z)
 -- Function: complex long double conjl (complex long double Z)
     These functions return the conjugate complex value of the complex number Z.

 -- Function: double carg (complex double Z)
 -- Function: float cargf (complex float Z)
 -- Function: long double cargl (complex long double Z)
     These functions return argument of the complex number Z.

     Mathematically, the argument is the phase angle of Z with a branch cut along the negative real axis.

 -- Function: complex double cproj (complex double Z)
 -- Function: complex float cprojf (complex float Z)
 -- Function: complex long double cprojl (complex long double Z)
     Return the projection of the complex value Z on the Riemann sphere.  Values with a infinite complex part (even if the real part is NaN) are projected to positive infinite on the real axis.  If the real part is infinite, the result is equivalent to

          INFINITY + I * copysign (0.0, cimag (z))

Absolute Value
==============

These functions are provided for obtaining the absolute value (or magnitude) of a number.  The absolute value of a real number X is X is X is positive, -X if X is negative.  For a complex number Z, whose real part is X and whose imaginary part is Y, the absolute value is sqrt (X*X + Y*Y).

Prototypes for abs and labs are in stdlib.h; fabs, fabsf and fabsl are declared in math.h; cabs, cabsf and cabsl are declared in complex.h.

 -- Function: int abs (int NUMBER)
     This function returns the absolute value of NUMBER.

     Most computers use a two's complement integer representation, in which the absolute value of INT_MIN (the smallest possible int) cannot be represented; thus, abs (INT_MIN) is not defined.

 -- Function: long int labs (long int NUMBER)
     This is similar to abs, except that both the argument and result are of type long int rather than int.

 -- Function: double fabs (double NUMBER)
 -- Function: float fabsf (float NUMBER)
 -- Function: long double fabsl (long double NUMBER)
     This function returns the absolute value of the floating-point number NUMBER.

 -- Function: double cabs (complex double Z)
 -- Function: float cabsf (complex float Z)
 -- Function: long double cabsl (complex long double Z)
     These functions return the absolute value of the complex number Z. The compiler must support complex numbers to use these functions.  The value is:

          sqrt (creal (Z) * creal (Z) + cimag (Z) * cimag (Z))

     This function should always be used instead of the direct formula since using the simple straight-forward method can mean to lose accuracy.  If one of the squared values is neglectable in size compared to the other value the result should be the same as the larger value.  But squaring the value and afterwards using the square root function leads to inaccuracy.  See hypot in see Exponents and Logarithms.

Normalization Functions
=======================

The functions described in this section are primarily provided as a way to efficiently perform certain low-level manipulations on floating point numbers that are represented internally using a binary radix; see Floating Point Concepts.  These functions are required to have equivalent behavior even if the representation does not use a radix of 2, but of course they are unlikely to be particularly efficient in those cases.

All these functions are declared in math.h.

 -- Function: double frexp (double VALUE, int *EXPONENT)
 -- Function: float frexpf (float VALUE, int *EXPONENT)
 -- Function: long double frexpl (long double VALUE, int *EXPONENT)
     These functions are used to split the number VALUE into a normalized fraction and an exponent.

     If the argument VALUE is not zero, the return value is VALUE times a power of two, and is always in the range 1/2 (inclusive) to 1 (exclusive).  The corresponding exponent is stored in *EXPONENT; the return value multiplied by 2 raised to this exponent equals the original number VALUE.

     For example, frexp (12.8, &exponent) returns 0.8 and stores 4 in exponent.

     If VALUE is zero, then the return value is zero and zero is stored in *EXPONENT.

 -- Function: double ldexp (double VALUE, int EXPONENT)
 -- Function: float ldexpf (float VALUE, int EXPONENT)
 -- Function: long double ldexpl (long double VALUE, int EXPONENT)
     These functions return the result of multiplying the floating-point number VALUE by 2 raised to the power EXPONENT.  (It can be used to reassemble floating-point numbers that were taken apart by frexp.)

     For example, ldexp (0.8, 4) returns 12.8.

The following functions which come from BSD provide facilities equivalent to those of ldexp and frexp:

 -- Function: double scalb (double VALUE, int EXPONENT)
 -- Function: float scalbf (float VALUE, int EXPONENT)
 -- Function: long double scalbl (long double VALUE, int EXPONENT)
     The scalb function is the BSD name for ldexp.

 -- Function: double logb (double X)
 -- Function: float logbf (float X)
 -- Function: long double logbl (long double X)
     These BSD functions return the integer part of the base-2 logarithm of X, an integer value represented in type double.  This is the highest integer power of 2 contained in X.  The sign of X is ignored.  For example, logb (3.5) is 1.0 and logb (4.0) is 2.0.

     When 2 raised to this power is divided into X, it gives a quotient between 1 (inclusive) and 2 (exclusive).

     If X is zero, the value is minus infinity (if the machine supports such a value), or else a very small number.  If X is infinity, the value is infinity.

     The value returned by logb is one less than the value that frexp would store into *EXPONENT.

 -- Function: double copysign (double VALUE, double SIGN)
 -- Function: float copysignf (float VALUE, float SIGN)
 -- Function: long double copysignl (long double VALUE, long double SIGN)
     These functions return a value whose absolute value is the same as that of VALUE, and whose sign matches that of SIGN. This function appears in BSD and was standardized in ISO C 9X.

 -- Function: int signbit (float-type X)
     signbit is a generic macro which can work on all floating-point types.  It returns a nonzero value if the value of X has its sign bit set.

     This is not the same as x < 0.0 since in some floating-point formats (e.g., IEEE 754) the zero value is optionally signed.  The comparison -0.0 < 0.0 will not be true while signbit (-0.0) will return a nonzero value.

Rounding and Remainder Functions
================================

The functions listed here perform operations such as rounding, truncation, and remainder in division of floating point numbers.  Some of these functions convert floating point numbers to integer values. They are all declared in math.h.

You can also convert floating-point numbers to integers simply by casting them to int.  This discards the fractional part, effectively rounding towards zero.  However, this only works if the result can actually be represented as an int---for very large numbers, this is impossible.  The functions listed here return the result as a double instead to get around this problem.

 -- Function: double ceil (double X)
 -- Function: float ceilf (float X)
 -- Function: long double ceill (long double X)
     These functions round X upwards to the nearest integer, returning that value as a double.  Thus, ceil (1.5) is 2.0.

 -- Function: double floor (double X)
 -- Function: float floorf (float X)
 -- Function: long double floorl (long double X)
     These functions round X downwards to the nearest integer, returning that value as a double.  Thus, floor (1.5) is 1.0 and floor (-1.5) is -2.0.

 -- Function: double rint (double X)
 -- Function: float rintf (float X)
 -- Function: long double rintl (long double X)
     These functions round X to an integer value according to the current rounding mode.  See Floating Point Parameters, for information about the various rounding modes.  The default rounding mode is to round to the nearest integer; some machines support other modes, but round-to-nearest is always used unless you explicit select another.

 -- Function: double nearbyint (double X)
 -- Function: float nearbyintf (float X)
 -- Function: long double nearbyintl (long double X)
     These functions return the same value as the rint functions but even some rounding actually takes place nearbyint does not raise the inexact exception.

 -- Function: double modf (double VALUE, double *INTEGER-PART)
 -- Function: float modff (float VALUE, float *INTEGER-PART)
 -- Function: long double modfl (long double VALUE, long double *INTEGER-PART)
     These functions break the argument VALUE into an integer part and a fractional part (between -1 and 1, exclusive).  Their sum equals VALUE.  Each of the parts has the same sign as VALUE, so the rounding of the integer part is towards zero.

     modf stores the integer part in *INTEGER-PART, and returns the fractional part.  For example, modf (2.5, &intpart) returns 0.5 and stores 2.0 into intpart.

 -- Function: double fmod (double NUMERATOR, double DENOMINATOR)
 -- Function: float fmodf (float NUMERATOR, float DENOMINATOR)
 -- Function: long double fmodl (long double NUMERATOR, long double DENOMINATOR)
     These functions compute the remainder from the division of NUMERATOR by DENOMINATOR.  Specifically, the return value is NUMERATOR - N * DENOMINATOR, where N is the quotient of NUMERATOR divided by DENOMINATOR, rounded towards zero to an integer.  Thus, fmod (6.5, 2.3) returns 1.9, which is 6.5 minus 4.6.

     The result has the same sign as the NUMERATOR and has magnitude less than the magnitude of the DENOMINATOR.

     If DENOMINATOR is zero, fmod fails and sets errno to EDOM.

 -- Function: double drem (double NUMERATOR, double DENOMINATOR)
 -- Function: float dremf (float NUMERATOR, float DENOMINATOR)
 -- Function: long double dreml (long double NUMERATOR, long double DENOMINATOR)
     These functions are like fmod etc except that it rounds the internal quotient N to the nearest integer instead of towards zero to an integer.  For example, drem (6.5, 2.3) returns -0.4, which is 6.5 minus 6.9.

     The absolute value of the result is less than or equal to half the absolute value of the DENOMINATOR.  The difference between fmod (NUMERATOR, DENOMINATOR) and drem (NUMERATOR, DENOMINATOR) is always either DENOMINATOR, minus DENOMINATOR, or zero.

     If DENOMINATOR is zero, drem fails and sets errno to EDOM.

Integer Division
================

This section describes functions for performing integer division.  These functions are redundant in the GNU C library, since in GNU C the / operator always rounds towards zero.  But in other C implementations, / may round differently with negative arguments.  div and ldiv are useful because they specify how to round the quotient: towards zero.  The remainder has the same sign as the numerator.

These functions are specified to return a result R such that the value R.quot*DENOMINATOR + R.rem equals NUMERATOR.

To use these facilities, you should include the header file stdlib.h in your program.

 -- Data Type: div_t
     This is a structure type used to hold the result returned by the div function.  It has the following members:

     int quot
          The quotient from the division.

     int rem
          The remainder from the division.

 -- Function: div_t div (int NUMERATOR, int DENOMINATOR)
     This function div computes the quotient and remainder from the division of NUMERATOR by DENOMINATOR, returning the result in a structure of type div_t.

     If the result cannot be represented (as in a division by zero), the behavior is undefined.

     Here is an example, albeit not a very useful one.

          div_t result;
          result = div (20, -6);

     Now result.quot is -3 and result.rem is 2.

 -- Data Type: ldiv_t
     This is a structure type used to hold the result returned by the ldiv function.  It has the following members:

     long int quot
          The quotient from the division.

     long int rem
          The remainder from the division.

     (This is identical to div_t except that the components are of type long int rather than int.)

 -- Function: ldiv_t ldiv (long int NUMERATOR, long int DENOMINATOR)
     The ldiv function is similar to div, except that the arguments are of type long int and the result is returned as a structure of type ldiv_t.

 -- Data Type: lldiv_t
     This is a structure type used to hold the result returned by the lldiv function.  It has the following members:

     long long int quot
          The quotient from the division.

     long long int rem
          The remainder from the division.

     (This is identical to div_t except that the components are of type long long int rather than int.)

 -- Function: lldiv_t lldiv (long long int NUMERATOR, long long int DENOMINATOR)
     The lldiv function is like the div function, but the arguments are of type long long int and the result is returned as a structure of type lldiv_t.

     The lldiv function is a GNU extension but it will eventually be part of the next ISO C standard.

Parsing of Numbers
==================

This section describes functions for ``reading'' integer and floating-point numbers from a string.  It may be more convenient in some cases to use sscanf or one of the related functions; see Formatted Input.  But often you can make a program more robust by finding the tokens in the string by hand, then converting the numbers one by one.

Parsing of Integers
-------------------

These functions are declared in stdlib.h.

 -- Function: long int strtol (const char *STRING, char **TAILPTR, int BASE)
     The strtol (``string-to-long'') function converts the initial part of STRING to a signed integer, which is returned as a value of type long int.

     This function attempts to decompose STRING as follows:

       * A (possibly empty) sequence of whitespace characters.  Which characters are whitespace is determined by the isspace function (see Classification of Characters).  These are discarded.

       * An optional plus or minus sign (+ or -).

       * A nonempty sequence of digits in the radix specified by BASE.

          If BASE is zero, decimal radix is assumed unless the series of digits begins with 0 (specifying octal radix), or 0x or 0X (specifying hexadecimal radix); in other words, the same syntax used for integer constants in C.

          Otherwise BASE must have a value between 2 and 35. If BASE is 16, the digits may optionally be preceded by 0x or 0X.  If base has no legal value the value returned is 0l and the global variable errno is set to EINVAL.

       * Any remaining characters in the string.  If TAILPTR is not a null pointer, strtol stores a pointer to this tail in *TAILPTR.

     If the string is empty, contains only whitespace, or does not contain an initial substring that has the expected syntax for an integer in the specified BASE, no conversion is performed.  In this case, strtol returns a value of zero and the value stored in *TAILPTR is the value of STRING.

     In a locale other than the standard "C" locale, this function may recognize additional implementation-dependent syntax.

     If the string has valid syntax for an integer but the value is not representable because of overflow, strtol returns either LONG_MAX or LONG_MIN (see Range of Type), as appropriate for the sign of the value.  It also sets errno to ERANGE to indicate there was overflow.

     Because the value 0l is a correct result for strtol the user who is interested in handling errors should set the global variable errno to 0 before calling this function, so that the program can later test whether an error occurred.

     There is an example at the end of this section.

 -- Function: unsigned long int strtoul (const char *STRING, char **TAILPTR, int BASE)
     The strtoul (``string-to-unsigned-long'') function is like strtol except it deals with unsigned numbers, and returns its value with type unsigned long int.  No + or - sign may appear before the number, but the syntax is otherwise the same as described above for strtol.  The value returned in case of overflow is ULONG_MAX (see Range of Type).

     Like strtol this function sets errno and returns the value 0ul in case the value for BASE is not in the legal range. For strtoul this can happen in another situation.  In case the number to be converted is negative strtoul also sets errno to EINVAL and returns 0ul.

 -- Function: long long int strtoll (const char *STRING, char **TAILPTR, int BASE)
     The strtoll function is like strtol except that is deals with extra long numbers and it returns its value with type long long int.

     If the string has valid syntax for an integer but the value is not representable because of overflow, strtoll returns either LONG_LONG_MAX or LONG_LONG_MIN (see Range of Type), as appropriate for the sign of the value.  It also sets errno to ERANGE to indicate there was overflow.

     The strtoll function is a GNU extension but it will eventually be part of the next ISO C standard.

 -- Function: long long int strtoq (const char *STRING, char **TAILPTR, int BASE)
     strtoq (``string-to-quad-word'') is only an commonly used other name for the strtoll function.  Everything said for strtoll applies to strtoq as well.

 -- Function: unsigned long long int strtoull (const char *STRING, char **TAILPTR, int BASE)
     The strtoull function is like strtoul except that is deals with extra long numbers and it returns its value with type unsigned long long int.  The value returned in case of overflow is ULONG_LONG_MAX (see Range of Type).

     The strtoull function is a GNU extension but it will eventually be part of the next ISO C standard.

 -- Function: unsigned long long int strtouq (const char *STRING, char **TAILPTR, int BASE)
     strtouq (``string-to-unsigned-quad-word'') is only an commonly used other name for the strtoull function.  Everything said for strtoull applies to strtouq as well.

 -- Function: long int atol (const char *STRING)
     This function is similar to the strtol function with a BASE argument of 10, except that it need not detect overflow errors. The atol function is provided mostly for compatibility with existing code; using strtol is more robust.

 -- Function: int atoi (const char *STRING)
     This function is like atol, except that it returns an int value rather than long int.  The atoi function is also considered obsolete; use strtol instead.

 -- Function: long long int atoll (const char *STRING)
     This function is similar to atol, except it returns a long long int value rather than long int.

     The atoll function is a GNU extension but it will eventually be part of the next ISO C standard.

The POSIX locales contain some information about how to format numbers (see General Numeric).  This mainly deals with representing numbers for better readability for humans.  The functions present so far in this section cannot handle numbers in this form.

If this functionality is needed in a program one can use the functions from the scanf family which know about the flag ' for parsing numeric input (see Numeric Input Conversions).  Sometimes it is more desirable to have finer control.

In these situation one could use the function __strtoXXX_internal.  XXX here stands for any of the above forms.  All numeric conversion functions (including the functions to process floating-point numbers) have such a counterpart.  The difference to the normal form is the extra argument at the end of the parameter list.  If this value has an non-zero value the handling of number grouping is enabled.  The advantage of using these functions is that the TAILPTR parameters allow to determine which part of the input is processed.  The scanf functions don't provide this information.  The drawback of using these functions is that they are not portable.  They only exist in the GNU C library.

Here is a function which parses a string as a sequence of integers and returns the sum of them:

     int
     sum_ints_from_string (char *string)
     {
       int sum = 0;

       while (1) {
         char *tail;
         int next;

         /* Skip whitespace by hand, to detect the end.  */
         while (isspace (*string)) string++;
         if (*string == 0)
           break;

         /* There is more nonwhitespace,  */
         /* so it ought to be another number.  */
         errno = 0;
         /* Parse it.  */
         next = strtol (string, &tail, 0);
         /* Add it in, if not overflow.  */
         if (errno)
           printf ("Overflow\n");
         else
           sum += next;
         /* Advance past it.  */
         string = tail;
       }

       return sum;
     }

Parsing of Floats
-----------------

These functions are declared in stdlib.h.

 -- Function: double strtod (const char *STRING, char **TAILPTR)
     The strtod (``string-to-double'') function converts the initial part of STRING to a floating-point number, which is returned as a value of type double.

     This function attempts to decompose STRING as follows:

       * A (possibly empty) sequence of whitespace characters.  Which characters are whitespace is determined by the isspace function (see Classification of Characters).  These are discarded.

       * An optional plus or minus sign (+ or -).

       * A nonempty sequence of digits optionally containing a decimal-point character---normally ., but it depends on the locale (see Numeric Formatting).

       * An optional exponent part, consisting of a character e or E, an optional sign, and a sequence of digits.

       * Any remaining characters in the string.  If TAILPTR is not a null pointer, a pointer to this tail of the string is stored in *TAILPTR.

     If the string is empty, contains only whitespace, or does not contain an initial substring that has the expected syntax for a floating-point number, no conversion is performed.  In this case, strtod returns a value of zero and the value returned in *TAILPTR is the value of STRING.

     In a locale other than the standard "C" or "POSIX" locales, this function may recognize additional locale-dependent syntax.

     If the string has valid syntax for a floating-point number but the value is not representable because of overflow, strtod returns either positive or negative HUGE_VAL (see Mathematics), depending on the sign of the value.  Similarly, if the value is not representable because of underflow, strtod returns zero.  It also sets errno to ERANGE if there was overflow or underflow.

     There are two more special inputs which are recognized by strtod. The string "inf" or "infinity" (without consideration of case and optionally preceded by a "+" or "-" sign) is changed to the floating-point value for infinity if the floating-point format supports this; and to the largest representable value otherwise.

     If the input string is "nan" or "nan(N-CHAR-SEQUENCE)" the return value of strtod is the representation of the NaN (not a number) value (if the floating-point format supports this).  In the second form the part N-CHAR-SEQUENCE allows to specify the form of the NaN value in an implementation specific way.  When using the IEEE 754 floating-point format, the NaN value can have a lot of forms since only at least one bit in the mantissa must be set.  In the GNU C library implementation of strtod the N-CHAR-SEQUENCE is interpreted as a number (as recognized by strtol, see Parsing of Integers). The mantissa of the return value corresponds to this given number.

     Since the value zero which is returned in the error case is also a valid result the user should set the global variable errno to zero before calling this function.  So one can test for failures after the call since all failures set errno to a non-zero value.

 -- Function: float strtof (const char *STRING, char **TAILPTR)
     This function is similar to the strtod function but it returns a float value instead of a double value.  If the precision of a float value is sufficient this function should be used since it is much faster than strtod on some architectures.  The reasons are obvious: IEEE 754 defines float to have a mantissa of 23 bits while double has 53 bits and every additional bit of precision can require additional computation.

     If the string has valid syntax for a floating-point number but the value is not representable because of overflow, strtof returns either positive or negative HUGE_VALF (see Mathematics), depending on the sign of the value.

     This function is a GNU extension.

 -- Function: long double strtold (const char *STRING, char **TAILPTR)
     This function is similar to the strtod function but it returns a long double value instead of a double value.  It should be used when high precision is needed.  On systems which define a long double type (i.e., on which it is not the same as double) running this function might take significantly more time since more bits of precision are required.

     If the string has valid syntax for a floating-point number but the value is not representable because of overflow, strtold returns either positive or negative HUGE_VALL (see Mathematics), depending on the sign of the value.

     This function is a GNU extension.

As for the integer parsing functions there are additional functions which will handle numbers represented using the grouping scheme of the current locale (see Parsing of Integers).

 -- Function: double atof (const char *STRING)
     This function is similar to the strtod function, except that it need not detect overflow and underflow errors.  The atof function is provided mostly for compatibility with existing code; using strtod is more robust.