diff options
Diffstat (limited to 'manual/math.texi')
| -rw-r--r-- | manual/math.texi | 505 |
1 files changed, 505 insertions, 0 deletions
diff --git a/manual/math.texi b/manual/math.texi new file mode 100644 index 0000000000..a97d76c2a1 --- /dev/null +++ b/manual/math.texi @@ -0,0 +1,505 @@ +@node Mathematics, Arithmetic, Low-Level 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 +@file{math.h}. +@pindex math.h + +All of the functions that operate on floating-point numbers accept +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:: 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. +* Pseudo-Random Numbers:: Functions for generating pseudo-random + numbers. +@end menu + +@node Domain and Range Errors +@section Domain and Range Errors + +@cindex domain error +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 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. 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 +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 (@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}. + +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 +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 floating-point representations and limits, +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 Trig Functions +@section Trigonometric 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 +that pi radians equals 180 degrees. + +@cindex pi (trigonometric constant) +The math library doesn't define a symbolic constant for pi, but you can +define your own if you need one: + +@smallexample +#define PI 3.14159265358979323846264338327 +@end smallexample + +@noindent +You can also compute the value of pi with the expression @code{acos +(-1.0)}. + + +@comment math.h +@comment ANSI +@deftypefun double sin (double @var{x}) +This function returns the sine of @var{x}, where @var{x} is given in +radians. The return value is in the range @code{-1} to @code{1}. +@end deftypefun + +@comment math.h +@comment ANSI +@deftypefun double cos (double @var{x}) +This function returns the cosine of @var{x}, where @var{x} is given in +radians. The return value is in the range @code{-1} to @code{1}. +@end deftypefun + +@comment math.h +@comment ANSI +@deftypefun double tan (double @var{x}) +This function returns the tangent of @var{x}, where @var{x} is given in +radians. + +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 @code{errno} to @code{ERANGE} and returns +either positive or negative @code{HUGE_VAL}. +@end table +@end deftypefun + + +@node Inverse Trig Functions +@section Inverse Trigonometric Functions +@cindex inverse trigonmetric functions + +These are the usual arc sine, arc cosine and arc tangent functions, +which are the inverses of the sine, cosine and tangent functions, +respectively. + +@comment math.h +@comment ANSI +@deftypefun double asin (double @var{x}) +This function computes the arc sine of @var{x}---that is, the value whose +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). + +@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 +@comment ANSI +@deftypefun double acos (double @var{x}) +This function computes the arc cosine of @var{x}---that is, the value +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). + +@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 + + +@comment math.h +@comment ANSI +@deftypefun double atan (double @var{x}) +This function computes the arc tangent of @var{x}---that is, the value +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 +@deftypefun double atan2 (double @var{y}, double @var{x}) +This is the two argument arc tangent function. It is similar to computing +the arc tangent of @var{y}/@var{x}, except that the signs of both arguments +are used to determine the quadrant of the result, and @var{x} is +permitted to be zero. The return value is given in radians and is in +the range @code{-pi} to @code{pi}, inclusive. + +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 x-axis. Thus, @code{atan2} is useful for +converting Cartesian coordinates to polar coordinates. (To compute the +radial coordinate, use @code{hypot}; see @ref{Exponents and +Logarithms}.) + +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 Exponents and Logarithms +@section Exponentiation and Logarithms +@cindex exponentiation functions +@cindex power functions +@cindex logarithm functions + +@comment math.h +@comment ANSI +@deftypefun double exp (double @var{x}) +The @code{exp} function returns the value of e (the base of natural +logarithms) raised to power @var{x}. + +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 +C. + +The following @code{errno} error conditions are defined for this function: + +@table @code +@item EDOM +The argument @var{x} is negative. The log function is defined +mathematically to return a real result only on positive arguments. + +@item ERANGE +The argument is zero. The log of zero is not defined. +@end table +@end deftypefun + +@comment math.h +@comment ANSI +@deftypefun double log10 (double @var{x}) +This function returns the base-10 logarithm of @var{x}. Except for the +different base, it is similar to the @code{log} function. In fact, +@code{log10 (@var{x})} equals @code{log (@var{x}) / log (10)}. +@end deftypefun + +@comment math.h +@comment ANSI +@deftypefun double pow (double @var{base}, double @var{power}) +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 +@item EDOM +The argument @var{base} is negative and @var{power} is not an integral +value. Mathematically, the result would be a complex number in this case. + +@item ERANGE +An underflow or overflow condition was detected in the result. +@end table +@end deftypefun + +@cindex square root function +@comment math.h +@comment ANSI +@deftypefun double sqrt (double @var{x}) +This function returns the nonnegative square root of @var{x}. + +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 BSD +@deftypefun double cbrt (double @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 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.) See also the function +@code{cabs} in @ref{Absolute Value}. +@end deftypefun + +@comment math.h +@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 +near zero---a case where @code{exp (@var{x}) - 1} would be inaccurate due +to subtraction of two numbers that are nearly equal. +@end deftypefun + +@comment math.h +@comment BSD +@deftypefun double log1p (double @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 + +@node Hyperbolic Functions +@section Hyperbolic Functions +@cindex hyperbolic functions + +The functions in this section are related to the exponential functions; +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 @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 @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}, whose +mathematical definition is @w{@code{sinh (@var{x}) / cosh (@var{x})}}. +@end deftypefun + +@cindex inverse hyperbolic functions + +@comment math.h +@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 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 +@code{1}, @code{acosh} returns @code{HUGE_VAL}. +@end deftypefun + +@comment math.h +@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 +@var{x} is greater than or equal to @code{1}, @code{atanh} returns +@code{HUGE_VAL}. +@end deftypefun + +@node Pseudo-Random Numbers +@section Pseudo-Random Numbers +@cindex random numbers +@cindex pseudo-random numbers +@cindex seed (for random numbers) + +This section describes the GNU facilities for generating a series of +pseudo-random 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 pseudo-random, 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 Random:: @code{rand} and friends. +* BSD Random:: @code{random} and friends. +@end menu + +@node ANSI Random +@subsection ANSI C Random Number Functions + +This section describes the random number functions that are part of +the ANSI C standard. + +To use these facilities, you should include the header file +@file{stdlib.h} in your program. +@pindex stdlib.h + +@comment stdlib.h +@comment ANSI +@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}, 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 () +The @code{rand} function returns the next pseudo-random number in the +series. The value is in the range from @code{0} to @code{RAND_MAX}. +@end deftypefun + +@comment stdlib.h +@comment ANSI +@deftypefun void srand (unsigned int @var{seed}) +This function establishes @var{seed} as the seed for a new series of +pseudo-random numbers. If you call @code{rand} before a seed has been +established with @code{srand}, it uses the value @code{1} as a default +seed. + +To produce truly random numbers (not just pseudo-random), do @code{srand +(time (0))}. +@end deftypefun + +@node BSD Random +@subsection BSD Random Number Functions + +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 () +This function returns the next pseudo-random number in the sequence. +The range of values returned is from @code{0} to @code{RAND_MAX}. +@end deftypefun + +@comment stdlib.h +@comment BSD +@deftypefun void srandom (unsigned int @var{seed}) +The @code{srandom} function sets the seed for the current random number +state based on the integer @var{seed}. If you supply a @var{seed} value +of @code{1}, this will cause @code{random} to reproduce the default set +of random numbers. + +To produce truly random numbers (not just pseudo-random), do +@code{srandom (time (0))}. +@end deftypefun + +@comment stdlib.h +@comment BSD +@deftypefun {void *} initstate (unsigned int @var{seed}, void *@var{state}, size_t @var{size}) +The @code{initstate} function is used to initialize the random number +generator state. The argument @var{state} is an array of @var{size} +bytes, used to hold the state information. The size must be at least 8 +bytes, and optimal sizes are 8, 16, 32, 64, 128, and 256. The bigger +the @var{state} array, the better. + +The return value is the previous value of the state information array. +You can use this value later as an argument to @code{setstate} to +restore that state. +@end deftypefun + +@comment stdlib.h +@comment BSD +@deftypefun {void *} setstate (void *@var{state}) +The @code{setstate} function restores the random number state +information @var{state}. The argument must have been the result of +a previous call to @var{initstate} or @var{setstate}. + +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 |