@Go to the ‰ŠP�”›first@�”˜, ‰ŠP�”›previous@�”˜, ‰ŠP�”›next@�”˜, ‰ŠP�”›last@�”˜ section, ‰ŠP�”›table of contents@�”˜.
Œ

ˆ‰SEC262Št�”›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. These functions are declared in the header file H`math.h'@.
ˆ‰SEC263Št�”›"Not a Number" Values

‰IDX1334Š‰IDX1335Š‰IDX1336Š
@�”˜The IEEE floating point format used by most modern computers supports values that are "not a number". These values are called BNaNs@. "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, Hx == x@ can be 0 if the value of Hx@ 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 Hisnan@ function (see section ‰ŠP�”›Predicates on Floats@�”˜).
Almost any arithmetic operation in which one argument is a NaN returns a NaN.

AMacro:@ double DNAN
Â‰IDX1337Š@�”˜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 H`#ifdef NAN'@ to test whether the machine supports NaNs. (Of course, you must arrange for GNU extensions to be visible, such as by defining H_GNU_SOURCE@, and then you must include H`math.h'@.)À

ˆ‰SEC264Št�”›Predicates on Floats

‰IDX1338Š@�”˜This section describes some miscellaneous test functions on doubles. Prototypes for these functions appear in H`math.h'@. These are BSD functions, and thus are available if you define H_BSD_SOURCE@ or H_GNU_SOURCE@.

AFunction:@ int Disinf@ B(double Bx@)
Â‰IDX1339Š@�”˜This function returns H-1@ if Bx@ represents negative infinity, H1@ if Bx@ represents positive infinity, and H0@ otherwise.À

AFunction:@ int Disnan@ B(double Bx@)
Â‰IDX1340Š@�”˜This function returns a nonzero value if Bx@ is a "not a number" value, and zero otherwise. (You can just as well use JxH != Jx@ to get the same result).À

AFunction:@ int Dfinite@ B(double Bx@)
Â‰IDX1341Š@�”˜This function returns a nonzero value if Bx@ is finite or a "not a number" value, and zero otherwise.À

AFunction:@ double Dinfnan@ B(int Berror@)
Â‰IDX1342Š@�”˜This function is provided for compatibility with BSD. The other mathematical functions use Hinfnan@ to decide what to return on occasion of an error. Its argument is an error code, HEDOM@ or HERANGE@; Hinfnan@ returns a suitable value to indicate this with. H-ERANGE@ is also acceptable as an argument, and corresponds to H-HUGE_VAL@ as a value.
In the BSD library, on certain machines, Hinfnan@ raises a fatal signal in all cases. The GNU library does not do likewise, because that does not fit the ISO C specification.À

DPortability Note:@ The functions listed in this section are BSD extensions.
ˆ‰SEC265Št�”›Absolute Value

‰IDX1343Š
@�”˜These functions are provided for obtaining the Babsolute value@ (or Bmagnitude@) of a number. The absolute value of a real number Bx@ is Bx@ is Bx@ is positive, -Bx@ if Bx@ is negative. For a complex number Bz@, whose real part is Bx@ and whose imaginary part is By@, the absolute value is Hsqrt (JxH*JxH + JyH*JyH)@.
‰IDX1344Š‰IDX1345Š@�”˜Prototypes for Habs@ and Hlabs@ are in H`stdlib.h'@; Hfabs@ and Hcabs@ are declared in H`math.h'@.

AFunction:@ int Dabs@ B(int Bnumber@)
Â‰IDX1346Š@�”˜This function returns the absolute value of Bnumber@.
Most computers use a two's complement integer representation, in which the absolute value of HINT_MIN@ (the smallest possible Hint@) cannot be represented; thus, Habs (INT_MIN)@ is not defined.À

AFunction:@ long int Dlabs@ B(long int Bnumber@)
Â‰IDX1347Š@�”˜This is similar to Habs@, except that both the argument and result are of type Hlong int@ rather than Hint@.À

AFunction:@ double Dfabs@ B(double Bnumber@)
Â‰IDX1348Š@�”˜This function returns the absolute value of the floating-point number Bnumber@.À

AFunction:@ double Dcabs@ B(struct { double real, imag; } Bz@)
Â‰IDX1349Š@�”˜The Hcabs@ function returns the absolute value of the complex number Bz@, whose real part is JzH.real@ and whose imaginary part is JzH.imag@. (See also the function Hhypot@ in section ‰ŠP�”›Exponentiation and Logarithms@�”˜.) The value is: sqrt (Bz@.real*Bz@.real + Bz@.imag*Bz@.imag) À

