fpc/docs/math.tex

%
%   $Id$
%   This file is part of the FPC documentation.
%   Copyright (C) 2000 by Florian Klaempfl
%
%   The FPC documentation is free text; you can redistribute it and/or
%   modify it under the terms of the GNU Library General Public License as
%   published by the Free Software Foundation; either version 2 of the
%   License, or (at your option) any later version.
%
%   The FPC Documentation is distributed in the hope that it will be useful,
%   but WITHOUT ANY WARRANTY; without even the implied warranty of
%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
%   Library General Public License for more details.
%
%   You should have received a copy of the GNU Library General Public
%   License along with the FPC documentation; see the file COPYING.LIB.  If not,
%   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
%   Boston, MA 02111-1307, USA.
%
\chapter{The MATH unit}
\FPCexampledir{mathex}

This chapter describes the \file{math} unit. The \var{math} unit
was initially written by Florian Klaempfl. It provides mathematical
functions which aren't covered by the system unit.

This chapter starts out with a definition of all types and constants
that are defined, followed by a complete explanation of each function.
{\em Remark} This unit is compiled in Object Pascal mode so all
\var{integers} are 32 bit.

\section{Constants and types}

The following types are defined in the \file{math} unit:
\begin{verbatim}
Type
   Float = Extended;
\end{verbatim}
All calculations are done with the Float type. This allows to
recompile the unit with a different float type to obtain a
desired precision.
\begin{verbatim}
Type
   TPaymentTime = (PTEndOfPeriod,PTStartOfPeriod);
\end{verbatim}
\var{TPaymentTime} is used in the financial calculations.
\begin{verbatim}
Type
   EInvalidArgument = Class(EMathError);
\end{verbatim}
The \var{EInvalidArgument} exception is used to report invalid arguments.
\section{Functions and Procedures}

\begin{function}{arccos}
\Declaration
Function arccos(x : float) : float;
\Description
\var{Arccos} returns the inverse cosine of its argument \var{x}. The
argument \var{x} should lie between -1 and 1 (borders included). 
\Errors
If the argument \var{x} is not in the allowed range, an
\var{EInvalidArgument} exception is raised.
\SeeAlso
\seef{arcsin}, \seef{arcosh}, \seef{arsinh}, \seef{artanh}
\end{function}

\FPCexample{ex1}

\begin{function}{arcosh}
\Declaration
Function arcosh(x : float) : float;
Function arccosh(x : float) : float;
\Description
\var{Arcosh} returns the inverse hyperbolic cosine of its argument \var{x}. 
The argument \var{x} should be larger than 1. 

The \var{arccosh} variant of this function is supplied for \delphi 
compatibility.
\Errors
If the argument \var{x} is not in the allowed range, an \var{EInvalidArgument}
exception is raised.
\SeeAlso
\seef{cosh}, \seef{sinh}, \seef{arcsin}, \seef{arsinh}, \seef{artanh},
\seef{tanh}
\end{function}

\FPCexample{ex3}

\begin{function}{arcsin}
\Declaration
Function arcsin(x : float) : float;
\Description
\var{Arcsin} returns the inverse sine of its argument \var{x}. The
argument \var{x} should lie between -1 and 1. 
\Errors
If the argument \var{x} is not in the allowed range, an \var{EInvalidArgument}
exception is raised.
\SeeAlso
\seef{arccos}, \seef{arcosh}, \seef{arsinh}, \seef{artanh}
\end{function}

\FPCexample{ex2}


\begin{function}{arctan2}
\Declaration
Function arctan2(x,y : float) : float;
\Description
\var{arctan2} calculates \var{arctan(y/x)}, and returns an angle in the
correct quadrant. The returned angle will be in the range $-\pi$ to
$\pi$ radians.
The values of \var{x} and \var{y} must be between -2\^{}64 and 2\^{}64,
moreover \var{x} should be different from zero.

On Intel systems this function is implemented with the native intel
\var{fpatan} instruction.
\Errors
If \var{x} is zero, an overflow error will occur.
\SeeAlso
\seef{arccos}, \seef{arcosh}, \seef{arsinh}, \seef{artanh}
\end{function}

