XGitUrl: https://git.csclub.uwaterloo.ca/?p=kopensolarisgnu%2Fglibc.git;a=blobdiff_plain;f=manual%2Fmath.texi;h=a97d76c2a199f45dd9b3d720f4238da02420403b;hp=794d72745037cb36f63196e25bc5c4023e3fbf5f;hb=0d96fc6478a87c17b5c7397bf6bfd7551afaf2c3;hpb=4db4f253fcd942402979e0a68f778faac780a192
diff git a/manual/math.texi b/manual/math.texi
index 794d727450..a97d76c2a1 100644
 a/manual/math.texi
+++ b/manual/math.texi
@@ 1,33 +1,29 @@
@node Mathematics
+@node Mathematics, Arithmetic, LowLevel Terminal Interface, Top
@chapter Mathematics
This chapter contains information about functions for performing
mathematical computations, such as trigonometric functions. Most
of these functions have prototypes declared in the header file
+mathematical computations, such as trigonometric functions. Most of
+these functions have prototypes declared in the header file
@file{math.h}.
@pindex math.h
All of the functions that operate on floatingpoint numbers accept
arguments and return results of type @code{double}. In future revisions
of the ANSI C standard, additional functions may be added that operate
on @code{float} and @code{long double} values. For example, @code{cosf}
and @code{cosl} would be versions of the @code{cos} function that
operate on @code{float} and @code{long double} arguments, respectively.
In the meantime, you should avoid using these names yourself.
@xref{Reserved Names}.

@strong{Incomplete:} This chapter doesn't have any examples.
+arguments and return results of type @code{double}. In the future,
+there may be additional functions that operate on @code{float} and
+@code{long double} values. For example, @code{cosf} and @code{cosl}
+would be versions of the @code{cos} function that operate on
+@code{float} and @code{long double} arguments, respectively. In the
+meantime, you should avoid using these names yourself. @xref{Reserved
+Names}.
@menu
* Domain and Range Errors:: How overflow conditions and the like
 are reported.
* Trigonometric Functions:: Sine, cosine, and tangent.
* Inverse Trigonometric Functions:: Arc sine, arc cosine, and arc tangent.
* Exponentiation and Logarithms:: Also includes square root.
* Hyperbolic Functions:: Hyperbolic sine and friends.
* PseudoRandom Numbers:: Functions for generating pseudorandom
 numbers.
* Absolute Value:: Absolute value functions.
+* Domain and Range Errors:: Detecting overflow conditions and the like.
+* Trig Functions:: Sine, cosine, and tangent.
+* Inverse Trig Functions:: Arc sine, arc cosine, and arc tangent.
+* Exponents and Logarithms:: Also includes square root.
+* Hyperbolic Functions:: Hyperbolic sine and friends.
+* PseudoRandom Numbers:: Functions for generating pseudorandom
+ numbers.
@end menu
@node Domain and Range Errors
@@ 38,15 +34,17 @@ Many of the functions listed in this chapter are defined mathematically
over a domain that is only a subset of real numbers. For example, the
@code{acos} function is defined over the domain between @code{1} and
@code{1}. If you pass an argument to one of these functions that is
outside the domain over which it is defined, the function returns
an unspecified value and sets @code{errno} to @code{EDOM} to indicate
a @dfn{domain error}.
+outside the domain over which it is defined, the function sets
+@code{errno} to @code{EDOM} to indicate a @dfn{domain error}. On
+machines that support IEEE floating point, functions reporting error
+@code{EDOM} also return a NaN.
Some of these functions are defined mathematically to result in a
complex value over parts of their domains. The most familiar example of
this is taking the square root of a negative number. Since the C
language has no support for complex numbers, this is considered a
domain error.
+this is taking the square root of a negative number. The functions in
+this chapter take only real arguments and return only real values;
+therefore, if the value ought to be nonreal, this is treated as a domain
+error.
@cindex range error
A related problem is that the mathematical result of a function may not
@@ 54,43 +52,44 @@ be representable as a floating point number. If magnitude of the
correct result is too large to be represented, the function sets
@code{errno} to @code{ERANGE} to indicate a @dfn{range error}, and
returns a particular very large value (named by the macro
@code{HUGE_VAL}) or its negation.
+@code{HUGE_VAL}) or its negation (@w{@code{ HUGE_VAL}}).
If the magnitude of the result is too small, a value of zero is returned
instead. In this case, @code{errno} might or might not be
set to @code{ERANGE}.
None of the mathematical functions ever generates signals as a result of
domain or range errors. In particular, this means that you won't see
@code{SIGFPE} signals generated within these functions. (@xref{Signal
Handling}, for more information about signals.)