ˆ‰SEC266Št�”›Normalization Functions

‰IDX1350Š
@�”˜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 section ‰ŠP�”›Floating Point Representation 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.
‰IDX1351Š@�”˜All these functions are declared in H`math.h'@.

AFunction:@ double Dfrexp@ B(double Bvalue@, int *Bexponent@)
Â‰IDX1352Š@�”˜The Hfrexp@ function is used to split the number Bvalue@ into a normalized fraction and an exponent.
If the argument Bvalue@ is not zero, the return value is Bvalue@ times a power of two, and is always in the range 1/2 (inclusive) to 1 (exclusive). The corresponding exponent is stored in H*Jexponent@; the return value multiplied by 2 raised to this exponent equals the original number Bvalue@.
For example, Hfrexp (12.8, &exponent)@ returns H0.8@ and stores H4@ in Hexponent@.
If Bvalue@ is zero, then the return value is zero and zero is stored in H*Jexponent@.À

AFunction:@ double Dldexp@ B(double Bvalue@, int Bexponent@)
Â‰IDX1353Š@�”˜This function returns the result of multiplying the floating-point number Bvalue@ by 2 raised to the power Bexponent@. (It can be used to reassemble floating-point numbers that were taken apart by Hfrexp@.)
For example, Hldexp (0.8, 4)@ returns H12.8@.À

The following functions which come from BSD provide facilities equivalent to those of Hldexp@ and Hfrexp@:

AFunction:@ double Dscalb@ B(double Bvalue@, int Bexponent@)
Â‰IDX1354Š@�”˜The Hscalb@ function is the BSD name for Hldexp@.À

AFunction:@ double Dlogb@ B(double Bx@)
Â‰IDX1355Š@�”˜This BSD function returns the integer part of the base-2 logarithm of Bx@, an integer value represented in type Hdouble@. This is the highest integer power of H2@ contained in Bx@. The sign of Bx@ is ignored. For example, Hlogb (3.5)@ is H1.0@ and Hlogb (4.0)@ is H2.0@.
When H2@ raised to this power is divided into Bx@, it gives a quotient between H1@ (inclusive) and H2@ (exclusive).
If Bx@ is zero, the value is minus infinity (if the machine supports such a value), or else a very small number. If Bx@ is infinity, the value is infinity.
The value returned by Hlogb@ is one less than the value that Hfrexp@ would store into H*Jexponent@.À

AFunction:@ double Dcopysign@ B(double Bvalue@, double Bsign@)
Â‰IDX1356Š@�”˜The Hcopysign@ function returns a value whose absolute value is the same as that of Bvalue@, and whose sign matches that of Bsign@. This is a BSD function.À

ˆ‰SEC267Št�”›Rounding and Remainder Functions

‰IDX1357Š‰IDX1358Š‰IDX1359Š
‰IDX1360Š@�”˜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 H`math.h'@.
You can also convert floating-point numbers to integers simply by casting them to Hint@. This discards the fractional part, effectively rounding towards zero. However, this only works if the result can actually be represented as an Hint@---for very large numbers, this is impossible. The functions listed here return the result as a Hdouble@ instead to get around this problem.

AFunction:@ double Dceil@ B(double Bx@)
Â‰IDX1361Š@�”˜The Hceil@ function rounds Bx@ upwards to the nearest integer, returning that value as a Hdouble@. Thus, Hceil (1.5)@ is H2.0@.À

AFunction:@ double Dfloor@ B(double Bx@)
Â‰IDX1362Š@�”˜The Hceil@ function rounds Bx@ downwards to the nearest integer, returning that value as a Hdouble@. Thus, Hfloor (1.5)@ is H1.0@ and Hfloor (-1.5)@ is H-2.0@.À

AFunction:@ double Drint@ B(double Bx@)
Â‰IDX1363Š@�”˜This function rounds Bx@ to an integer value according to the current rounding mode. See section ‰ŠP�”›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.À

AFunction:@ double Dmodf@ B(double Bvalue@, double *Binteger-part@)
Â‰IDX1364Š@�”˜This function breaks the argument Bvalue@ into an integer part and a fractional part (between H-1@ and H1@, exclusive). Their sum equals Bvalue@. Each of the parts has the same sign as Bvalue@, so the rounding of the integer part is towards zero.
Hmodf@ stores the integer part in H*Jinteger-part@, and returns the fractional part. For example, Hmodf (2.5, &intpart)@ returns H0.5@ and stores H2.0@ into Hintpart@.À