\FPCexample{ex6}

\begin{function}{arsinh}
\Declaration
Function arsinh(x : float) : float;
Function arcsinh(x : float) : float;
\Description
\var{arsinh} returns the inverse hyperbolic sine of its argument \var{x}. 

The \var{arscsinh} variant of this function is supplied for \delphi 
compatibility.
\Errors
None.
\SeeAlso
\seef{arcosh}, \seef{arccos}, \seef{arcsin}, \seef{artanh}
\end{function}

\FPCexample{ex4}


\begin{function}{artanh}
\Declaration
Function artanh(x : float) : float;
Function arctanh(x : float) : float;
\Description
\var{artanh} returns the inverse hyperbolic tangent of its argument \var{x},
where \var{x} should lie in the interval [-1,1], borders included.

The \var{arctanh} variant of this function is supplied for \delphi compatibility.
\Errors
In case \var{x} is not in the interval [-1,1], an \var{EInvalidArgument}
exception is raised.
\SeeAlso
\seef{arcosh}, \seef{arccos}, \seef{arcsin}, \seef{artanh}
\Errors
\SeeAlso
\end{function}

\FPCexample{ex5}


\begin{function}{ceil}
\Declaration
Function ceil(x : float) : longint;
\Description
\var{Ceil} returns the lowest integer number greater than or equal to \var{x}.
The absolute value of \var{x} should be less than \var{maxint}.
\Errors
If the asolute value of \var{x} is larger than maxint, an overflow error will
occur.
\SeeAlso
\seef{floor}
\end{function}

\FPCexample{ex7}

\begin{function}{cosh}
\Declaration
Function cosh(x : float) : float;
\Description
\var{Cosh} returns the hyperbolic cosine of it's argument {x}.
\Errors
None.
\SeeAlso
\seef{arcosh}, \seef{sinh}, \seef{arsinh}
\end{function}

\FPCexample{ex8}


\begin{function}{cotan}
\Declaration
Function cotan(x : float) : float;
\Description
\var{Cotan} returns the cotangent of it's argument \var{x}. \var{x} should
be different from zero.
\Errors
If \var{x} is zero then a overflow error will occur.
\SeeAlso
\seef{tanh}
\end{function}

\FPCexample{ex9}


\begin{function}{cycletorad}
\Declaration
Function cycletorad(cycle : float) : float;
\Description
\var{Cycletorad} transforms it's argument \var{cycle}
(an angle expressed in cycles) to radians.
(1 cycle is $2 \pi$ radians).
\Errors
None.
\SeeAlso
\seef{degtograd}, \seef{degtorad}, \seef{radtodeg},
\seef{radtograd}, \seef{radtocycle}
\end{function}

\FPCexample{ex10}


\begin{function}{degtograd}
\Declaration
Function degtograd(deg : float) : float;
\Description
\var{Degtograd} transforms it's argument \var{deg} (an angle in degrees)
to grads.

(90 degrees is 100 grad.)
\Errors
None.
\SeeAlso
\seef{cycletorad}, \seef{degtorad}, \seef{radtodeg},
\seef{radtograd}, \seef{radtocycle}
\end{function}

\FPCexample{ex11}


\begin{function}{degtorad}
\Declaration
Function degtorad(deg : float) : float;
\Description
\var{Degtorad} converts it's argument \var{deg} (an angle in degrees) to
radians.

(pi radians is 180 degrees)
\Errors
None.
\SeeAlso
\seef{cycletorad}, \seef{degtograd}, \seef{radtodeg},
\seef{radtograd}, \seef{radtocycle}
\end{function}

\FPCexample{ex12}


\begin{function}{floor}
\Declaration
Function floor(x : float) : longint;
\Description
\var{Floor} returns the largest integer smaller than or equal to \var{x}.
The absolute value of \var{x} should be less than \var{maxint}.
\Errors
If \var{x} is larger than \var{maxint}, an overflow will occur.
\SeeAlso
\seef{ceil}
\end{function}

\FPCexample{ex13}