The only completely reliable way to check for domain and range errors is
to set @code{errno} to @code{0} before you call the mathematical function
and test @code{errno} afterward. As a consequence of this use of
@code{errno}, use of the mathematical functions is not reentrant if you
check for errors.
+@c !!! this isn't always true at the moment....
+None of the mathematical functions ever generates signals as a result of
+domain or range errors. In particular, this means that you won't see
+@code{SIGFPE} signals generated within these functions. (@xref{Signal
+Handling}, for more information about signals.)
+
@comment math.h
@comment ANSI
@deftypevr Macro double HUGE_VAL
This macro expands into an expression of type @code{double} representing
a particular very large number. On machines that use IEEE floating
point format, the value is ``infinity''. On other machines, it's
typically the largest positive number that can be represented.
+An expression representing a particular very large number. On machines
+that use IEEE floating point format, the value is ``infinity''. On
+other machines, it's typically the largest positive number that can be
+represented.
The value of this macro is used as the return value from various
mathematical functions in overflow situations.
@end deftypevr
For more information about floatingpoint representations and limits,
@xref{FloatingPoint Limits}. In particular, the macro @code{DBL_MAX}
might be more appropriate than @code{HUGE_VAL} for many uses.
+see @ref{Floating Point Parameters}. In particular, the macro
+@code{DBL_MAX} might be more appropriate than @code{HUGE_VAL} for many
+uses other than testing for an error in a mathematical function.