AFunction:@ double Dfmod@ B(double Bnumerator@, double Bdenominator@)
Â‰IDX1365Š@�”˜This function computes the remainder from the division of Bnumerator@ by Bdenominator@. Specifically, the return value is JnumeratorH - JnH * Jdenominator@, where Bn@ is the quotient of Bnumerator@ divided by Bdenominator@, rounded towards zero to an integer. Thus, Hfmod (6.5, 2.3)@ returns H1.9@, which is H6.5@ minus H4.6@.
The result has the same sign as the Bnumerator@ and has magnitude less than the magnitude of the Bdenominator@.
If Bdenominator@ is zero, Hfmod@ fails and sets Herrno@ to HEDOM@.À

AFunction:@ double Ddrem@ B(double Bnumerator@, double Bdenominator@)
Â‰IDX1366Š@�”˜The function Hdrem@ is like Hfmod@ except that it rounds the internal quotient Bn@ to the nearest integer instead of towards zero to an integer. For example, Hdrem (6.5, 2.3)@ returns H-0.4@, which is H6.5@ minus H6.9@.
The absolute value of the result is less than or equal to half the absolute value of the Bdenominator@. The difference between Hfmod (JnumeratorH, JdenominatorH)@ and Hdrem (JnumeratorH, JdenominatorH)@ is always either Bdenominator@, minus Bdenominator@, or zero.
If Bdenominator@ is zero, Hdrem@ fails and sets Herrno@ to HEDOM@.À

ˆ‰SEC268Št�”›Integer Division

‰IDX1367Š
@�”˜This section describes functions for performing integer division. These functions are redundant in the GNU C library, since in GNU C the H`/'@ operator always rounds towards zero. But in other C implementations, H`/'@ may round differently with negative arguments. Hdiv@ and Hldiv@ 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 Br@ such that the value JrH.quot*JdenominatorH + JrH.rem@ equals Bnumerator@.
‰IDX1368Š@�”˜To use these facilities, you should include the header file H`stdlib.h'@ in your program.

AData Type:@ Ddiv_t
Â‰IDX1369Š@�”˜This is a structure type used to hold the result returned by the Hdiv@ function. It has the following members:
Hint quot
Ä@The quotient from the division.
ÂHint rem
Ä@The remainder from the division.Â
À

AFunction:@ div_t Ddiv@ B(int Bnumerator@, int Bdenominator@)
Â‰IDX1370Š@�”˜This function Hdiv@ computes the quotient and remainder from the division of Bnumerator@ by Bdenominator@, returning the result in a structure of type Hdiv_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 Hresult.quot@ is H-3@ and Hresult.rem@ is H2@.À

AData Type:@ Dldiv_t
Â‰IDX1371Š@�”˜This is a structure type used to hold the result returned by the Hldiv@ function. It has the following members:
Hlong int quot
Ä@The quotient from the division.
ÂHlong int rem
Ä@The remainder from the division.Â

(This is identical to Hdiv_t@ except that the components are of type Hlong int@ rather than Hint@.)À

AFunction:@ ldiv_t Dldiv@ B(long int Bnumerator@, long int Bdenominator@)
Â‰IDX1372Š@�”˜The Hldiv@ function is similar to Hdiv@, except that the arguments are of type Hlong int@ and the result is returned as a structure of type Hldiv@.À

ˆ‰SEC269Št�”›Parsing of Numbers

‰IDX1373Š‰IDX1374Š‰IDX1375Š‰IDX1376Š
@�”˜This section describes functions for "reading" integer and floating-point numbers from a string. It may be more convenient in some cases to use Hsscanf@ or one of the related functions; see section ‰ŠP�”›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.
ˆ‰SEC270ŠT�”›Parsing of Integers

‰IDX1377Š@�”˜These functions are declared in H`stdlib.h'@.