\begin{procedure}{frexp}
\Declaration
Procedure frexp(x : float;var mantissa,exponent : float);
\Description
\var{Frexp} returns the mantissa and exponent of it's argument
\var{x} in \var{mantissa} and \var{exponent}.
\Errors
None
\SeeAlso
\end{procedure}

\FPCexample{ex14}


\begin{function}{gradtodeg}
\Declaration
Function gradtodeg(grad : float) : float;
\Description
\var{Gradtodeg} converts its argument \var{grad} (an angle in grads)
to degrees.

(100 grad is 90 degrees)
\Errors
None.
\SeeAlso
\seef{cycletorad}, \seef{degtograd}, \seef{radtodeg},
\seef{radtograd}, \seef{radtocycle}, \seef{gradtorad}
\end{function}

\FPCexample{ex15}


\begin{function}{gradtorad}
\Declaration
Function gradtorad(grad : float) : float;
\Description
\var{Gradtorad} converts its argument \var{grad} (an angle in grads)
to radians.

(200 grad is pi degrees).
\Errors
None.
\SeeAlso
\seef{cycletorad}, \seef{degtograd}, \seef{radtodeg},
\seef{radtograd}, \seef{radtocycle}, \seef{gradtodeg}
\end{function}

\FPCexample{ex16}


\begin{function}{hypot}
\Declaration
Function hypot(x,y : float) : float;
\Description
\var{Hypot} returns the hypotenuse of the triangle where the sides
adjacent to the square angle have lengths \var{x} and \var{y}.

The function uses Pythagoras' rule for this.
\Errors
None.
\SeeAlso
\end{function}

\FPCexample{ex17}


\begin{function}{intpower}
\Declaration
Function intpower(base : float;exponent : longint) : float;
\Description
\var{Intpower} returns \var{base} to the power \var{exponent},
where exponent is an integer value.
\Errors
If \var{base} is zero and the exponent is negative, then an
overflow error will occur.
\SeeAlso
\seef{power}
\end{function}

\FPCexample{ex18}


\begin{function}{ldexp}
\Declaration
Function ldexp(x : float;p : longint) : float;
\Description
\var{Ldexp} returns $2^p x$.
\Errors
None.
\SeeAlso
\seef{lnxp1}, \seef{log10},\seef{log2},\seef{logn}
\end{function}

\FPCexample{ex19}


\begin{function}{lnxp1}
\Declaration
Function lnxp1(x : float) : float;
\Description
\var{Lnxp1} returns the natural logarithm of \var{1+X}. The result
is more precise for small values of \var{x}. \var{x} should be larger
than -1.
\Errors
If $x\leq -1$ then an \var{EInvalidArgument} exception will be raised.
\SeeAlso
\seef{ldexp}, \seef{log10},\seef{log2},\seef{logn}
\end{function}

\FPCexample{ex20}

\begin{function}{log10}
\Declaration
Function log10(x : float) : float;
\Description
\var{Log10} returns the 10-base logarithm of \var{X}.
\Errors
If \var{x} is less than or equal to 0 an 'invalid fpu operation' error
will occur.
\SeeAlso
\seef{ldexp}, \seef{lnxp1},\seef{log2},\seef{logn}
\end{function}

\FPCexample{ex21}


\begin{function}{log2}
\Declaration
Function log2(x : float) : float;
\Description
\var{Log2} returns the 2-base logarithm of \var{X}.
\Errors
If \var{x} is less than or equal to 0 an 'invalid fpu operation' error
will occur.
\SeeAlso
\seef{ldexp}, \seef{lnxp1},\seef{log10},\seef{logn}
\end{function}

\FPCexample{ex22}


\begin{function}{logn}
\Declaration
Function logn(n,x : float) : float;
\Description
\var{Logn} returns the n-base logarithm of \var{X}.
\Errors
If \var{x} is less than or equal to 0 an 'invalid fpu operation' error
will occur.
\SeeAlso
\seef{ldexp}, \seef{lnxp1},\seef{log10},\seef{log2}
\end{function}

\FPCexample{ex23}