@node Trigonometric Functions
+@node Trig Functions
@section Trigonometric Functions
@cindex trignometric functions
+@cindex trigonometric functions
These are the familiar @code{sin}, @code{cos}, and @code{tan} functions.
The arguments to all of these functions are in units of radians; recall
@@ 100,9 +99,9 @@ that pi radians equals 180 degrees.
The math library doesn't define a symbolic constant for pi, but you can
define your own if you need one:
@example
+@smallexample
#define PI 3.14159265358979323846264338327
@end example
+@end smallexample
@noindent
You can also compute the value of pi with the expression @code{acos
@@ 133,15 +132,15 @@ The following @code{errno} error conditions are defined for this function:
@table @code
@item ERANGE
Mathematically, the tangent function has singularities at odd multiples of
pi/2. If the argument @var{x} is too close to one of these singularities,
@code{tan} sets this error condition and returns either positive or
negative @code{HUGE_VAL}.
+Mathematically, the tangent function has singularities at odd multiples
+of pi/2. If the argument @var{x} is too close to one of these
+singularities, @code{tan} sets @code{errno} to @code{ERANGE} and returns
+either positive or negative @code{HUGE_VAL}.
@end table
@end deftypefun
@node Inverse Trigonometric Functions
+@node Inverse Trig Functions
@section Inverse Trigonometric Functions
@cindex inverse trigonmetric functions
@@ 157,13 +156,9 @@ sine is @var{x}. The value is in units of radians. Mathematically,
there are infinitely many such values; the one actually returned is the
one between @code{pi/2} and @code{pi/2} (inclusive).
The following @code{errno} error conditions are defined for this function:

@table @code
@item EDOM
The argument @var{x} is out of range. The arc sine function is defined
mathematically only over the domain @code{1} to @code{1}.
@end table
+@code{asin} fails, and sets @code{errno} to @code{EDOM}, if @var{x} is
+out of range. The arc sine function is defined mathematically only
+over the domain @code{1} to @code{1}.
@end deftypefun
@comment math.h
@@ 174,13 +169,9 @@ whose cosine is @var{x}. The value is in units of radians.
Mathematically, there are infinitely many such values; the one actually
returned is the one between @code{0} and @code{pi} (inclusive).
The following @code{errno} error conditions are defined for this function:

@table @code
@item EDOM
The argument @var{x} is out of range. The arc cosine function is defined
mathematically only over the domain @code{1} to @code{1}.
@end table
+@code{acos} fails, and sets @code{errno} to @code{EDOM}, if @var{x} is
+out of range. The arc cosine function is defined mathematically only
+over the domain @code{1} to @code{1}.
@end deftypefun
@@ 192,6 +183,7 @@ whose tangent is @var{x}. The value is in units of radians.
Mathematically, there are infinitely many such values; the one actually
returned is the one between @code{pi/2} and @code{pi/2}
(inclusive).
+@end deftypefun
@comment math.h
@comment ANSI
@@ 206,20 +198,16 @@ If @var{x} and @var{y} are coordinates of a point in the plane,
@code{atan2} returns the signed angle between the line from the origin
to that point and the xaxis. Thus, @code{atan2} is useful for
converting Cartesian coordinates to polar coordinates. (To compute the
radial coordinate, use @code{hypot}; see @ref{Exponentiation and
+radial coordinate, use @code{hypot}; see @ref{Exponents and
Logarithms}.)
The following @code{errno} error conditions are defined for this function:

@table @code
@item EDOM
Both the @var{x} and @var{y} arguments are zero; the value of the
function is not defined in this case.
@end table
+The function @code{atan2} sets @code{errno} to @code{EDOM} if both
+@var{x} and @var{y} are zero; the return value is not defined in this
+case.
@end deftypefun
@node Exponentiation and Logarithms
+@node Exponents and Logarithms
@section Exponentiation and Logarithms
@cindex exponentiation functions
@cindex power functions
@@ 231,31 +219,26 @@ function is not defined in this case.
The @code{exp} function returns the value of e (the base of natural
logarithms) raised to power @var{x}.
The following @code{errno} error conditions are defined for this function:

@table @code
@item ERANGE
The magnitude of the result is too large to be representable.
@end table
+The function fails, and sets @code{errno} to @code{ERANGE}, if the
+magnitude of the result is too large to be representable.
@end deftypefun
@comment math.h
@comment ANSI
@deftypefun double log (double @var{x})
This function returns the natural logarithm of @var{x}. @code{exp (log
(@var{x})) equals @var{x}, exactly in mathematics and approximately in
+(@var{x}))} equals @var{x}, exactly in mathematics and approximately in
C.
The following @code{errno} error conditions are defined for this function:
@table @code
@item EDOM
The log function is defined mathematically to return a noncomplex
result only on positive arguments. This error is used to report a
negative argument @var{x}.
+The argument @var{x} is negative. The log function is defined
+mathematically to return a real result only on positive arguments.
@item ERANGE
The result of the function on an argument of zero is not defined.
+The argument is zero. The log of zero is not defined.
@end table
@end deftypefun
@@ 273,6 +256,7 @@ different base, it is similar to the @code{log} function. In fact,
This is a general exponentiation function, returning @var{base} raised
to @var{power}.
+@need 250
The following @code{errno} error conditions are defined for this function:
@table @code
@@ 291,41 +275,31 @@ An underflow or overflow condition was detected in the result.
@deftypefun double sqrt (double @var{x})
This function returns the nonnegative square root of @var{x}.
The following @code{errno} error conditions are defined for this function:

@table @code
@item EDOM
The argument @var{x} is negative. Mathematically, the square root would
be a complex number.
@end table
+The @code{sqrt} function fails, and sets @code{errno} to @code{EDOM}, if
+@var{x} is negative. Mathematically, the square root would be a complex
+number.
@end deftypefun
@cindex cube root function
@comment math.h
@comment GNU
+@comment BSD
@deftypefun double cbrt (double @var{x})
This function returns the cube root of @var{x}.
+This function returns the cube root of @var{x}. This function cannot
+fail; every representable real value has a representable real cube root.
@end deftypefun
@comment math.h
@comment GNU
+@comment BSD
@deftypefun double hypot (double @var{x}, double @var{y})
The @code{hypot} function returns @code{sqrt (@var{x}*@var{x} +
@var{y}*@var{y})}. (This is the length of the hypotenuse of a right
triangle with sides of length @var{x} and @var{y}, or the distance
of the point (@var{x}, @var{y}) from the origin.)
@end deftypefun

@comment math.h
@comment GNU
@deftypefun double cabs (struct @{ double x, y; @} @var{z})
The @code{cabs} function is similar to @code{hypot}, but the argument
is specified as a @code{struct} representing a complex number.
+of the point (@var{x}, @var{y}) from the origin.) See also the function
+@code{cabs} in @ref{Absolute Value}.
@end deftypefun