AFunction:@ long int Dstrtol@ B(const char *Bstring@, char **Btailptr@, int Bbase@)
Â‰IDX1378Š@�”˜The Hstrtol@ ("string-to-long") function converts the initial part of Bstring@ to a signed integer, which is returned as a value of type Hlong int@.
This function attempts to decompose Bstring@ as follows: þÄ
• A (possibly empty) sequence of whitespace characters. Which characters are whitespace is determined by the Hisspace@ function (see section ‰ŠP�”›Classification of Characters@�”˜). These are discarded.
• An optional plus or minus sign (H`+'@ or H`-'@).
• A nonempty sequence of digits in the radix specified by Bbase@. If Bbase@ is zero, decimal radix is assumed unless the series of digits begins with H`0'@ (specifying octal radix), or H`0x'@ or H`0X'@ (specifying hexadecimal radix); in other words, the same syntax used for integer constants in C. Otherwise Bbase@ must have a value between H2@ and H35@. If Bbase@ is H16@, the digits may optionally be preceded by H`0x'@ or H`0X'@. If base has no legal value the value returned is H0l@ and the global variable Herrno@ is set to HEINVAL@.
• Any remaining characters in the string. If Btailptr@ is not a null pointer, Hstrtol@ stores a pointer to this tail in H*Jtailptr@.Âð
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 Bbase@, no conversion is performed. In this case, Hstrtol@ returns a value of zero and the value stored in H*Jtailptr@ is the value of Bstring@.
In a locale other than the standard H"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, Hstrtol@ returns either HLONG_MAX@ or HLONG_MIN@ (see section ‰ŠP�”›Range of an Integer Type@�”˜), as appropriate for the sign of the value. It also sets Herrno@ to HERANGE@ to indicate there was overflow.
Because the value H0l@ is a correct result for Hstrtol@ the user who is interested in handling errors should set the global variable Herrno@ to H0@ 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.À

AFunction:@ unsigned long int Dstrtoul@ B(const char *Bstring@, char **Btailptr@, int Bbase@)
Â‰IDX1379Š@�”˜The Hstrtoul@ ("string-to-unsigned-long") function is like Hstrtol@ except it deals with unsigned numbers, and returns its value with type Hunsigned long int@. No H`+'@ or H`-'@ sign may appear before the number, but the syntax is otherwise the same as described above for Hstrtol@. The value returned in case of overflow is HULONG_MAX@ (see section ‰ŠP�”›Range of an Integer Type@�”˜).
Like Hstrtol@ this function sets Herrno@ and returns the value H0ul@ in case the value for Bbase@ is not in the legal range. For Hstrtoul@ this can happen in another situation. In case the number to be converted is negative Hstrtoul@ also sets Herrno@ to HEINVAL@ and returns H0ul@.À

AFunction:@ long long int Dstrtoq@ B(const char *Bstring@, char **Btailptr@, int Bbase@)
Â‰IDX1380Š@�”˜The Hstrtoq@ ("string-to-quad-word") function is like Hstrtol@ except that is deals with extra long numbers and it returns its value with type Hlong long int@.
If the string has valid syntax for an integer but the value is not representable because of overflow, Hstrtoq@ returns either HLONG_LONG_MAX@ or HLONG_LONG_MIN@ (see section ‰ŠP�”›Range of an Integer Type@�”˜), as appropriate for the sign of the value. It also sets Herrno@ to HERANGE@ to indicate there was overflow.À

AFunction:@ long long int Dstrtoll@ B(const char *Bstring@, char **Btailptr@, int Bbase@)
Â‰IDX1381ŠH�”˜strtoll@ is only an commonly used other name for the Hstrtoq@ function. Everything said for Hstrtoq@ applies to Hstrtoll@ as well.À

AFunction:@ unsigned long long int Dstrtouq@ B(const char *Bstring@, char **Btailptr@, int Bbase@)
Â‰IDX1382Š@�”˜The Hstrtouq@ ("string-to-unsigned-quad-word") function is like Hstrtoul@ except that is deals with extra long numbers and it returns its value with type Hunsigned long long int@. The value returned in case of overflow is HULONG_LONG_MAX@ (see section ‰ŠP�”›Range of an Integer Type@�”˜).À

AFunction:@ unsigned long long int Dstrtoull@ B(const char *Bstring@, char **Btailptr@, int Bbase@)
Â‰IDX1383ŠH�”˜strtoull@ is only an commonly used other name for the Hstrtouq@ function. Everything said for Hstrtouq@ applies to Hstrtoull@ as well.À

AFunction:@ long int Datol@ B(const char *Bstring@)
Â‰IDX1384Š@�”˜This function is similar to the Hstrtol@ function with a Bbase@ argument of H10@, except that it need not detect overflow errors. The Hatol@ function is provided mostly for compatibility with existing code; using Hstrtol@ is more robust.À

AFunction:@ int Datoi@ B(const char *Bstring@)
Â‰IDX1385Š@�”˜This function is like Hatol@, except that it returns an Hint@ value rather than Hlong int@. The Hatoi@ function is also considered obsolete; use Hstrtol@ instead.À

The POSIX locales contain some information about how to format numbers (see section ‰ŠP�”›Generic Numeric Formatting Parameters@�”˜). 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 Hscanf@ family which know about the flag H`''@ for parsing numeric input (see section ‰ŠP�”›Numeric Input Conversions@�”˜). Sometimes it is more desirable to have finer control.
In these situation one could use the function H__strtoJXXXH_internal@. BXXX@ 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 Btailptr@ parameters allow to determine which part of the input is processed. The Hscanf@ 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;
}
ˆ‰SEC271ŠT�”›Parsing of Floats

‰IDX1386Š@�”˜These functions are declared in H`stdlib.h'@.

AFunction:@ double Dstrtod@ B(const char *Bstring@, char **Btailptr@)
Â‰IDX1387Š@�”˜The Hstrtod@ ("string-to-double") function converts the initial part of Bstring@ to a floating-point number, which is returned as a value of type Hdouble@.
This function attempts to decompose Bstring@ as follows: þÄ
• A (possibly empty) sequence of whitespace characters. Which characters are whitespace is determined by the Hisspace@ function (see section ‰ŠP�”›Classification of Characters@�”˜). These are discarded.
• An optional plus or minus sign (H`+'@ or H`-'@).
• A nonempty sequence of digits optionally containing a decimal-point character--normally H`.'@, but it depends on the locale (see section ‰ŠP�”›Numeric Formatting@�”˜).
• An optional exponent part, consisting of a character H`e'@ or H`E'@, an optional sign, and a sequence of digits.
• Any remaining characters in the string. If Btailptr@ is not a null pointer, a pointer to this tail of the string is stored in H*Jtailptr@.Âð
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, Hstrtod@ returns a value of zero and the value returned in H*Jtailptr@ is the value of Bstring@.
In a locale other than the standard H"C"@ or H"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, Hstrtod@ returns either positive or negative HHUGE_VAL@ (see section ‰ŠP�”›Mathematics@�”˜), depending on the sign of the value. Similarly, if the value is not representable because of underflow, Hstrtod@ returns zero. It also sets Herrno@ to HERANGE@ if there was overflow or underflow.
Since the value zero which is returned in the error case is also a valid result the user should set the global variable Herrno@ to zero before calling this function. So one can test for failures after the call since all failures set Herrno@ to a non-zero value.À

AFunction:@ float Dstrtof@ B(const char *Bstring@, char **Btailptr@)
Â‰IDX1388Š@�”˜This function is similar to the Hstrtod@ function but it returns a Hfloat@ value instead of a Hdouble@ value. If the precision of a Hfloat@ value is sufficient this function should be used since it is much faster than Hstrtod@ on some architectures. The reasons are obvious: IEEE 754 defines Hfloat@ to have a mantissa of 23 bits while Hdouble@ 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, Hstrtof@ returns either positive or negative HHUGE_VALf@ (see section ‰ŠP�”›Mathematics@�”˜), depending on the sign of the value.
This function is a GNU extension.À

AFunction:@ long double Dstrtold@ B(const char *Bstring@, char **Btailptr@)
Â‰IDX1389Š@�”˜This function is similar to the Hstrtod@ function but it returns a Hlong double@ value instead of a Hdouble@ value. It should be used when high precision is needed. On systems which define a Hlong double@ type (i.e., on which it is not the same as Hdouble@) 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, Hstrtold@ returns either positive or negative HHUGE_VALl@ (see section ‰ŠP�”›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 section ‰ŠP�”›Parsing of Integers@�”˜).

AFunction:@ double Datof@ B(const char *Bstring@)
Â‰IDX1390Š@�”˜This function is similar to the Hstrtod@ function, except that it need not detect overflow and underflow errors. The Hatof@ function is provided mostly for compatibility with existing code; using Hstrtod@ is more robust.À

Œ
Go to the ‰ŠP�”›first@�”˜, ‰ŠP�”›previous@�”˜, ‰ŠP�”›next@�”˜, ‰ŠP�”›last@�”˜ section, ‰ŠP�”›table of contents@�”˜.