\begin{function}{max}
\Declaration
Function max(Int1,Int2:Cardinal):Cardinal;
Function max(Int1,Int2:Integer):Integer;
\Description
\var{Max} returns the maximum of \var{Int1} and \var{Int2}.
\Errors
None.
\SeeAlso
\seef{min}, \seef{maxIntValue}, \seef{maxvalue}
\end{function}

\FPCexample{ex24}

\begin{function}{maxIntValue}
\Declaration
function MaxIntValue(const Data: array of Integer): Integer;
\Description
\var{MaxIntValue} returns the largest integer out of the \var{Data}
array.

This function is provided for \delphi compatibility, use the \seef{maxvalue}
function instead.
\Errors
None.
\SeeAlso
\seef{maxvalue}, \seef{minvalue}, \seef{minIntValue}
\end{function}

\FPCexample{ex25}


\begin{function}{maxvalue}
\Declaration
Function maxvalue(const data : array of float) : float;
Function maxvalue(const data : array of Integer) : Integer;
Function maxvalue(const data : PFloat; Const N : Integer) : float;
Function maxvalue(const data : PInteger; Const N : Integer) : Integer;
\Description
\var{Maxvalue} returns the largest value in the \var{data} 
array with integer or float values. The return value has 
the same type as the elements of the array.

The third and fourth forms accept a pointer to an array of \var{N} 
integer or float values.
\Errors
None.
\SeeAlso
\seef{maxIntValue}, \seef{minvalue}, \seef{minIntValue}
\end{function}

\FPCexample{ex26}

\begin{function}{mean}
\Declaration
Function mean(const data : array of float) : float;
Function mean(const data : PFloat; Const N : longint) : float;
\Description
\var{Mean} returns the average value of \var{data}.

The second form accepts a pointer to an array of \var{N} values.
\Errors
None.
\SeeAlso
\seep{meanandstddev}, \seep{momentskewkurtosis}, \seef{sum}
\end{function}

\FPCexample{ex27}

\begin{procedure}{meanandstddev}
\Declaration
Procedure meanandstddev(const data : array of float; 
                        var mean,stddev : float);
procedure meanandstddev(const data : PFloat;
  Const N : Longint;var mean,stddev : float);
\Description
\var{meanandstddev} calculates the mean and standard deviation of \var{data}
and returns the result in \var{mean} and \var{stddev}, respectively.

The second form accepts a pointer to an array of \var{N} values.
\Errors
None.
\SeeAlso
\seef{mean},\seef{sum}, \seef{sumofsquares}, \seep{momentskewkurtosis}
\end{procedure}

\FPCexample{ex28}


\begin{function}{min}
\Declaration
Function min(Int1,Int2:Cardinal):Cardinal;
Function min(Int1,Int2:Integer):Integer;
\Description
\var{min} returns the smallest value of \var{Int1} and \var{Int2};
\Errors
None.
\SeeAlso
\seef{max}
\end{function}

\FPCexample{ex29}

\begin{function}{minIntValue}
\Declaration
Function minIntValue(const Data: array of Integer): Integer;
\Description
\var{MinIntvalue} returns the smallest value in the \var{Data} array.

This function is provided for \delphi compatibility, use \var{minvalue}
instead.
\Errors
None
\SeeAlso
\seef{minvalue}, \seef{maxIntValue}, \seef{maxvalue}
\end{function}

\FPCexample{ex30}


\begin{function}{minvalue}
\Declaration
Function minvalue(const data : array of float) : float;
Function minvalue(const data : array of Integer) : Integer;
Function minvalue(const data : PFloat; Const N : Integer) : float;
Function minvalue(const data : PInteger; Const N : Integer) : Integer;
\Description
\var{Minvalue} returns the smallest value in the \var{data} 
array with integer or float values. The return value has 
the same type as the elements of the array.

The third and fourth forms accept a pointer to an array of \var{N} 
integer or float values.
\Errors
None.
\SeeAlso
\seef{maxIntValue}, \seef{maxvalue}, \seef{minIntValue}
\end{function}

\FPCexample{ex31}


\begin{procedure}{momentskewkurtosis}
\Declaration
procedure momentskewkurtosis(const data : array of float;
  var m1,m2,m3,m4,skew,kurtosis : float);
