diff options
Diffstat (limited to 'manual')
| -rw-r--r-- | manual/arith.texi | 404 | ||||
| -rw-r--r-- | manual/math.texi | 840 | ||||
| -rw-r--r-- | manual/string.texi | 81 |
3 files changed, 1251 insertions, 74 deletions
diff --git a/manual/arith.texi b/manual/arith.texi index d8703ea6c1..86fb2667a0 100644 --- a/manual/arith.texi +++ b/manual/arith.texi @@ -3,12 +3,17 @@ 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}. +fractional parts or retrieving the imaginary part of a complex value. +These functions are declared in the header files @file{math.h} and +@file{complex.h}. @menu +* Infinity:: What is Infinity and how to test for it. * Not a Number:: Making NaNs and testing for NaNs. +* Imaginary Unit:: Constructing complex Numbers. * Predicates on Floats:: Testing for infinity and for NaNs. +* Floating-Point Classes:: Classifiy floating-point numbers. +* Operations on Complex:: Projections, Conjugates, and Decomposing. * Absolute Value:: Absolute value functions. * Normalization Functions:: Hacks for radix-2 representations. * Rounding and Remainders:: Determining the integer and @@ -19,6 +24,44 @@ fractional parts. These functions are declared in the header file from strings. @end menu +@node Infinity +@section Infinity Values +@cindex Infinity +@cindex IEEE floating point + +Mathematical operations easily can produce as the result values which +are not representable by the floating-point format. The functions in +the mathematics library also have this problem. The situation is +generally solved by raising an overflow exception and by returning a +huge value. + +The @w{IEEE 754} floating-point defines a special value to be used in +these situations. There is a special value for infinity. + +@comment math.h +@comment ISO +@deftypevr Macro float_t INFINITY +A expression representing the inifite value. @code{INFINITY} values are +produce by mathematical operations like @code{1.0 / 0.0}. It is +possible to continue the computations with this value since the basic +operations as well as the mathematical library functions are prepared to +handle values like this. + +Beside @code{INFINITY} also the value @code{-INIFITY} is representable +and it is handled differently if needed. It is possible to test a +variables for infinite value using a simple comparison but the +recommended way is to use the the @code{isinf} function. + +This macro was introduced in the @w{ISO C 9X} standard. +@end deftypevr + +@vindex HUGE_VAL +The macros @code{HUGE_VAL}, @code{HUGE_VALF} and @code{HUGE_VALL} are +defined in a similar way but they are not required to represent the +infinite value, only a very large value (@pxref{Domain and Range Errors}). +If actually infinity is wanted, @code{INFINITY} should be used. + + @node Not a Number @section ``Not a Number'' Values @cindex NaN @@ -54,6 +97,46 @@ such as by defining @code{_GNU_SOURCE}, and then you must include @file{math.h}.) @end deftypevr +@node Imaginary Unit +@section Constructing complex Numbers + +@pindex complex.h +To construct complex numbers it is necessary have a way to express the +imaginary part of the numbers. In mathematics one uses the symbol ``i'' +to mark a number as imaginary. For convenienve the @file{complex.h} +header defines two macros which allow to use a similar easy notation. + +@deftypevr Macro float_t _Imaginary_I +This macro is a (compiler specific) representation of the value ``1i''. +I.e., it is the value for which + +@smallexample +_Imaginary_I * _Imaginary_I = -1 +@end smallexample + +@noindent +One can use it to easily construct complex number like in + +@smallexample +3.0 - _Imaginary_I * 4.0 +@end smallexample + +@noindent +which results in the complex number with a real part of 3.0 and a +imaginary part -4.0. +@end deftypevr + +@noindent +A more intuitive approach is to use the following macro. + +@deftypevr Macro float_t I +This macro has exactly the same value as @code{_Imaginary_I}. The +problem is that the name @code{I} very easily can clash with macros or +variables in programs and so it might be a good idea to avoid this name +and stay at the safe side by using @code{_Imaginary_I}. +@end deftypevr + + @node Predicates on Floats @section Predicates on Floats @@ -66,6 +149,10 @@ functions, and thus are available if you define @code{_BSD_SOURCE} or @comment math.h @comment BSD @deftypefun int isinf (double @var{x}) +@end deftypefun +@deftypefun int isinff (float @var{x}) +@end deftypefun +@deftypefun int isinfl (long 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 @@ -73,6 +160,10 @@ This function returns @code{-1} if @var{x} represents negative infinity, @comment math.h @comment BSD @deftypefun int isnan (double @var{x}) +@end deftypefun +@deftypefun int isnanf (float @var{x}) +@end deftypefun +@deftypefun int isnanl (long double @var{x}) This function returns a nonzero value if @var{x} is a ``not a number'' value, and zero otherwise. (You can just as well use @code{@var{x} != @var{x}} to get the same result). @@ -81,6 +172,10 @@ value, and zero otherwise. (You can just as well use @code{@var{x} != @comment math.h @comment BSD @deftypefun int finite (double @var{x}) +@end deftypefun +@deftypefun int finitef (float @var{x}) +@end deftypefun +@deftypefun int finitel (long 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 @@ -103,6 +198,189 @@ does not fit the @w{ISO C} specification. @strong{Portability Note:} The functions listed in this section are BSD extensions. +@node Floating-Point Classes +@section Floating-Point Number Classification Functions + +Instead of using the BSD specific functions from the last section it is +better to use those in this section will are introduced in the @w{ISO C +9X} standard and are therefore widely available. + +@comment math.h +@comment ISO +@deftypefun int fpclassify (@emph{float-type} @var{x}) +This is a generic macro which works on all floating-point types and +which returns a value of type @code{int}. The possible values are: + +@vtable @code +@item FP_NAN + The floating-point number @var{x} is ``Not a Number'' (@pxref{Not a Number}) +@item FP_INFINITE + The value of @var{x} is either plus or minus infinity (@pxref{Infinity}) +@item FP_ZERO + The value of @var{x} is zero. In floating-point formats like @w{IEEE + 754} where the zero value can be signed this value is also returned if + @var{x} is minus zero. +@item FP_SUBNORMAL + Some floating-point formats (such as @w{IEEE 754}) allow floating-point + numbers to be represented in a denormalized format. This happens if the + absolute value of the number is too small to be represented in the + normal format. @code{FP_SUBNORMAL} is returned for such values of @var{x}. +@item FP_NORMAL + This value is returned for all other cases which means the number is a + plain floating-point number without special meaning. +@end vtable + +This macro is useful if more than property of a number must be +tested. If one only has to test for, e.g., a NaN value, there are +function which are faster. +@end deftypefun + +The remainder of this section introduces some more specific functions. +They might be implemented faster than the call to @code{fpclassify} and +if the actual need in the program is covered be these functions they +should be used (and not @code{fpclassify}). + +@comment math.h +@comment ISO +@deftypefun int isfinite (@emph{float-type} @var{x}) +The value returned by this macro is nonzero if the value of @var{x} is +not plus or minus infinity and not NaN. I.e., it could be implemented as + +@smallexample +(fpclassify (x) != FP_NAN && fpclassify (x) != FP_INFINITE) +@end smallexample + +@code{isfinite} is also implemented as a macro which can handle all +floating-point types. Programs should use this function instead of +@var{finite} (@pxref{Predicates on Floats}). +@end deftypefun + +@comment math.h +@comment ISO +@deftypefun int isnormal (@emph{float-type} @var{x}) +If @code{isnormal} returns a nonzero value the value or @var{x} is +neither a NaN, infinity, zero, nor a denormalized number. I.e., it +could be implemented as + +@smallexample +(fpclassify (x) == FP_NORMAL) +@end smallexample +@end deftypefun + +@comment math.h +@comment ISO +@deftypefun int isnan (@emph{float-type} @var{x}) +The situation with this macro is a bit complicated. Here @code{isnan} +is a macro which can handle all kinds of floating-point types. It +returns a nonzero value is @var{x} does not represent a NaN value and +could be written like this + +@smallexample +(fpclassify (x) == FP_NAN) +@end smallexample + +The complication is that there is a function of the same name and the +same semantic defined for compatibility with BSD (@pxref{Predicates on +Floats}). Fortunately this should not yield to problems in most cases +since the macro and the function have the same semantic. Should in a +situation the function be absolutely necessary one can use + +@smallexample +(isnan) (x) +@end smallexample + +@noindent +to avoid the macro expansion. Using the macro has two big adavantages: +it is more portable and one does not have to choose the right function +among @code{isnan}, @code{isnanf}, and @code{isnanl}. +@end deftypefun + + +@node Operations on Complex +@section Projections, Conjugates, and Decomposing of Complex Numbers +@cindex project complex numbers +@cindex conjugate complex numbers +@cindex decompose complex numbers + +This section lists functions performing some of the simple mathematical +operations on complex numbers. Using any of the function requries that +the C compiler understands the @code{complex} keyword, introduced to the +C language in the @w{ISO C 9X} standard. + +@pindex complex.h +The prototypes for all functions in this section can be found in +@file{complex.h}. All functions are available in three variants, one +for each of the three floating-point types. + +The easiest operation on complex numbers is the decomposition in the +real part and the imaginary part. This is done by the next two +functions. + +@comment complex.h +@comment ISO +@deftypefun double creal (complex double @var{z}) +@end deftypefun +@deftypefun float crealf (complex float @var{z}) +@end deftypefun +@deftypefun {long double} creall (complex long double @var{z}) +These functions return the real part of the complex number @var{z}. +@end deftypefun + +@comment complex.h +@comment ISO +@deftypefun double cimag (complex double @var{z}) +@end deftypefun +@deftypefun float cimagf (complex float @var{z}) +@end deftypefun +@deftypefun {long double} cimagl (complex long double @var{z}) +These functions return the imaginary part of the complex number @var{z}. +@end deftypefun + + +The conjugate complex value of a given complex number has the same value +for the real part but the complex part is negated. + +@comment complex.h +@comment ISO +@deftypefun {complex double} conj (complex double @var{z}) +@end deftypefun +@deftypefun {complex float} conjf (complex float @var{z}) +@end deftypefun +@deftypefun {complex long double} conjl (complex long double @var{z}) +These functions return the conjugate complex value of the complex number +@var{z}. +@end deftypefun + +@comment complex.h +@comment ISO +@deftypefun double carg (complex double @var{z}) +@end deftypefun +@deftypefun float cargf (complex float @var{z}) +@end deftypefun +@deftypefun {long double} cargl (complex long double @var{z}) +These functions return argument of the complex number @var{z}. + +Mathematically, the argument is the phase angle of @var{z} with a branch +cut along the negative real axis. +@end deftypefun + +@comment complex.h +@comment ISO +@deftypefun {complex double} cproj (complex double @var{z}) +@end deftypefun +@deftypefun {complex float} cprojf (complex float @var{z}) +@end deftypefun +@deftypefun {complex long double} cprojl (complex long double @var{z}) +Return the projection of the complex value @var{z} on the Riemann +sphere. Values with a infinite complex part (even if the real part +is NaN) are projected to positive infinte on the real axis. If the real part is infinite, the result is equivalent to + +@smallexample +INFINITY + I * copysign (0.0, cimag (z)) +@end smallexample +@end deftypefun + + @node Absolute Value @section Absolute Value @cindex absolute value functions @@ -117,7 +395,8 @@ whose imaginary part is @var{y}, the absolute value is @w{@code{sqrt @pindex math.h @pindex stdlib.h Prototypes for @code{abs} and @code{labs} are in @file{stdlib.h}; -@code{fabs} and @code{cabs} are declared in @file{math.h}. +@code{fabs}, @code{fabsf} and @code{fabsl} are declared in @file{math.h}; +@code{cabs}, @code{cabsf} and @code{cabsl} are declared in @file{complex.h}. @comment stdlib.h @comment ISO @@ -139,20 +418,28 @@ are of type @code{long int} rather than @code{int}. @comment math.h @comment ISO @deftypefun double fabs (double @var{number}) +@end deftypefun +@deftypefun float fabsf (float @var{number}) +@end deftypefun +@deftypefun {long double} fabsl (long double @var{number}) This function returns the absolute value of the floating-point number @var{number}. @end deftypefun -@comment math.h -@comment BSD -@deftypefun double cabs (struct @{ double real, imag; @} @var{z}) -The @code{cabs} function returns the absolute value of the complex -number @var{z}, whose real part is @code{@var{z}.real} and whose -imaginary part is @code{@var{z}.imag}. (See also the function -@code{hypot} in @ref{Exponents and Logarithms}.) The value is: +@comment complex.h +@comment ISO +@deftypefun double cabs (complex double @var{z}) +@end deftypefun +@deftypefun float cabsf (complex float @var{z}) +@end deftypefun +@deftypefun {long double} cabsl (complex long double @var{z}) +These functions return the absolute value of the complex number @var{z}. +The compiler must support complex numbers to use these functions. (See +also the function @code{hypot} in @ref{Exponents and Logarithms}.) The +value is: @smallexample -sqrt (@var{z}.real*@var{z}.real + @var{z}.imag*@var{z}.imag) +sqrt (creal (@var{z}) * creal (@var{z}) + cimag (@var{z}) * cimag (@var{z})) @end smallexample @end deftypefun @@ -174,7 +461,11 @@ All these functions are declared in @file{math.h}. @comment math.h @comment ISO @deftypefun double frexp (double @var{value}, int *@var{exponent}) -The @code{frexp} function is used to split the number @var{value} +@end deftypefun +@deftypefun float frexpf (float @var{value}, int *@var{exponent}) +@end deftypefun +@deftypefun {long double} frexpl (long double @var{value}, int *@var{exponent}) +These functions are used to split the number @var{value} into a normalized fraction and an exponent. If the argument @var{value} is not zero, the return value is @var{value} @@ -193,7 +484,11 @@ zero is stored in @code{*@var{exponent}}. @comment math.h @comment ISO @deftypefun double ldexp (double @var{value}, int @var{exponent}) -This function returns the result of multiplying the floating-point +@end deftypefun +@deftypefun float ldexpf (float @var{value}, int @var{exponent}) +@end deftypefun +@deftypefun {long double} ldexpl (long double @var{value}, int @var{exponent}) +These functions return the result of multiplying the floating-point number @var{value} by 2 raised to the power @var{exponent}. (It can be used to reassemble floating-point numbers that were taken apart by @code{frexp}.) @@ -207,13 +502,21 @@ equivalent to those of @code{ldexp} and @code{frexp}: @comment math.h @comment BSD @deftypefun double scalb (double @var{value}, int @var{exponent}) +@end deftypefun +@deftypefun float scalbf (float @var{value}, int @var{exponent}) +@end deftypefun +@deftypefun {long double} scalbl (long double @var{value}, int @var{exponent}) The @code{scalb} function is the BSD name for @code{ldexp}. @end deftypefun @comment math.h @comment BSD @deftypefun double logb (double @var{x}) -This BSD function returns the integer part of the base-2 logarithm of +@end deftypefun +@deftypefun float logbf (float @var{x}) +@end deftypefun +@deftypefun {long double} logbl (long double @var{x}) +These BSD functions return the integer part of the base-2 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}. The sign of @var{x} is ignored. For example, @code{logb (3.5)} is @code{1.0} and @@ -231,11 +534,28 @@ The value returned by @code{logb} is one less than the value that @end deftypefun @comment math.h -@comment BSD +@comment ISO @deftypefun double copysign (double @var{value}, double @var{sign}) -The @code{copysign} function returns a value whose absolute value is the +@end deftypefun +@deftypefun float copysignf (float @var{value}, float @var{sign}) +@end deftypefun +@deftypefun {long double} copysignl (long double @var{value}, long double @var{sign}) +These functions return a value whose absolute value is the same as that of @var{value}, and whose sign matches that of @var{sign}. -This is a BSD function. +This function appears in BSD and was standardized in @w{ISO C 9X}. +@end deftypefun + +@comment math.h +@comment ISO +@deftypefun int signbit (@emph{float-type} @var{x}) +@code{signbit} is a generic macro which can work on all floating-point +types. It returns a nonzero value if the value of @var{x} has its sign +bit set. + +This is not the same as @code{x < 0.0} since in some floating-point +formats (e.g., @w{IEEE 754}) the zero value is optionally signed. The +comparison @code{-0.0 < 0.0} will not be true while @code{signbit +(-0.0)} will return a nonzeri value. @end deftypefun @node Rounding and Remainders @@ -260,7 +580,11 @@ result as a @code{double} instead to get around this problem. @comment math.h @comment ISO @deftypefun double ceil (double @var{x}) -The @code{ceil} function rounds @var{x} upwards to the nearest integer, +@end deftypefun +@deftypefun float ceilf (float @var{x}) +@end deftypefun +@deftypefun {long double} ceill (long double @var{x}) +These functions round @var{x} upwards to the nearest integer, returning that value as a @code{double}. Thus, @code{ceil (1.5)} is @code{2.0}. @end deftypefun @@ -268,15 +592,23 @@ is @code{2.0}. @comment math.h @comment ISO @deftypefun double floor (double @var{x}) -The @code{ceil} function rounds @var{x} downwards to the nearest +@end deftypefun +@deftypefun float floorf (float @var{x}) +@end deftypefun +@deftypefun {long double} floorl (long double @var{x}) +These functions round @var{x} downwards to the nearest integer, returning that value as a @code{double}. Thus, @code{floor (1.5)} is @code{1.0} and @code{floor (-1.5)} is @code{-2.0}. @end deftypefun @comment math.h -@comment BSD +@comment ISO @deftypefun double rint (double @var{x}) -This function rounds @var{x} to an integer value according to the +@end deftypefun +@deftypefun float rintf (float @var{x}) +@end deftypefun +@deftypefun {long double} rintl (long double @var{x}) +These functions round @var{x} to an integer value according to the current rounding mode. @xref{Floating Point Parameters}, for information about the various rounding modes. The default rounding mode is to round to the nearest integer; some machines @@ -286,8 +618,24 @@ you explicit select another. @comment math.h @comment ISO +@deftypefun double nearbyint (double @var{x}) +@end deftypefun +@deftypefun float nearbyintf (float @var{x}) +@end deftypefun +@deftypefun {long double} nearbyintl (long double @var{x}) +These functions return the same value as the @code{rint} functions but +even some rounding actually takes place @code{nearbyint} does @emph{not} +raise the inexact exception. +@end deftypefun + +@comment math.h +@comment ISO @deftypefun double modf (double @var{value}, double *@var{integer-part}) -This function breaks the argument @var{value} into an integer part and a +@end deftypefun +@deftypefun float modff (flaot @var{value}, float *@var{integer-part}) +@end deftypefun +@deftypefun {long double} modfl (long double @var{value}, long double *@var{integer-part}) +These functions break the argument @var{value} into an integer part and a fractional part (between @code{-1} and @code{1}, exclusive). 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. @@ -300,7 +648,11 @@ returns @code{0.5} and stores @code{2.0} into @code{intpart}. @comment math.h @comment ISO @deftypefun double fmod (double @var{numerator}, double @var{denominator}) -This function computes the remainder from the division of +@end deftypefun +@deftypefun float fmodf (float @var{numerator}, float @var{denominator}) +@end deftypefun +@deftypefun {long double} fmodl (long double @var{numerator}, long double @var{denominator}) +These functions compute the remainder from the division of @var{numerator} by @var{denominator}. Specifically, the return value is @code{@var{numerator} - @w{@var{n} * @var{denominator}}}, where @var{n} is the quotient of @var{numerator} divided by @var{denominator}, rounded @@ -317,7 +669,11 @@ If @var{denominator} is zero, @code{fmod} fails and sets @code{errno} to @comment math.h @comment BSD @deftypefun double drem (double @var{numerator}, double @var{denominator}) -The function @code{drem} is like @code{fmod} except that it rounds the +@end deftypefun +@deftypefun float dremf (float @var{numerator}, float @var{denominator}) +@end deftypefun +@deftypefun {long double} dreml (long double @var{numerator}, long double @var{denominator}) +These functions are like @code{fmod} etc except that it rounds the internal quotient @var{n} to the nearest integer instead of towards zero to an integer. For example, @code{drem (6.5, 2.3)} returns @code{-0.4}, which is @code{6.5} minus @code{6.9}. diff --git a/manual/math.texi b/manual/math.texi index 543647297f..78d567b367 100644 --- a/manual/math.texi +++ b/manual/math.texi @@ -7,14 +7,22 @@ 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}. +For all functions which take a single floating-point argument and for +several other functions as well there are three different functions +available for the type @code{double}, @code{float}, and @code{long +double}. The @code{double} versions of the functions are mostly defined +even in the @w{ISO C 89} standard. The @code{float} and @code{long +double} variants are introduced in the numeric extensions for the C +language which are part of the @w{ISO C 9X} standard. + +Which of the three versions of the function should be used depends on +the situation. For most functions and implementation it is true that +speed and precision do not go together. I.e., the @code{float} versions +are normally faster than the @code{double} and @code{long double} +versions. On the other hand the @code{long double} version has the +highest precision. One should always think about the actual needs and +in case of double using @code{double} is a good compromise. + @menu * Domain and Range Errors:: Detecting overflow conditions and the like. @@ -119,11 +127,15 @@ 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: +The math library does define a symbolic constant for pi in @file{math.h} +when BSD compliance is required (@pxref{Feature Test Macros}). Beside +pi several other constants are defined. + +@noindent +In case it is not possible to use this macro one easily can define it: @smallexample -#define PI 3.14159265358979323846264338327 +#define M_PI 3.14159265358979323846264338327 @end smallexample @noindent @@ -134,21 +146,33 @@ You can also compute the value of pi with the expression @code{acos @comment math.h @comment ISO @deftypefun double sin (double @var{x}) -This function returns the sine of @var{x}, where @var{x} is given in +@end deftypefun +@deftypefun float sinf (float @var{x}) +@end deftypefun +@deftypefun {long double} sinl (long double @var{x}) +These functions return 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 ISO @deftypefun double cos (double @var{x}) -This function returns the cosine of @var{x}, where @var{x} is given in +@end deftypefun +@deftypefun float cosf (float @var{x}) +@end deftypefun +@deftypefun {long double} cosl (long double @var{x}) +These functions return 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 ISO @deftypefun double tan (double @var{x}) -This function returns the tangent of @var{x}, where @var{x} is given in +@end deftypefun +@deftypefun float tanf (float @var{x}) +@end deftypefun +@deftypefun {long double} tanl (long double @var{x}) +These functions return the tangent of @var{x}, where @var{x} is given in radians. The following @code{errno} error conditions are defined for this function: @@ -162,6 +186,76 @@ either positive or negative @code{HUGE_VAL}. @end table @end deftypefun +In many applications where @code{sin} and @code{cos} are used, the value +for the same argument of both of these functions is used at the same +time. Since the algorithm to compute these values is very similar for +both functions there is an additional function with computes both values +at the same time. + +@comment math.h +@comment GNU +@deftypefun void sincos (double @var{x}, double *@var{sinx}, double *@var{cosx}) +@end deftypefun +@deftypefun void sincosf (float @var{x}, float *@var{sinx}, float *@var{cosx}) +@end deftypefun +@deftypefun void sincosl (long double @var{x}, long double *@var{sinx}, long double *@var{cosx}) +These functions return the sine of @var{x} in @code{*@var{sinx}} and the +cosine of @var{x} in @code{*@var{cos}}, where @var{x} is given in +radians. Both values, @code{*@var{sinx}} and @code{*@var{cosx}}, are in +the range of @code{-1} to @code{1}. +@end deftypefun + +@cindex complex trigonometric functions + +The trigonometric functions are in mathematics not only on real numbers. +They can be extended to complex numbers and the @w{ISO C 9X} standard +introduces these variants in the standard math library. + +@comment complex.h +@comment ISO +@deftypefun {complex double} csin (complex double @var{z}) +@end deftypefun +@deftypefun {complex float} csinf (complex float @var{z}) +@end deftypefun +@deftypefun {complex long double} csinl (complex long double @var{z}) +These functions return the complex sine of the complex value in @var{z}. +The mathematical definition of the complex sine is + +@smallexample +sin (z) = 1/(2*i) * (exp (z*i) - exp (-z*i)) +@end smallexample +@end deftypefun + +@comment complex.h +@comment ISO +@deftypefun {complex double} ccos (complex double @var{z}) +@end deftypefun +@deftypefun {complex float} ccosf (complex float @var{z}) +@end deftypefun +@deftypefun {complex long double} ccosl (complex long double @var{z}) +These functions return the complex cosine of the complex value in @var{z}. +The mathematical definition of the complex cosine is + +@smallexample +cos (z) = 1/2 * (exp (z*i) + exp (-z*i)) +@end smallexample +@end deftypefun + +@comment complex.h +@comment ISO +@deftypefun {complex double} ctan (complex double @var{z}) +@end deftypefun +@deftypefun {complex float} ctanf (complex float @var{z}) +@end deftypefun +@deftypefun {complex long double} ctanl (complex long double @var{z}) +These functions return the complex tangent of the complex value in @var{z}. +The mathematical definition of the complex tangent is + +@smallexample +tan (z) = 1/i * (exp (z*i) - exp (-z*i)) / (exp (z*i) + exp (-z*i)) +@end smallexample +@end deftypefun + @node Inverse Trig Functions @section Inverse Trigonometric Functions @@ -174,7 +268,11 @@ respectively. @comment math.h @comment ISO @deftypefun double asin (double @var{x}) -This function computes the arc sine of @var{x}---that is, the value whose +@end deftypefun +@deftypefun float asinf (float @var{x}) +@end deftypefun +@deftypefun {long double} asinl (long double @var{x}) +These functions compute 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). @@ -187,7 +285,11 @@ over the domain @code{-1} to @code{1}. @comment math.h @comment ISO @deftypefun double acos (double @var{x}) -This function computes the arc cosine of @var{x}---that is, the value +@end deftypefun +@deftypefun float acosf (float @var{x}) +@end deftypefun +@deftypefun {long double} acosl (long double @var{x}) +These functions compute 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). @@ -201,7 +303,11 @@ over the domain @code{-1} to @code{1}. @comment math.h @comment ISO @deftypefun double atan (double @var{x}) -This function computes the arc tangent of @var{x}---that is, the value +@end deftypefun +@deftypefun float atanf (float @var{x}) +@end deftypefun +@deftypefun {long double} atanl (long double @var{x}) +These functions compute 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} @@ -211,6 +317,10 @@ returned is the one between @code{-pi/2} and @code{pi/2} @comment math.h @comment ISO @deftypefun double atan2 (double @var{y}, double @var{x}) +@end deftypefun +@deftypefun float atan2f (float @var{y}, float @var{x}) +@end deftypefun +@deftypefun {long double} atan2l (long double @var{y}, long 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 @@ -229,6 +339,51 @@ The function @code{atan2} sets @code{errno} to @code{EDOM} if both case. @end deftypefun +@cindex inverse complex trigonometric functions + +The inverse trigonometric functions also exist is separate versions +which are usable with complex numbers. + +@comment complex.h +@comment ISO +@deftypefun {complex double} casin (complex double @var{z}) +@end deftypefun +@deftypefun {complex float} casinf (complex float @var{z}) +@end deftypefun +@deftypefun {complex long double} casinl (complex long double @var{z}) +These functions compute the complex arc sine of @var{z}---that is, the +value whose sine is @var{z}. The value is in units of radians. + +Unlike the real version of the arc sine function @code{casin} has no +limitation on the argument @var{z}. +@end deftypefun + +@comment complex.h +@comment ISO +@deftypefun {complex double} cacos (complex double @var{z}) +@end deftypefun +@deftypefun {complex float} cacosf (complex float @var{z}) +@end deftypefun +@deftypefun {complex long double} cacosl (complex long double @var{z}) +These functions compute the complex arc cosine of @var{z}---that is, the +value whose cosine is @var{z}. The value is in units of radians. + +Unlike the real version of the arc cosine function @code{cacos} has no +limitation on the argument @var{z}. +@end deftypefun + + +@comment complex.h +@comment ISO +@deftypefun {complex double} catan (complex double @var{z}) +@end deftypefun +@deftypefun {complex float} catanf (complex float @var{z}) +@end deftypefun +@deftypefun {complex long double} catanl (complex long double @var{z}) +These functions compute the complex arc tangent of @var{z}---that is, +the value whose tangent is @var{z}. The value is in units of radians. +@end deftypefun + @node Exponents and Logarithms @section Exponentiation and Logarithms @@ -239,7 +394,11 @@ case. @comment math.h @comment ISO @deftypefun double exp (double @var{x}) -The @code{exp} function returns the value of e (the base of natural +@end deftypefun +@deftypefun float expf (float @var{x}) +@end deftypefun +@deftypefun {long double} expl (long double @var{x}) +These functions return the value of @code{e} (the base of natural logarithms) raised to power @var{x}. The function fails, and sets @code{errno} to @code{ERANGE}, if the @@ -248,8 +407,41 @@ magnitude of the result is too large to be representable. @comment math.h @comment ISO +@deftypefun double exp10 (double @var{x}) +@end deftypefun +@deftypefun float exp10f (float @var{x}) +@end deftypefun +@deftypefun {long double} exp10l (long double @var{x}) +These functions return the value of @code{10} raised to the power @var{x}. +Mathematically, @code{exp10 (x)} is the same as @code{exp (x * log (10))}. + +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 ISO +@deftypefun double exp2 (double @var{x}) +@end deftypefun +@deftypefun float exp2f (float @var{x}) +@end deftypefun +@deftypefun {long double} exp2l (long double @var{x}) +These functions return the value of @code{2} raised to the power @var{x}. +Mathematically, @code{exp2 (x)} is the same as @code{exp (x * log (2))}. + +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 ISO @deftypefun double log (double @var{x}) -This function returns the natural logarithm of @var{x}. @code{exp (log +@end deftypefun +@deftypefun float logf (floatdouble @var{x}) +@end deftypefun +@deftypefun {long double} logl (long double @var{x}) +These functions return the natural logarithm of @var{x}. @code{exp (log (@var{x}))} equals @var{x}, exactly in mathematics and approximately in C. @@ -268,15 +460,35 @@ The argument is zero. The log of zero is not defined. @comment math.h @comment ISO @deftypefun double log10 (double @var{x}) -This function returns the base-10 logarithm of @var{x}. Except for the +@end deftypefun +@deftypefun float log10f (float @var{x}) +@end deftypefun +@deftypefun {long double} log10l (long double @var{x}) +These functions return 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 ISO +@deftypefun double log2 (double @var{x}) +@end deftypefun +@deftypefun float log2f (float @var{x}) +@end deftypefun +@deftypefun {long double} log2l (long double @var{x}) +These functions return the base-2 logarithm of @var{x}. Except for the +different base, it is similar to the @code{log} function. In fact, +@code{log2 (@var{x})} equals @code{log (@var{x}) / log (2)}. +@end deftypefun + +@comment math.h +@comment ISO @deftypefun double pow (double @var{base}, double @var{power}) -This is a general exponentiation function, returning @var{base} raised +@end deftypefun +@deftypefun float powf (float @var{base}, float @var{power}) +@end deftypefun +@deftypefun {long double} powl (long double @var{base}, long double @var{power}) +These are general exponentiation functions, returning @var{base} raised to @var{power}. @need 250 @@ -296,48 +508,142 @@ An underflow or overflow condition was detected in the result. @comment math.h @comment ISO @deftypefun double sqrt (double @var{x}) -This function returns the nonnegative square root of @var{x}. +@end deftypefun +@deftypefun float sqrtf (float @var{x}) +@end deftypefun +@deftypefun {long double} sqrtl (long double @var{x}) +These functions return 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. +@c (@pxref{csqrt}) @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 +@end deftypefun +@deftypefun float cbrtf (float @var{x}) +@end deftypefun +@deftypefun {long double} cbrtl (long double @var{x}) +These functions return the cube root of @var{x}. They cannot fail; every representable real value has a representable real cube root. @end deftypefun @comment math.h -@comment BSD +@comment ISO @deftypefun double hypot (double @var{x}, double @var{y}) -The @code{hypot} function returns @code{sqrt (@var{x}*@var{x} + +@end deftypefun +@deftypefun float hypotf (float @var{x}, float @var{y}) +@end deftypefun +@deftypefun {long double} hypotl (long double @var{x}, long double @var{y}) +These functions return @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}. +of the point (@var{x}, @var{y}) from the origin.) Using this function +instead of the direct formula is highly appreciated since the error is +much smaller. See also the function @code{cabs} in @ref{Absolute Value}. @end deftypefun @comment math.h -@comment BSD +@comment ISO @deftypefun double expm1 (double @var{x}) -This function returns a value equivalent to @code{exp (@var{x}) - 1}. +@end deftypefun +@deftypefun float expm1f (float @var{x}) +@end deftypefun +@deftypefun {long double} expm1l (long double @var{x}) +These functions return 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 +@comment ISO @deftypefun double log1p (double @var{x}) +@end deftypefun +@deftypefun float log1pf (float @var{x}) +@end deftypefun +@deftypefun {long double} log1pl (long 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 +@cindex complex exponentiation functions +@cindex complex logarithm functions + +@w{ISO C 9X} defines variants of some of the exponentiation and +logarithm functions. As for the other functions handlung complex +numbers these functions are perhaps better optimized and provide better +error checking than a direct use of the formulas of the mathematical +definition. + +@comment complex.h +@comment ISO +@deftypefun {complex double} cexp (complex double @var{z}) +@end deftypefun +@deftypefun {complex float} cexpf (complex float @var{z}) +@end deftypefun +@deftypefun {complex long double} cexpl (complex long double @var{z}) +These functions return the value of @code{e} (the base of natural +logarithms) raised to power of the complex value @var{z}. + +Mathematically this corresponds to the value + +@smallexample +exp (z) = exp (creal (z)) * (cos (cimag (z)) + I * sin (cimag (z))) +@end smallexample +@end deftypefun + +@comment complex.h +@comment ISO +@deftypefun {complex double} clog (complex double @var{z}) +@end deftypefun +@deftypefun {complex float} clogf (complex float @var{z}) +@end deftypefun +@deftypefun {complex long double} clogl (complex long double @var{z}) +These functions return the natural logarithm of the complex value +@var{z}. Unlike the real value version @code{log} and its variants, +@code{clog} has no limit for the range of its argument @var{z}. + +Mathematically this corresponds to the value + +@smallexample +log (z) = log (cabs (z)) + I * carg (z) +@end smallexample +@end deftypefun + +@comment complex.h +@comment ISO +@deftypefun {complex double} csqrt (complex double @var{z}) +@end deftypefun +@deftypefun {complex float} csqrtf (complex float @var{z}) +@end deftypefun +@deftypefun {complex long double} csqrtl (complex long double @var{z}) +These functions return the complex root of the argument @var{z}. Unlike +the @code{sqrt} function these functions do not have any restriction on +the value of the argument. +@end deftypefun + +@comment complex.h +@comment ISO +@deftypefun {complex double} cpow (complex double @var{base}, complex double @var{power}) +@end deftypefun +@deftypefun {complex float} cpowf (complex float @var{base}, complex float @var{power}) +@end deftypefun +@deftypefun {complex long double} cpowl (complex long double @var{base}, complex long double @var{power}) +These functions return the complex value @var{BASE} raised to the power of +@var{power}. This is computed as + +@smallexample +cpow (x, y) = cexp (y * clog (x)) +@end smallexample +@end deftypefun + + @node Hyperbolic Functions @section Hyperbolic Functions @cindex hyperbolic functions @@ -348,8 +654,12 @@ see @ref{Exponents and Logarithms}. @comment math.h @comment ISO @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 +@end deftypefun +@deftypefun float sinhf (float @var{x}) +@end deftypefun +@deftypefun {long double} sinhl (long double @var{x}) +These functions return 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 @@ -357,8 +667,12 @@ function fails, and sets @code{errno} to @code{ERANGE}, if the value of @comment math.h @comment ISO @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}}. +@end deftypefun +@deftypefun float coshf (float @var{x}) +@end deftypefun +@deftypefun {long double} coshl (long double @var{x}) +These function return 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 @@ -366,36 +680,136 @@ of @var{x} is too large; that is, if overflow occurs. @comment math.h @comment ISO @deftypefun double tanh (double @var{x}) -This function returns the hyperbolic tangent of @var{x}, whose +@end deftypefun +@deftypefun float tanhf (float @var{x}) +@end deftypefun +@deftypefun {long double} tanhl (long double @var{x}) +These functions return the hyperbolic tangent of @var{x}, whose mathematical definition is @w{@code{sinh (@var{x}) / cosh (@var{x})}}. @end deftypefun +@cindex hyperbolic functions + +There are counterparts for these hyperbolic functions which work with +complex valued arguments. They should always be used instead of the +obvious mathematical formula since the implementations in the math +library are optimized for accuracy and speed. + +@comment complex.h +@comment ISO +@deftypefun {complex double} csinh (complex double @var{z}) +@end deftypefun +@deftypefun {complex float} csinhf (complex float @var{z}) +@end deftypefun +@deftypefun {complex long double} csinhl (complex long double @var{z}) +These functions return the complex hyperbolic sine of @var{z}, defined +mathematically as @w{@code{(exp (@var{z}) - exp (-@var{z})) / 2}}. The +function fails, and sets @code{errno} to @code{ERANGE}, if the value of +result is too large. +@end deftypefun + +@comment complex.h +@comment ISO +@deftypefun {complex double} ccosh (complex double @var{z}) +@end deftypefun +@deftypefun {complex float} ccoshf (complex float @var{z}) +@end deftypefun +@deftypefun {complex long double} ccoshl (complex long double @var{z}) +These functions return the complex hyperbolic cosine of @var{z}, defined +mathematically as @w{@code{(exp (@var{z}) + exp (-@var{z})) / 2}}. The +function fails, and sets @code{errno} to @code{ERANGE}, if the value of +result is too large. +@end deftypefun + +@comment complex.h +@comment ISO +@deftypefun {complex double} ctanh (complex double @var{z}) +@end deftypefun +@deftypefun {complex float} ctanhf (complex float @var{z}) +@end deftypefun +@deftypefun {complex long double} ctanhl (complex long double @var{z}) +These functions return the complex hyperbolic tangent of @var{z}, whose +mathematical definition is @w{@code{csinh (@var{z}) / ccosh (@var{z})}}. +@end deftypefun + + @cindex inverse hyperbolic functions @comment math.h -@comment BSD +@comment ISO @deftypefun double asinh (double @var{x}) -This function returns the inverse hyperbolic sine of @var{x}---the +@end deftypefun +@deftypefun float asinhf (float @var{x}) +@end deftypefun +@deftypefun {long double} asinhl (long double @var{x}) +These functions return the inverse hyperbolic sine of @var{x}---the value whose hyperbolic sine is @var{x}. @end deftypefun @comment math.h -@comment BSD +@comment ISO @deftypefun double acosh (double @var{x}) -This function returns the inverse hyperbolic cosine of @var{x}---the +@end deftypefun +@deftypefun float acoshf (float @var{x}) +@end deftypefun +@deftypefun {long double} acoshl (long double @var{x}) +These functions return 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 +@comment ISO @deftypefun double atanh (double @var{x}) -This function returns the inverse hyperbolic tangent of @var{x}---the +@end deftypefun +@deftypefun float atanhf (float @var{x}) +@end deftypefun +@deftypefun {long double} atanhl (long double @var{x}) +These functions return 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 +@cindex inverse complex hyperbolic functions + +@comment complex.h +@comment ISO +@deftypefun {complex double} casinh (complex double @var{z}) +@end deftypefun +@deftypefun {complex float} casinhf (complex float @var{z}) +@end deftypefun +@deftypefun {complex long double} casinhl (complex long double @var{z}) +These functions return the inverse complex hyperbolic sine of +@var{z}---the value whose complex hyperbolic sine is @var{z}. +@end deftypefun + +@comment complex.h +@comment ISO +@deftypefun {complex double} cacosh (complex double @var{z}) +@end deftypefun +@deftypefun {complex float} cacoshf (complex float @var{z}) +@end deftypefun +@deftypefun {complex long double} cacoshl (complex long double @var{z}) +These functions return the inverse complex hyperbolic cosine of +@var{z}---the value whose complex hyperbolic cosine is @var{z}. Unlike +the real valued function @code{acosh} there is not limit for the range +of the argument. +@end deftypefun + +@comment complex.h +@comment ISO +@deftypefun {complex double} catanh (complex double @var{z}) +@end deftypefun +@deftypefun {complex float} catanhf (complex float @var{z}) +@end deftypefun +@deftypefun {complex long double} catanhl (complex long double @var{z}) +These functions return the inverse complex hyperbolic tangent of +@var{z}---the value whose complex hyperbolic tangent is @var{z}. Unlike +the real valued function @code{atanh} there is not limit for the range +of the argument. +@end deftypefun + @node Pseudo-Random Numbers @section Pseudo-Random Numbers @cindex random numbers @@ -431,6 +845,7 @@ ones, @code{rand} and @code{srand}. @menu * ISO Random:: @code{rand} and friends. * BSD Random:: @code{random} and friends. +* SVID Random:: @code{drand48} and friends. @end menu @node ISO Random @@ -526,3 +941,346 @@ 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 SVID Random +@subsection SVID Random Number Function + +The C library on SVID systems contains yet another kind of random number +generator functions. They use a state of 48 bits of data. The user can +choose among a collection of functions which all return the random bits +in different forms. + +Generally there are two kinds of functions: those which use a state of +the random number generator which is shared among several functions and +by all threads of the process. The second group of functions require +the user to handle the state. + +All functions have in common that they use the same congruential +formula with the same constants. The formula is + +@smallexample +Y = (a * X + c) mod m +@end smallexample + +@noindent +where @var{X} is the state of the generator at the beginning and +@var{Y} the state at the end. @code{a} and @code{c} are constants +determining the way the generator work. By default they are + +@smallexample +a = 0x5DEECE66D = 25214903917 +c = 0xb = 11 +@end smallexample + +@noindent +but they can also be changed by the user. @code{m} is of course 2^48 +since the state consists of a 48 bit array. + + +@comment stdlib.h +@comment SVID +@deftypefun double drand48 () +This function returns a @code{double} value in the range of @code{0.0} +to @code{1.0} (exclusive). The random bits are determined by the global +state of the random number generator in the C library. + +Since the @code{double} type according to @w{IEEE 754} has a 52 bit +mantissa this means 4 bits are not initialized by the random number +generator. These are (of course) chosen to be the least significant +bits and they are initialized to @code{0}. +@end deftypefun + +@comment stdlib.h +@comment SVID +@deftypefun double erand48 (unsigned short int @var{xsubi}[3]) +This function returns a @code{double} value in the range of @code{0.0} +to @code{1.0} (exclusive), similar to @code{drand48}. The argument is +an array describing the state of the random number generator. + +This function can be called subsequently since it updates the array to +guarantee random numbers. The array should have been initialized before +using to get reproducible results. +@end deftypefun + +@comment stdlib.h +@comment SVID +@deftypefun {long int} lrand48 () +The @code{lrand48} functions return an integer value in the range of +@code{0} to @code{2^31} (exclusive). Even if the size of the @code{long +int} type can take more than 32 bits no higher numbers are returned. +The random bits are determined by the global state of the random number +generator in the C library. +@end deftypefun + +@comment stdlib.h +@comment SVID +@deftypefun {long int} nrand48 (unsigned short int @var{xsubi}[3]) +This function is similar to the @code{lrand48} function in that it +returns a number in the range of @code{0} to @code{2^31} (exclusive) but +the state of the random number generator used to produce the random bits +is determined by the array provided as the parameter to the function. + +The numbers in the array are afterwards updated so that subsequent calls +to this function yield to different results (as it is expected by a +random number generator). The array should have been initialized before +the first call to get reproducible results. +@end deftypefun + +@comment stdlib.h +@comment SVID +@deftypefun {long int} mrand48 () +The @code{mrand48} function is similar to @code{lrand48}. The only +difference is that the numbers returned are in the range @code{-2^31} to +@code{2^31} (exclusive). +@end deftypefun + +@comment stdlib.h +@comment SVID +@deftypefun {long int} jrand48 (unsigned short int @var{xsubi}[3]) +The @code{jrand48} function is similar to @code{nrand48}. The only +difference is that the numbers returned are in the range @code{-2^31} to +@code{2^31} (exclusive). For the @code{xsubi} parameter the same +requirements are necessary. +@end deftypefun + +The internal state of the random number generator can be initialized in +several ways. The functions differ in the completeness of the +information provided. + +@comment stdlib.h +@comment SVID +@deftypefun void srand48 (long int @var{seedval})) +The @code{srand48} function sets the most significant 32 bits of the +state internal state of the random number generator to the least +significant 32 bits of the @var{seedval} parameter. The lower 16 bts +are initilialized to the value @code{0x330E}. Even if the @code{long +int} type contains more the 32 bits only the lower 32 bits are used. + +Due to this limitation the initialization of the state using this +function of not very useful. But it makes it easy to use a constrcut +like @code{srand48 (time (0))}. + +A side-effect of this function is that the values @code{a} and @code{c} +from the internal state, which are used in the congruential formula, +are reset to the default values given above. This is of importance once +the user called the @code{lcong48} function (see below). +@end deftypefun + +@comment stdlib.h +@comment SVID +@deftypefun {unsigned short int *} seed48 (unsigned short int @var{seed16v}[3]) +The @code{seed48} function initializes all 48 bits of the state of the +internal random number generator from the content of the parameter +@var{seed16v}. Here the lower 16 bits of the first element of +@var{see16v} initialize the least significant 16 bits of the internal +state, the lower 16 bits of @code{@var{seed16v}[1]} initialize the mid-order +16 bits of the state and the 16 lower bits of @code{@var{seed16v}[2]} +initialize the most significant 16 bits of the state. + +Unlike @code{srand48} this function lets the user initialize all 48 bits +of the state. + +The value returned by @code{seed48} is a pointer to an array containing +the values of the internal state before the change. This might be +useful to restart the random number generator at a certain state. +Otherwise, the value can simply be ignored. + +As for @code{srand48}, the values @code{a} and @code{c} from the +congruential formula are reset to the default values. +@end deftypefun + +There is one more function to initialize the random number generator +which allows to specify even more information by allowing to change the +parameters in the congruential formula. + +@comment stdlib.h +@comment SVID +@deftypefun void lcong48 (unsigned short int @var{param}[7]) +The @code{lcong48} function allows the user to change the complete state +of the random number generator. Unlike @code{srand48} and +@code{seed48}, this function also changes the constants in the +congruential formula. + +From the seven elements in the array @var{param} the least significant +16 bits of the entries @code{@var{param}[0]} to @code{@var{param}[2]} +determine the the initial state, the least 16 bits of +@code{@var{param}[3]} to @code{@var{param}[5]} determine the 48 bit +constant @code{a} and @code{@var{param}[6]} determines the 16 bit value +@code{c}. +@end deftypefun + +All the above functions have in common that they use the global +parameters for the congruential formula. In multi-threaded programs it +might sometimes be useful to have different parameters in different +threads. For this reason all the above functions have a counterpart +which works on a description of the random number generator in the +user-supplied buffer instead of the global state. + +Please note that it is no problem if several threads use the global +state if all threads use the functions which take a pointer to an array +containing the state. The random numbers are computed following the +same loop but if the state in the array is different all threads will +get an individuual random number generator. + +The user supplied buffer must be of type @code{struct drand48_data}. +This type should be regarded as opaque and no member should be used +directly. + +@comment stdlib.h +@comment GNU +@deftypefun int drand48_r (struct drand48_data *@var{buffer}, double *@var{result}) +This function is equivalent to the @code{drand48} function with the +difference it does not modify the global random number generator +parameters but instead the parameters is the buffer supplied by the +buffer through the pointer @var{buffer}. The random number is return in +the variable pointed to by @var{result}. + +The return value of the function indicate whether the call succeeded. +If the value is less than @code{0} an error occurred and @var{errno} is +set to indicate the problem. + +This function is a GNU extension and should not be used in portable +programs. +@end deftypefun + +@comment stdlib.h +@comment GNU +@deftypefun int erand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, double *@var{result}) +The @code{erand48_r} function works like the @code{erand48} and it takes +an argument @var{buffer} which describes the random number generator. +The state of the random number genertor is taken from the @code{xsubi} +array, the parameters for the congruential formula from the global +random number generator data. The random number is return in the +variable pointed to by @var{result}. + +The return value is non-negative is the call succeeded. + +This function is a GNU extension and should not be used in portable +programs. +@end deftypefun + +@comment stdlib.h +@comment GNU +@deftypefun int lrand48_r (struct drand48_data *@var{buffer}, double *@var{result}) +This function is similar to @code{lrand48} and it takes a pointer to a +buffer describing the state of the random number generator as a +parameter just like @code{drand48}. + +If the return value of the function is non-negative the variable pointed +to by @var{result} contains the result. Otherwise an error occurred. + +This function is a GNU extension and should not be used in portable +programs. +@end deftypefun + +@comment stdlib.h +@comment GNU +@deftypefun int nrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result}) +The @code{nrand48_r} function works like @code{nrand48} in that it +produces a random number in range @code{0} to @code{2^31}. But instead +of using the global parameters for the congruential formula it uses the +information from the buffer pointed to by @var{buffer}. The state is +described by the values in @var{xsubi}. + +If the return value is non-negative the variable pointed to by +@var{result} contains the result. + +This function is a GNU extension and should not be used in portable +programs. +@end deftypefun + +@comment stdlib.h +@comment GNU +@deftypefun int mrand48_r (struct drand48_data *@var{buffer}, double *@var{result}) +This function is similar to @code{mrand48} but as the other reentrant +function it uses the random number generator described by the value in +the buffer pointed to by @var{buffer}. + +If the return value is non-negative the variable pointed to by +@var{result} contains the result. + +This function is a GNU extension and should not be used in portable +programs. +@end deftypefun + +@comment stdlib.h +@comment GNU +@deftypefun int jrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result}) +The @code{jrand48_r} function is similar to @code{jrand48}. But as the +other reentrant functions of this function family it uses the +congruential formula parameters from the buffer pointed to by +@var{buffer}. + +If the return value is non-negative the variable pointed to by +@var{result} contains the result. + +This function is a GNU extension and should not be used in portable +programs. +@end deftypefun + +Before any of the above functions should be used the buffer of type +@code{struct drand48_data} should initialized. The easiest way is to +fill the whole buffer with null bytes, e.g., using + +@smallexample +memset (buffer, '\0', sizeof (struct drand48_data)); +@end smallexample + +@noindent +Using any of the reetrant functions of this family now will +automatically initialize the random number generator to the default +values for the state and the parameters of the congruential formula. + +The other possibility is too use any of the functions which explicitely +initialize the buffer. Though it might be obvious how to initialize the +buffer from the data given as parameter from the function it is highly +recommended to use these functions since the result might not always be +what you expect. + +@comment stdlib.h +@comment GNU +@deftypefun int srand48_r (long int @var{seedval}, struct drand48_data *@var{buffer}) +The description of the random number generator represented by the +information in @var{buffer} is initialized similar to what the function +@code{srand48} does. The state is initialized from the paramter +@var{seedval} and the paameters for the congruential formula are +initialized to the default values. + +If the return value is non-negative the function call succeeded. + +This function is a GNU extension and should not be used in portable +programs. +@end deftypefun + +@comment stdlib.h +@comment GNU +@deftypefun int seed48_r (unsigned short int @var{seed16v}[3], struct drand48_data *@var{buffer}) +This function is similar to @code{srand48_r} but like @code{seed48} it +initializes all 48 bits of the state from the parameter @var{seed16v}. + +If the return value is non-negative the function call succeeded. It +does not return a pointer to the previous state of the random number +generator like the @code{seed48} function does. if the user wants to +preserve the state for a later rerun s/he can copy the whole buffer +pointed to by @var{buffer}. + +This function is a GNU extension and should not be used in portable +programs. +@end deftypefun + +@comment stdlib.h +@comment GNU +@deftypefun int lcong48_r (unsigned short int @var{param}[7], struct drand48_data *@var{buffer}) +This function initializes all aspects of the random number generator +described in @var{buffer} by the data in @var{param}. Here it is +especially true the function does more than just copying the contents of +@var{param} of @var{buffer}. Some more actions are required and +therefore it is important to use this function and not initialized the +random number generator directly. + +If the return value is non-negative the function call succeeded. + +This function is a GNU extension and should not be used in portable +programs. +@end deftypefun diff --git a/manual/string.texi b/manual/string.texi index 9d242b7c19..8f09ac9728 100644 --- a/manual/string.texi +++ b/manual/string.texi @@ -32,9 +32,10 @@ too. * Search Functions:: Searching for a specific element or substring. * Finding Tokens in a String:: Splitting a string into tokens by looking for delimiters. +* Encode Binary Data:: Encoding and Decoding of Binary Data. @end menu -@node Representation of Strings, String/Array Conventions, , String and Array Utilities +@node Representation of Strings @section Representation of Strings @cindex string, representation of @@ -99,7 +100,7 @@ checks for overflowing the array. Many of the library functions an extra byte to hold the null character that marks the end of the string. -@node String/Array Conventions, String Length, Representation of Strings, String and Array Utilities +@node String/Array Conventions @section String and Array Conventions This chapter describes both functions that work on arbitrary arrays or @@ -132,7 +133,7 @@ other hand, when you are manipulating null-terminated strings it is usually more convenient to use the @samp{str} functions, unless you already know the length of the string in advance. -@node String Length, Copying and Concatenation, String/Array Conventions, String and Array Utilities +@node String Length @section String Length You can get the length of a string using the @code{strlen} function. @@ -166,7 +167,7 @@ strlen (string) @end smallexample @end deftypefun -@node Copying and Concatenation, String/Array Comparison, String Length, String and Array Utilities +@node Copying and Concatenation @section Copying and Concatenation You can use the functions described in this section to copy the contents @@ -470,7 +471,7 @@ BSD. Note that it is not as general as @code{memset}, because the only value it can store is zero. @end deftypefun -@node String/Array Comparison, Collation Functions, Copying and Concatenation, String and Array Utilities +@node String/Array Comparison @section String/Array Comparison @cindex comparing strings and arrays @cindex string comparison functions @@ -613,7 +614,7 @@ strncmp ("hello, world", "hello, stupid world!!!", 5) This is an obsolete alias for @code{memcmp}, derived from BSD. @end deftypefun -@node Collation Functions, Search Functions, String/Array Comparison, String and Array Utilities +@node Collation Functions @section Collation Functions @cindex collating strings @@ -792,9 +793,9 @@ sort_strings_fast (char **array, int nstrings) @end smallexample @strong{Compatibility Note:} The string collation functions are a new -feature of @w{ISO C}. Older C dialects have no equivalent feature. +feature of @w{ISO C 89}. Older C dialects have no equivalent feature. -@node Search Functions, Finding Tokens in a String, Collation Functions, String and Array Utilities +@node Search Functions @section Search Functions This section describes library functions which perform various kinds @@ -940,7 +941,7 @@ strpbrk ("hello, world", " \t\n,.;!?") @c @end group @end deftypefun -@node Finding Tokens in a String, , Search Functions, String and Array Utilities +@node Finding Tokens in a String @section Finding Tokens in a String @cindex tokenizing strings @@ -1087,3 +1088,65 @@ token = strsep (&running, delimiters); /* token => "and" */ token = strsep (&running, delimiters); /* token => "punctuation" */ token = strsep (&running, delimiters); /* token => NULL */ @end smallexample + +@node Encode Binary Data +@section Encode Binary Data + +To store or transfer binary data in environments which only support text +one has to encode the binary data by mapping the input bytes to +characters in the range allowed for storing or transfering. SVID +systems (and nowadays XPG compliant systems) have such a function in the +C library. + +@comment stdlib.h +@comment XPG +@deftypefun {char *} l64a (long int @var{n}) +This function encodes an input value with 32 bits using characters from +the basic character set. Groups of 6 bits are encoded using the +following table: + +@multitable {xxxxx} {xxx} {xxx} {xxx} {xxx} {xxx} {xxx} {xxx} {xxx} +@item @tab 0 @tab 1 @tab 2 @tab 3 @tab 4 @tab 5 @tab 6 @tab 7 +@item 0 @tab @code{.} @tab @code{/} @tab @code{0} @tab @code{1} + @tab @code{2} @tab @code{3} @tab @code{4} @tab @code{5} +@item 8 @tab @code{6} @tab @code{7} @tab @code{8} @tab @code{9} + @tab @code{A} @tab @code{B} @tab @code{C} @tab @code{D} +@item 16 @tab @code{E} @tab @code{F} @tab @code{G} @tab @code{H} + @tab @code{I} @tab @code{J} @tab @code{K} @tab @code{L} +@item 24 @tab @code{M} @tab @code{N} @tab @code{O} @tab @code{P} + @tab @code{Q} @tab @code{R} @tab @code{S} @tab @code{T} +@item 32 @tab @code{U} @tab @code{V} @tab @code{W} @tab @code{X} + @tab @code{Y} @tab @code{Z} @tab @code{a} @tab @code{b} +@item 40 @tab @code{c} @tab @code{d} @tab @code{e} @tab @code{f} + @tab @code{g} @tab @code{h} @tab @code{i} @tab @code{j} +@item 48 @tab @code{k} @tab @code{l} @tab @code{m} @tab @code{n} + @tab @code{o} @tab @code{p} @tab @code{q} @tab @code{r} +@item 56 @tab @code{s} @tab @code{t} @tab @code{u} @tab @code{v} + @tab @code{w} @tab @code{x} @tab @code{y} @tab @code{z} +@end multitable + +The function returns a pointer to a static buffer which contains the +string representing of the encoding of @var{n}. To encoded a series of +bytes the use should append the new string to the destination buffer. +@emph{Warning:} Since a static buffer is used this function should not +be used in multi-threaded programs. There is no thread-safe alternatice +to this function in the C library. +@end deftypefun + +To decode data produced with @code{l64a} the following function should be +used. + +@deftypefun {long int} a64l (const char *@var{string}) +The parameter @var{string} should contain a string which was produced by +a call to @code{l64a}. The function processes the next 6 characters and +decodes the characters it finds according to the table above. +Characters not in the conversion table are simply ignored. This is +useful for breaking the information in lines in which case the end of +line characters are simply ignored. + +The decoded number is returned at the end as a @code{long int} value. +Consecutive calls to this function are possible but the caller must make +sure the buffer pointer is update after each call to @code{a64l} since +this function does not modify the buffer pointer. Every call consumes 6 +characters. +@end deftypefun |