@comment math.h
@comment GNU
+@comment BSD
@deftypefun double expm1 (double @var{x})
This function returns a value equivalent to @code{exp (@var{x})  1}.
It is computed in a way that is accurate even if the value of @var{x} is
@@ 334,9 +308,9 @@ to subtraction of two numbers that are nearly equal.
@end deftypefun
@comment math.h
@comment GNU
+@comment BSD
@deftypefun double log1p (double @var{x})
This function returns a value equivalent to @code{log (1 + @var{x})}.
+This function returns a value equivalent to @w{@code{log (1 + @var{x})}}.
It is computed in a way that is accurate even if the value of @var{x} is
near zero.
@end deftypefun
@@ 346,56 +320,44 @@ near zero.
@cindex hyperbolic functions
The functions in this section are related to the exponential functions;
see @ref{Exponentiation and Logarithms}.
+see @ref{Exponents and Logarithms}.
@comment math.h
@comment ANSI
@deftypefun double sinh (double @var{x})
The @code{sinh} function returns the hyperbolic sine of @var{x}, defined
mathematically as @code{(exp (@var{x})  exp (@var{x}) / 2}.
The following @code{errno} error conditions are defined for this
function:

@table @code
@item ERANGE
The value of the argument @var{x} is too large; an overflow condition
was detected.
@end table
+mathematically as @w{@code{exp (@var{x})  exp (@var{x}) / 2}}. The
+function fails, and sets @code{errno} to @code{ERANGE}, if the value of
+@var{x} is too large; that is, if overflow occurs.
@end deftypefun
@comment math.h
@comment ANSI
@deftypefun double cosh (double @var{x})
The @code{cosh} function returns the hyperbolic cosine of @var{x},
defined mathematically as @code{(exp (@var{x}) + exp (@var{x}) /
2}. The following @code{errno} error conditions are defined for this
function:

@table @code
@item ERANGE
The value of the argument @var{x} is too large; an overflow condition
was detected.
@end table
+defined mathematically as @w{@code{exp (@var{x}) + exp (@var{x}) / 2}}.
+The function fails, and sets @code{errno} to @code{ERANGE}, if the value
+of @var{x} is too large; that is, if overflow occurs.
@end deftypefun
@comment math.h
@comment ANSI
@deftypefun double tanh (double @var{x})
This function returns the hyperbolic tangent of @var{x}, defined
mathematically as @code{sinh (@var{x}) / cosh (@var{x})}.
+This function returns the hyperbolic tangent of @var{x}, whose
+mathematical definition is @w{@code{sinh (@var{x}) / cosh (@var{x})}}.
@end deftypefun
@cindex inverse hyperbolic functions
@comment math.h
@comment GNU
+@comment BSD
@deftypefun double asinh (double @var{x})
This function returns the inverse hyperbolic sine of @var{x}the
value whose hyperbolic sine is @var{x}.
@end deftypefun
@comment math.h
@comment GNU
+@comment BSD
@deftypefun double acosh (double @var{x})
This function returns the inverse hyperbolic cosine of @var{x}the
value whose hyperbolic cosine is @var{x}. If @var{x} is less than
@@ 403,7 +365,7 @@ value whose hyperbolic cosine is @var{x}. If @var{x} is less than
@end deftypefun
@comment math.h
@comment GNU
+@comment BSD
@deftypefun double atanh (double @var{x})
This function returns the inverse hyperbolic tangent of @var{x}the
value whose hyperbolic tangent is @var{x}. If the absolute value of
@@ 413,48 +375,46 @@ value whose hyperbolic tangent is @var{x}. If the absolute value of
@node PseudoRandom Numbers
@section PseudoRandom Numbers

This section describes the GNU facilities for generating a series of
pseudorandom numbers. The numbers generated are not necessarily truly
random; typically, the sequences repeat periodically, with the period
being a function of the number of bits in the @dfn{seed} or initial
state.
@cindex random numbers
@cindex pseudorandom numbers
@cindex seed (for random numbers)
There are actually two sets of random number functions provided.

@itemize @bullet
@item
The @code{rand} and @code{srand} functions, described in @ref{ANSI C
Random Number Functions}, are part of the ANSI C standard. You can use
these functions portably in many C implementations.

@item
The @code{random} and @code{srandom} functions, described in @ref{BSD
Random Number Functions}, are derived from BSD Unix. This uses a better
random number generator (producing numbers that are more random), but
is less portable.
@end itemize

For both sets of functions, you can get repeatable sequences of numbers
within a single implementation on a single machine type by specifying
the same initial seed value for the random number generator. Other C
libraries may produce different sequences of values for the same seed.

+This section describes the GNU facilities for generating a series of
+pseudorandom numbers. The numbers generated are not truly random;
+typically, they form a sequence that repeats periodically, with a
+period so large that you can ignore it for ordinary purposes. The
+random number generator works by remembering at all times a @dfn{seed}
+value which it uses to compute the next random number and also to
+compute a new seed.
+
+Although the generated numbers look unpredictable within one run of a
+program, the sequence of numbers is @emph{exactly the same} from one run
+to the next. This is because the initial seed is always the same. This
+is convenient when you are debugging a program, but it is unhelpful if
+you want the program to behave unpredictably. If you want truly random
+numbers, not just pseudorandom, specify a seed based on the current
+time.
+
+You can get repeatable sequences of numbers on a particular machine type
+by specifying the same initial seed value for the random number
+generator. There is no standard meaning for a particular seed value;
+the same seed, used in different C libraries or on different CPU types,
+will give you different random numbers.
+
+The GNU library supports the standard ANSI C random number functions
+plus another set derived from BSD. We recommend you use the standard
+ones, @code{rand} and @code{srand}.
@menu
* ANSI C Random Number Functions:: @code{rand} and friends.
* BSD Random Number Functions:: @code{random} and friends.
+* ANSI Random:: @code{rand} and friends.
+* BSD Random:: @code{random} and friends.
@end menu
@node ANSI C Random Number Functions
+@node ANSI Random
@subsection ANSI C Random Number Functions
This section describes the random number functions that are part of
the ANSI C standard. These functions represent the state of the
random number generator as an @code{int}.
+the ANSI C standard.
To use these facilities, you should include the header file
@file{stdlib.h} in your program.
@@ 465,13 +425,14 @@ To use these facilities, you should include the header file
@deftypevr Macro int RAND_MAX
The value of this macro is an integer constant expression that
represents the maximum possible value returned by the @code{rand}
function. In the GNU library, it is @code{037777777}. In other
libraries, it may be as low as @code{32767}.
+function. In the GNU library, it is @code{037777777}, which is the
+largest signed integer representable in 32 bits. In other libraries, it
+may be as low as @code{32767}.
@end deftypevr
@comment stdlib.h
@comment ANSI
@deftypefun int rand (void)
+@deftypefun int rand ()
The @code{rand} function returns the next pseudorandom number in the
series. The value is in the range from @code{0} to @code{RAND_MAX}.
@end deftypefun
@@ 488,20 +449,19 @@ To produce truly random numbers (not just pseudorandom), do @code{srand
(time (0))}.
@end deftypefun
@node BSD Random Number Functions
+@node BSD Random
@subsection BSD Random Number Functions
This section describes a set of random number generation functions
that are derived from BSD Unix. The @code{random} function can generate
better random numbers than @code{rand}, because it maintains more bits
of internal state.
+This section describes a set of random number generation functions that
+are derived from BSD. There is no advantage to using these functions
+with the GNU C library; we support them for BSD compatibility only.
The prototypes for these functions are in @file{stdlib.h}.
@pindex stdlib.h
@comment stdlib.h
@comment BSD
@deftypefun {long int} random (void)
+@deftypefun {long int} random ()
This function returns the next pseudorandom number in the sequence.
The range of values returned is from @code{0} to @code{RAND_MAX}.
@end deftypefun
@@ 518,12 +478,6 @@ To produce truly random numbers (not just pseudorandom), do
@code{srandom (time (0))}.
@end deftypefun
Because this random number generator uses more state information than
will fit in an @code{int}, @code{srandom} does not return a value that
is useful for saving and restoring the random number state. Instead,
you should use the @code{initstate} and @code{setstate} functions to do
this.

@comment stdlib.h
@comment BSD
@deftypefun {void *} initstate (unsigned int @var{seed}, void *@var{state}, size_t @var{size})
@@ 549,507 +503,3 @@ The return value is the previous value of the state information array.
You can use thise value later as an argument to @code{setstate} to
restore that state.
@end deftypefun

@node Absolute Value
@section Absolute Value
@cindex absolute value functions

These functions are provided for obtaining the @dfn{absolute value} (or
@dfn{magnitude}) of a number. The absolute value of @var{x} is @var{x}
is @var{x} is positive, @minus{}@var{x} if @var{x} is negative.

Prototypes for @code{abs} and @code{abs} are declared in
@file{stdlib.h}; @code{fabs} is declared in @file{math.h}.
@pindex math.h
@pindex stdlib.h

@comment stdlib.h
@comment ANSI
@deftypefun int abs (int @var{number})
This function returns the absolute value of @var{number}.

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

@comment stdlib.h
@comment ANSI
@deftypefun {long int} labs (long int @var{number})
This is similar to @code{abs}, except that both the argument and result
are of type @code{long int} rather than @code{int}.
@end deftypefun

@comment math.h
@comment ANSI
@deftypefun double fabs (double @var{number})
This function returns the absolute value of the floatingpoint number
@var{number}.
@end deftypefun

There is also the function @code{cabs} for computing the absolute value
of a complex number; see @ref{Exponentiation and Logarithms}.

@node Arithmetic
@chapter LowLevel 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
@file{math.h}.

@menu
* Normalization Functions:: Hacks for radix2 representations.
* Rounding and Remainder Functions:: Determinining the integer and
 fractional parts of a float.
* Integer Division:: Functions for performing integer
 division.
* Parsing of Numbers:: Functions for ``reading'' numbers
 from strings.
* Predicates on Floats:: Some miscellaneous test functions.
@end menu

@node Normalization Functions
@section Normalization Functions
@cindex normalization functions (floatingpoint)

The functions described in this section are primarily provided as a way
to efficiently perform certain lowlevel manipulations on floating point
numbers that are represented internally using a binary radix;
see @ref{FloatingPoint Representation}. 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.

@comment math.h
@comment GNU
@deftypefun double copysign (double @var{value}, double @var{sign})
The @code{copysign} function returns a value whose absolute value is the
same as that of @var{value}, and whose sign matches that of @var{sign}.
@end deftypefun

@comment math.h
@comment ANSI
@deftypefun double frexp (double @var{value}, int *@var{exponent})
The @code{frexp} function is used to normalize the number @var{value}.

If the argument @var{value} is not zero, the return value is a
floatingpoint number with magnitude in the range 1/2 (inclusive) to 1
(exclusive). The corresponding exponent is stored in the location
pointed at by @var{exponent}; the return value multiplied by 2 raised to
this exponent would equal the original number @var{value}.

If @var{value} is zero, then both parts of the result are zero.
@end deftypefun

@comment math.h
@comment ANSI
@deftypefun double ldexp (double @var{value}, int @var{exponent})
This function returns the result of multiplying the floatingpoint
number @var{value} by 2 raised to the power @var{exponent}. (It can
be used to reassemble floatingpoint numbers that were taken apart
by @code{frexp}.)
@end deftypefun

@c ??? Where does this come from?
@comment math.h
@comment GNU
@deftypefun double scalb (double @var{value}, int @var{exponent})
The @code{scalb} function does the same thing as @code{ldexp}.
@end deftypefun

@c ??? Where does this come from?
@comment math.h
@comment GNU
@deftypefun double logb (double @var{x})
This function returns the integer part of the base2 logarithm of
@var{x}, an integer value represented in type @code{double}. This is
the highest integer power of @code{2} contained in @var{x}.

When @code{2} raised to this power is divided into @var{x}, it gives a
quotient between @code{1} (inclusive) and @code{2} (exclusive).

@strong{Incomplete:} What happens if @var{x} is zero?
@end deftypefun


@node Rounding and Remainder Functions
@section Rounding and Remainder Functions
@cindex rounding functions
@cindex remainder functions
@cindex converting floats to integers

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.

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

@comment math.h
@comment ANSI
@deftypefun double ceil (double @var{x})
The @code{ceil} function rounds @var{x} upwards to the nearest integer,
returning that value as a @code{double}.
@end deftypefun

@comment math.h
@comment ANSI
@deftypefun double floor (double @var{x})
The @code{ceil} function rounds @var{x} downwards to the nearest
integer, returning that value as a @code{double}.
@end deftypefun

@comment math.h
@comment GNU
@deftypefun double rint (double @var{x})
This function returns the integer nearest @var{x} according to the
current rounding mode. @xref{FloatingPoint Parameters}, for information
about the @code{FLT_ROUNDS} macro.
@end deftypefun

@comment math.h
@comment ANSI
@deftypefun double modf (double @var{value}, double *@var{integer_part})
This function breaks the argument @var{value} into an integer part and a
fractional part (between @code{1} and @code{1}, exclusive). The
integer part is stored at the location pointed at by @var{integer_part},
and the fractional part is returned. Their sum equals @var{value}.
Each of the parts has the same sign as @var{value}, so the rounding of
the integer part is towards zero.
@end deftypefun


@comment math.h
@comment ANSI
@deftypefun double fmod (double @var{numerator}, double @var{denominator})
This function computes the remainder from dividing @var{numerator} by
@var{denominator}. Specifically, the return value is
@code{@var{numerator}  @var{n} * @var{denominator}}, where @var{n} is
the quotient of @var{numerator} by @var{denominator}, rounded down to
the next lower integer.

The result has the same sign as the @var{numerator} and has magnitude
less than the magnitude of the @var{denominator}. (Recall that the
builtin @samp{%} operator isn't defined on floatingpoint values.)

The following @code{errno} error conditions are defined for this function:

@table @code
@item EDOM
The @var{denominator} is zero.
@end table
@end deftypefun

@comment math.h
@comment GNU
@deftypefun double drem (double @var{numerator}, double @var{denominator})
This function returns the remainder from dividing @var{numerator} by
@var{denominator}. Specifically, the return value is @code{@var{numerator}
 @var{n} * @var{denominator}}, where @var{n} is the integer closest to
the exact quotient of @var{numerator} and @var{denominator}. The absolute
value of the result is less than or equal to one half the absolute value
of the @var{denominator}.

The following @code{errno} error conditions are defined for this function:

@table @code
@item EDOM
The @var{denominator} is zero.
@end table
@end deftypefun


@node Integer Division
@section Integer Division
@cindex integer division functions

This section describes functions for performing integer division. These
functions are redundant in the GNU C library, since in GNU C the @samp{/}
operator always rounds towards zero. But in other C implementations,
@samp{/} may round differently with negative arguments. @code{div} and
@code{ldiv} are useful because they specify how to round the quotient.

These functions are specified to return a result @var{r} such that
@code{@var{r}.quot*@var{denominator} + @var{r}.rem} equals
@var{numerator}.

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

@comment stdlib.h
@comment ANSI
@deftp {Data Type} div_t
This is a structure type used to hold the result returned by the @code{div}
function. It has the following members:

@table @code
@item {int quot}
The quotient from the division.

@item {int rem}
The remainder from the division.
@end table
@end deftp

@comment stdlib.h
@comment ANSI
@deftypefun div_t div (int @var{numerator}, int @var{denominator})
This function @code{div} computes the quotient and remainder from
the division of @var{numerator} by @var{denominator}, returning the
result in a structure of type @code{div_t}.

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


@comment stdlib.h
@comment ANSI
@deftp {Data Type} ldiv_t
This is a structure type used to hold the result returned by the @code{ldiv}
function. It has the following members:

@table @code
@item {long int quot}
The quotient from the division.

@item {long int rem}
The remainder from the division.
@end table

(This is identical to the type @code{div_t} except that the components
are of type @code{long int} rather than @code{int}.)
@end deftp

@comment stdlib.h
@comment ANSI
@deftypefun ldiv_t ldiv (long int @var{numerator}, long int @var{denominator})
The @code{ldiv} function is similar to @code{div}, except that the
arguments are of type @code{long int} and the result is returned as a
structure of type @code{ldiv}.
@end deftypefun


@node Parsing of Numbers
@section Parsing of Numbers
@cindex parsing numbers (in formatted input)
@cindex converting strings to numbers
@cindex number syntax, parsing
@cindex syntax, for reading numbers

This section describes functions for ``reading'' integer and
floatingpoint numbers from a string. In many cases, it is more
appropriate to use @code{sscanf} or one of the related functions;
see @ref{Formatted Input}. The syntax recognized by the formatted input
functions for the numeric conversions is exactly the same as the syntax
recognized by the functions described in this section.

These functions are declared in @file{stdlib.h}.
@pindex stdlib.h

@menu
* Parsing of Integers:: Functions for conversion of integer values.
* Parsing of Floats:: Functions for conversion of floatingpoint
 values.
@end menu

@node Parsing of Integers
@subsection Parsing of Integers

@comment stdlib.h
@comment ANSI
@deftypefun {long int} strtol (const char *@var{string}, char **@var{tailptr}, int @var{base})
The @code{strtol} (``stringtolong'') function converts the initial
part of @var{string} to a signed integer, which is returned as a value
of type @code{long int}.

This function attempts to decompose @var{string} as follows:

@itemize @bullet
@item
A (possibly empty) sequence of whitespace characters, as determined by
the @code{isspace} function (@pxref{Classification of Characters}).
These are discarded.

@item
An optional plus or minus sign (@samp{+} or @samp{}).

@item
A nonempty sequence of digits in the radix specified by @var{base}. If
@var{base} is zero, decimal radix is assumed unless the series of digits
begins with @samp{0} (specifying octal radix), or @samp{0x} or @samp{0X}
(specifying hexadecimal radix); in other words, the same syntax that is
used for integer constants in the C language is recognized. Otherwise
@var{base} must have a value between @code{2} and @code{35}. If
@var{base} is @code{16}, the digits may optionally be preceeded by
@samp{0x} or @samp{0X}.

@item
Any remaining characters in the string. If @var{tailptr} is not a null
pointer, a pointer to this tail of the string is stored in
@code{*@var{tailptr}}.
@end itemize

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 @var{base}, no conversion is performed. In this case,
@code{strtol} returns a value of zero and the value returned in
@code{*@var{tailptr}} is the value of @var{string}.

In a locale other than the standard @code{"C"} locale, this function
may recognize additional implementationdependent syntax.

If the string has valid syntax for an integer but the value is not
representable because of overflow, @code{strtol} returns either
@code{LONG_MAX} or @code{LONG_MIN} (@pxref{Integer Representation
Limits}), as appropriate for the sign of the value.

The following @code{errno} error conditions are defined for this
function:

@table @code
@item ERANGE
An overflow condition was detected.
@end table
@end deftypefun

@comment stdlib.h
@comment ANSI
@deftypefun {unsigned long int} strtoul (const char *@var{string}, char **@var{tailptr}, int @var{base})
The @code{strtoul} (``stringtounsignedlong'') function is similar to
@code{strtol} except that it returns its value as an object of type
@code{unsigned long int}. The value returned in case of overflow is
@code{ULONG_MAX} (@pxref{Integer Representation Limits}).
@end deftypefun

@comment stdlib.h
@comment ANSI
@deftypefun {long int} atol (const char *@var{string})
This function is similar to the @code{strtol} function with a @var{base}
argument of @code{10}, except that it need not detect overflow errors.
The @code{atol} function is provided mostly for compatibility with
existing code; using @code{strtol} is more robust.
@end deftypefun

@comment stdlib.h
@comment ANSI
@deftypefun int atoi (const char *@var{string})
This function is similar to the @code{atol} function, except that
returns its value as an @code{int} rather than @code{long int}. The
@code{atoi} function is also considered obsolete; use @code{strtol}
instead.
@end deftypefun


@node Parsing of Floats
@subsection Parsing of Floats

@comment stdlib.h
@comment ANSI
@deftypefun double strtod (const char *@var{string}, char **@var{tailptr})
The @code{strtod} (``stringtodouble'') function converts the initial
part of @var{string} to a floatingpoint number, which is returned as a
value of type @code{double}.

This function attempts to decompose @var{string} as follows:

@itemize @bullet
@item
A (possibly empty) sequence of whitespace characters, as determined
by the @code{isspace} function. These are discarded.

@item
An optional plus or minus sign (@samp{+} or @samp{}).

@item
A nonempty sequence of digits optionally containing a decimalpoint
character (@samp{.}).

@item
An optional exponent part, consisting of a character @samp{e} or
@samp{E}, an optional sign, and a sequence of digits.

@item
Any remaining characters in the string. If @var{tailptr} is not a null
pointer, a pointer to this tail of the string is stored in
@code{*@var{tailptr}}.
@end itemize

If the string is empty, contains only whitespace, or does not contain an
initial substring that has the expected syntax for a floatingpoint
number, no conversion is performed. In this case, @code{strtod} returns
a value of zero and the value returned in @code{*@var{tailptr}} is the
value of @var{string}.

In a locale other than the standard @code{"C"} locale, this function may
recognize additional localedependent syntax.

If the string has valid syntax for a floatingpoint number but the value
is not representable because of overflow, @code{strtod} returns either
positive or negative @code{HUGE_VAL} (@pxref{Mathematics}), depending on
the sign of the value. Similarly, if the value is not representable
because of underflow, @code{strtod} returns zero.

The following @code{errno} error conditions are defined for this
function:

@table @code
@item ERANGE
An overflow or underflow condition was detected.
@end table
@end deftypefun

@comment stdlib.h
@comment ANSI
@deftypefun double atof (const char *@var{string})
This function is similar to the @code{strtod} function, except that it
need not detect overflow and underflow errors. The @code{atof} function
is provided mostly for compatibility with existing code; using
@code{strtod} is more robust.
@end deftypefun

@node Predicates on Floats
@section Predicates on Floats
@cindex predicates on floats

This section describes some miscellaneous test functions on doubles.
Prototypes for these functions appear in @file{math.h}.
@pindex math.h

@comment math.h
@comment GNU
@deftypefun int isinf (double @var{x})
This function returns @code{1} if @var{x} represents negative infinity,
@code{1} if @var{x} represents positive infinity, and @code{0} otherwise.
@end deftypefun

@comment math.h
@comment GNU
@deftypefun int isnan (double @var{x})
This function returns a nonzero value if @var{x} is a ``not a number''
value, and zero otherwise.
@end deftypefun

@comment math.h
@comment GNU
@deftypefun int finite (double @var{x})
This function returns a nonzero value if @var{x} is finite or a ``not a
number'' value, and zero otherwise.
@end deftypefun

@comment math.h
@comment GNU
@deftypefun double infnan (int @var{error})
@strong{Incomplete:} I don't understand what this function does.
@end deftypefun

@strong{Portability Note:} The functions listed in this section are GNU
extensions.