procedure momentskewkurtosis(const data : PFloat; Const N : Integer;
  var m1,m2,m3,m4,skew,kurtosis : float);
\Description
\var{momentskewkurtosis} calculates the 4 first moments of the distribution
of valuesin \var{data} and returns them in \var{m1},\var{m2},\var{m3} and
\var{m4}, as well as the \var{skew} and \var{kurtosis}.
\Errors
None.
\SeeAlso
\seef{mean}, \seep{meanandstddev}
\end{procedure}

\FPCexample{ex32}

\begin{function}{norm}
\Declaration
Function norm(const data : array of float) : float;
Function norm(const data : PFloat; Const N : Integer) : float;
\Description
\var{Norm} calculates the Euclidian norm of the array of data.
This equals \var{sqrt(sumofsquares(data))}.

The second form accepts a pointer to an array of \var{N} values.
\Errors
None.
\SeeAlso
\seef{sumofsquares}
\end{function}

\FPCexample{ex33}


\begin{function}{popnstddev}
\Declaration
Function popnstddev(const data : array of float) : float;
\Description

\Errors
\SeeAlso
\end{function}

\FPCexample{}


\begin{function}{popnvariance}
\Declaration
Function popnvariance(const data : array of float) : float;
\Description

\Errors
\SeeAlso
\end{function}

\FPCexample{}


\begin{function}{power}
\Declaration
Function power(base,exponent : float) : float;
\Description
\var{power} raises \var{base} to the power \var{power}. This is equivalent
to \var{exp(power*ln(base))}. Therefore \var{base} should be non-negative.
\Errors
None.
\SeeAlso
\seef{intpower}
\end{function}

\FPCexample{}


\begin{function}{radtocycle}
\Declaration
Function radtocycle(rad : float) : float;
\Description

\Errors
\SeeAlso
\end{function}

\FPCexample{}


\begin{function}{radtodeg}
\Declaration
Function radtodeg(rad : float) : float;
\Description

\Errors
\SeeAlso
\end{function}

\FPCexample{}


\begin{function}{radtograd}
\Declaration
Function radtograd(rad : float) : float;
\Description

\Errors
\SeeAlso
\end{function}

\FPCexample{}


\begin{function}{randg}
\Declaration
Function randg(mean,stddev : float) : float;
\Description

\Errors
\SeeAlso
\end{function}

\FPCexample{}


\begin{procedure}{sincos}
\Declaration
Procedure sincos(theta : float;var sinus,cosinus : float);
\Description

\Errors
\SeeAlso
\end{procedure}

\FPCexample{}


\begin{function}{sinh}
\Declaration
Function sinh(x : float) : float;
\Description

\Errors
\SeeAlso
\end{function}

\FPCexample{}


\begin{function}{stddev}
\Declaration
Function stddev(const data : array of float) : float;
\Description

\Errors
\SeeAlso
\end{function}

\FPCexample{}


\begin{function}{sum}
\Declaration
Function sum(const data : array of float) : float;
\Description

\Errors
\SeeAlso
\end{function}

\FPCexample{}


  var sum,sumofsquares : float);
\begin{function}{sumofsquares}
\Declaration
Function sumofsquares(const data : array of float) : float;
\Description

\Errors
\SeeAlso
\end{function}

\FPCexample{}


\begin{procedure}{sumsandsquares}
\Declaration
Procedure sumsandsquares(const data : array of float;
\Description

\Errors
\SeeAlso
\end{procedure}

\FPCexample{}


\begin{function}{tan}
\Declaration
Function tan(x : float) : float;
\Description

\Errors
\SeeAlso
\end{function}

\FPCexample{}


\begin{function}{tanh}
\Declaration
Function tanh(x : float) : float;
\Description

\Errors
\SeeAlso
\end{function}

\FPCexample{}


\begin{function}{totalvariance}
\Declaration
Function totalvariance(const data : array of float) : float;
\Description

\Errors
\SeeAlso
\end{function}

\FPCexample{}


\begin{function}{variance}
\Declaration
Function variance(const data : array of float) : float;
\Description

\Errors
\SeeAlso
\end{function}

\FPCexample{}