<!-- This HTML file has been created by texi2html 1.27
     from library.texinfo on 3 March 1994 -->

<TITLE>The GNU C Library - Low-Level Arithmetic Functions</TITLE>
<P>Go to the <A HREF="library_17.html" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_17.html">previous</A>, <A HREF="library_19.html" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_19.html">next</A> section.<P>
<H1><A NAME="SEC299" HREF="library_toc.html#SEC299" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC299">Low-Level Arithmetic Functions</A></H1>
<P>
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
<TT>`math.h'</TT>.
<P>
<A NAME="IDX1294"></A>
<A NAME="IDX1295"></A>
<A NAME="IDX1296"></A>
<H2><A NAME="SEC300" HREF="library_toc.html#SEC300" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC300">"Not a Number" Values</A></H2>
<P>
The IEEE floating point format used by most modern computers supports
values that are "not a number".  These values are called <DFN>NaNs</DFN>.
"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.
<P>
One noteworthy property of NaNs is that they are not equal to
themselves.  Thus, <CODE>x == x</CODE> can be 0 if the value of <CODE>x</CODE> 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 <CODE>isnan</CODE> function (see section <A HREF="library_18.html#SEC301" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_18.html#SEC301">Predicates on Floats</A>).
<P>
Almost any arithmetic operation in which one argument is a NaN returns
a NaN.
<P>
<A NAME="IDX1297"></A>
<U>Macro:</U> double <B>NAN</B><P>
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.
<P>
You can use <SAMP>`#ifdef NAN'</SAMP> to test whether the machine supports
NaNs.  (Of course, you must arrange for GNU extensions to be visible,
such as by defining <CODE>_GNU_SOURCE</CODE>, and then you must include
<TT>`math.h'</TT>.)
<P>
<H2><A NAME="SEC301" HREF="library_toc.html#SEC301" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC301">Predicates on Floats</A></H2>
<A NAME="IDX1298"></A>
<P>
This section describes some miscellaneous test functions on doubles.
Prototypes for these functions appear in <TT>`math.h'</TT>.  These are BSD
functions, and thus are available if you define <CODE>_BSD_SOURCE</CODE> or
<CODE>_GNU_SOURCE</CODE>.
<P>
<A NAME="IDX1299"></A>
<U>Function:</U> int <B>isinf</B> <I>(double <VAR>x</VAR>)</I><P>
This function returns <CODE>-1</CODE> if <VAR>x</VAR> represents negative infinity,
<CODE>1</CODE> if <VAR>x</VAR> represents positive infinity, and <CODE>0</CODE> otherwise.
<P>
<A NAME="IDX1300"></A>
<U>Function:</U> int <B>isnan</B> <I>(double <VAR>x</VAR>)</I><P>
This function returns a nonzero value if <VAR>x</VAR> is a "not a number"
value, and zero otherwise.  (You can just as well use <CODE><VAR>x</VAR> !=
<VAR>x</VAR></CODE> to get the same result).
<P>
<A NAME="IDX1301"></A>
<U>Function:</U> int <B>finite</B> <I>(double <VAR>x</VAR>)</I><P>
This function returns a nonzero value if <VAR>x</VAR> is finite or a "not a
number" value, and zero otherwise.
<P>
<A NAME="IDX1302"></A>
<U>Function:</U> double <B>infnan</B> <I>(int <VAR>error</VAR>)</I><P>
This function is provided for compatibility with BSD.  The other
mathematical functions use <CODE>infnan</CODE> to decide what to return on
occasion of an error.  Its argument is an error code, <CODE>EDOM</CODE> or
<CODE>ERANGE</CODE>; <CODE>infnan</CODE> returns a suitable value to indicate this
with.  <CODE>-ERANGE</CODE> is also acceptable as an argument, and corresponds
to <CODE>-HUGE_VAL</CODE> as a value.
<P>
In the BSD library, on certain machines, <CODE>infnan</CODE> raises a fatal
signal in all cases.  The GNU library does not do likewise, because that
does not fit the ANSI C specification.
<P>
<STRONG>Portability Note:</STRONG> The functions listed in this section are BSD
extensions.
<P>
<A NAME="IDX1303"></A>
<H2><A NAME="SEC302" HREF="library_toc.html#SEC302" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC302">Absolute Value</A></H2>
<P>
These functions are provided for obtaining the <DFN>absolute value</DFN> (or
<DFN>magnitude</DFN>) of a number.  The absolute value of a real number
<VAR>x</VAR> is <VAR>x</VAR> is <VAR>x</VAR> is positive, -<VAR>x</VAR> if <VAR>x</VAR> is
negative.  For a complex number <VAR>z</VAR>, whose real part is <VAR>x</VAR> and
whose imaginary part is <VAR>y</VAR>, the absolute value is <CODE>sqrt
(<VAR>x</VAR>*<VAR>x</VAR> + <VAR>y</VAR>*<VAR>y</VAR>)</CODE>.
<A NAME="IDX1304"></A>
<A NAME="IDX1305"></A>
<P>
Prototypes for <CODE>abs</CODE> and <CODE>labs</CODE> are in <TT>`stdlib.h'</TT>;
<CODE>fabs</CODE> and <CODE>cabs</CODE> are declared in <TT>`math.h'</TT>.
<P>
<A NAME="IDX1306"></A>
<U>Function:</U> int <B>abs</B> <I>(int <VAR>number</VAR>)</I><P>
This function returns the absolute value of <VAR>number</VAR>.
<P>
Most computers use a two's complement integer representation, in which
the absolute value of <CODE>INT_MIN</CODE> (the smallest possible <CODE>int</CODE>)
cannot be represented; thus, <CODE>abs (INT_MIN)</CODE> is not defined.
<P>
<A NAME="IDX1307"></A>
<U>Function:</U> long int <B>labs</B> <I>(long int <VAR>number</VAR>)</I><P>
This is similar to <CODE>abs</CODE>, except that both the argument and result
are of type <CODE>long int</CODE> rather than <CODE>int</CODE>.
<P>
<A NAME="IDX1308"></A>
<U>Function:</U> double <B>fabs</B> <I>(double <VAR>number</VAR>)</I><P>
This function returns the absolute value of the floating-point number
<VAR>number</VAR>.
<P>
<A NAME="IDX1309"></A>
<U>Function:</U> double <B>cabs</B> <I>(struct { double real, imag; } <VAR>z</VAR>)</I><P>
The <CODE>cabs</CODE> function returns the absolute value of the complex
number <VAR>z</VAR>, whose real part is <CODE><VAR>z</VAR>.real</CODE> and whose
imaginary part is <CODE><VAR>z</VAR>.imag</CODE>.  (See also the function
<CODE>hypot</CODE> in section <A HREF="library_17.html#SEC294" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_17.html#SEC294">Exponentiation and Logarithms</A>.)  The value is:
<P>
<PRE>
sqrt (<VAR>z</VAR>.real*<VAR>z</VAR>.real + <VAR>z</VAR>.imag*<VAR>z</VAR>.imag)
</PRE>
<P>
<A NAME="IDX1310"></A>
<H2><A NAME="SEC303" HREF="library_toc.html#SEC303" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC303">Normalization Functions</A></H2>
<P>
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 <A HREF="library_28.html#SEC488" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_28.html#SEC488">Floating Point Representation Concepts</A>.  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.
<A NAME="IDX1311"></A>
<P>
All these functions are declared in <TT>`math.h'</TT>.
<P>
<A NAME="IDX1312"></A>
<U>Function:</U> double <B>frexp</B> <I>(double <VAR>value</VAR>, int *<VAR>exponent</VAR>)</I><P>
The <CODE>frexp</CODE> function is used to split the number <VAR>value</VAR>
into a normalized fraction and an exponent.
<P>
If the argument <VAR>value</VAR> is not zero, the return value is <VAR>value</VAR>
times a power of two, and is always in the range 1/2 (inclusive) to 1
(exclusive).  The corresponding exponent is stored in
<CODE>*<VAR>exponent</VAR></CODE>; the return value multiplied by 2 raised to this
exponent equals the original number <VAR>value</VAR>.
<P>
For example, <CODE>frexp (12.8, &#38;exponent)</CODE> returns <CODE>0.8</CODE> and
stores <CODE>4</CODE> in <CODE>exponent</CODE>.
<P>
If <VAR>value</VAR> is zero, then the return value is zero and
zero is stored in <CODE>*<VAR>exponent</VAR></CODE>.
<P>
<A NAME="IDX1313"></A>
<U>Function:</U> double <B>ldexp</B> <I>(double <VAR>value</VAR>, int <VAR>exponent</VAR>)</I><P>
This function returns the result of multiplying the floating-point
number <VAR>value</VAR> by 2 raised to the power <VAR>exponent</VAR>.  (It can
be used to reassemble floating-point numbers that were taken apart
by <CODE>frexp</CODE>.)
<P>
For example, <CODE>ldexp (0.8, 4)</CODE> returns <CODE>12.8</CODE>.
<P>
The following functions which come from BSD provide facilities
equivalent to those of <CODE>ldexp</CODE> and <CODE>frexp</CODE>:
<P>
<A NAME="IDX1314"></A>
<U>Function:</U> double <B>scalb</B> <I>(double <VAR>value</VAR>, int <VAR>exponent</VAR>)</I><P>
The <CODE>scalb</CODE> function is the BSD name for <CODE>ldexp</CODE>.
<P>
<A NAME="IDX1315"></A>
<U>Function:</U> double <B>logb</B> <I>(double <VAR>x</VAR>)</I><P>
This BSD function returns the integer part of the base-2 logarithm of
<VAR>x</VAR>, an integer value represented in type <CODE>double</CODE>.  This is
the highest integer power of <CODE>2</CODE> contained in <VAR>x</VAR>.  The sign of
<VAR>x</VAR> is ignored.  For example, <CODE>logb (3.5)</CODE> is <CODE>1.0</CODE> and
<CODE>logb (4.0)</CODE> is <CODE>2.0</CODE>.
<P>
When <CODE>2</CODE> raised to this power is divided into <VAR>x</VAR>, it gives a
quotient between <CODE>1</CODE> (inclusive) and <CODE>2</CODE> (exclusive).
<P>
If <VAR>x</VAR> is zero, the value is minus infinity (if the machine supports
such a value), or else a very small number.  If <VAR>x</VAR> is infinity, the
value is infinity.
<P>
The value returned by <CODE>logb</CODE> is one less than the value that
<CODE>frexp</CODE> would store into <CODE>*<VAR>exponent</VAR></CODE>.
<P>
<A NAME="IDX1316"></A>
<U>Function:</U> double <B>copysign</B> <I>(double <VAR>value</VAR>, double <VAR>sign</VAR>)</I><P>
The <CODE>copysign</CODE> function returns a value whose absolute value is the
same as that of <VAR>value</VAR>, and whose sign matches that of <VAR>sign</VAR>.
This is a BSD function.
<P>
<A NAME="IDX1317"></A>
<A NAME="IDX1318"></A>
<A NAME="IDX1319"></A>
<H2><A NAME="SEC304" HREF="library_toc.html#SEC304" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC304">Rounding and Remainder Functions</A></H2>
<A NAME="IDX1320"></A>
<P>
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 <TT>`math.h'</TT>.
<P>
You can also convert floating-point numbers to integers simply by
casting them to <CODE>int</CODE>.  This discards the fractional part,
effectively rounding towards zero.  However, this only works if the
result can actually be represented as an <CODE>int</CODE>---for very large
numbers, this is impossible.  The functions listed here return the
result as a <CODE>double</CODE> instead to get around this problem.
<P>
<A NAME="IDX1321"></A>
<U>Function:</U> double <B>ceil</B> <I>(double <VAR>x</VAR>)</I><P>
The <CODE>ceil</CODE> function rounds <VAR>x</VAR> upwards to the nearest integer,
returning that value as a <CODE>double</CODE>.  Thus, <CODE>ceil (1.5)</CODE>
is <CODE>2.0</CODE>.
<P>
<A NAME="IDX1322"></A>
<U>Function:</U> double <B>floor</B> <I>(double <VAR>x</VAR>)</I><P>
The <CODE>ceil</CODE> function rounds <VAR>x</VAR> downwards to the nearest
integer, returning that value as a <CODE>double</CODE>.  Thus, <CODE>floor
(1.5)</CODE> is <CODE>1.0</CODE> and <CODE>floor (-1.5)</CODE> is <CODE>-2.0</CODE>.
<P>
<A NAME="IDX1323"></A>
<U>Function:</U> double <B>rint</B> <I>(double <VAR>x</VAR>)</I><P>
This function rounds <VAR>x</VAR> to an integer value according to the
current rounding mode.  See section <A HREF="library_28.html#SEC489" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_28.html#SEC489">Floating Point Parameters</A>, 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.
<P>
<A NAME="IDX1324"></A>
<U>Function:</U> double <B>modf</B> <I>(double <VAR>value</VAR>, double *<VAR>integer_part</VAR>)</I><P>
This function breaks the argument <VAR>value</VAR> into an integer part and a
fractional part (between <CODE>-1</CODE> and <CODE>1</CODE>, exclusive).  Their sum
equals <VAR>value</VAR>.  Each of the parts has the same sign as <VAR>value</VAR>,
so the rounding of the integer part is towards zero.
<P>
<CODE>modf</CODE> stores the integer part in <CODE>*<VAR>integer_part</VAR></CODE>, and
returns the fractional part.  For example, <CODE>modf (2.5, &#38;intpart)</CODE>
returns <CODE>0.5</CODE> and stores <CODE>2.0</CODE> into <CODE>intpart</CODE>.
<P>
<A NAME="IDX1325"></A>
<U>Function:</U> double <B>fmod</B> <I>(double <VAR>numerator</VAR>, double <VAR>denominator</VAR>)</I><P>
This function computes the remainder of dividing <VAR>numerator</VAR> by
<VAR>denominator</VAR>.  Specifically, the return value is
<CODE><VAR>numerator</VAR> - <VAR>n</VAR> * <VAR>denominator</VAR></CODE>, where <VAR>n</VAR>
is the quotient of <VAR>numerator</VAR> divided by <VAR>denominator</VAR>, rounded
towards zero to an integer.  Thus, <CODE>fmod (6.5, 2.3)</CODE> returns
<CODE>1.9</CODE>, which is <CODE>6.5</CODE> minus <CODE>4.6</CODE>.
<P>
The result has the same sign as the <VAR>numerator</VAR> and has magnitude
less than the magnitude of the <VAR>denominator</VAR>.
<P>
If <VAR>denominator</VAR> is zero, <CODE>fmod</CODE> fails and sets <CODE>errno</CODE> to
<CODE>EDOM</CODE>.
<P>
<A NAME="IDX1326"></A>
<U>Function:</U> double <B>drem</B> <I>(double <VAR>numerator</VAR>, double <VAR>denominator</VAR>)</I><P>
The function <CODE>drem</CODE> is like <CODE>fmod</CODE> except that it rounds the
internal quotient <VAR>n</VAR> to the nearest integer instead of towards zero
to an integer.  For example, <CODE>drem (6.5, 2.3)</CODE> returns <CODE>-0.4</CODE>,