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 Kl\"ampfl. 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, after which an overview is presented of the available 
functions, grouped by category, and the last part contains a 
complete explanation of each function.

The following things must be taken into account when using this unit:
\begin{enumerate}
\item This unit is compiled in Object Pascal mode so all
\var{integers} are 32 bit.
\item Some overloaded functions exist for data arrays of integers and
floats. When using the address operator (\var{@}) to pass an array of 
data to such a function, make sure the address is typecasted to the 
right type, or turn on the 'typed address operator' feature. failing to
do so, will cause the compiler not be able to decide which function you 
want to call.
\end{enumerate}

\section{Constants and types}

The following types are defined in the \file{math} unit:
\begin{verbatim}
Type
  Float = Extended;
  PFloat = ^FLoat
\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. The pointer type is used in functions that accept
an array of values of arbitrary length.
\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{Function list by category}
What follows is a listing of the available functions, grouped by category.
For each function there is a reference to the page where you can find the
function.
\subsection{Min/max determination}
Functions to determine the minimum or maximum of numbers:
\begin{funclist}
\funcref{max}{Maximum of 2 values}
\funcref{maxIntValue}{Maximum of an array of integer values}
\funcref{maxvalue}{Maximum of an array of values}
\funcref{min}{Minimum of 2 values}
\funcref{minIntValue}{Minimum of an array of integer values}
\funcref{minvalue}{Minimum of an array of values}
\end{funclist}
\subsection{Angle conversion}
\begin{funclist}
\funcref{cycletorad}{convert cycles to radians}
\funcref{degtograd}{convert degrees to grads}
\funcref{degtorad}{convert degrees to radians}
\funcref{gradtodeg}{convert grads to degrees}
\funcref{gradtorad}{convert grads to radians}
\funcref{radtocycle}{convert radians to cycles}
\funcref{radtodeg}{convert radians to degrees}
\funcref{radtograd}{convert radians to grads}
\end{funclist}
\subsection{Trigoniometric functions}
\begin{funclist}
\funcref{arccos}{calculate reverse cosine}
\funcref{arcsin}{calculate reverse sine}
\funcref{arctan2}{calculate reverse tangent}
\funcref{cotan}{calculate cotangent}
\procref{sincos}{calculate sine and cosine}
\funcref{tan}{calculate tangent}
\end{funclist}
\subsection{Hyperbolic functions}
\begin{funclist}
\funcref{arcosh}{caculate reverse hyperbolic cosine}
\funcref{arsinh}{caculate reverse hyperbolic sine}
\funcref{artanh}{caculate reverse hyperbolic tangent}
\funcref{cosh}{calculate hyperbolic cosine}
\funcref{sinh}{calculate hyperbolic sine}
\funcref{tanh}{calculate hyperbolic tangent}
\end{funclist}
\subsection{Exponential and logarithmic functions}
\begin{funclist}
\funcref{intpower}{Raise float to integer power}
\funcref{ldexp}{Calculate $2^p x$}
\funcref{lnxp1}{calculate \var{log(x+1)}}
\funcref{log10}{calculate 10-base log}
\funcref{log2}{calculate 2-base log}
\funcref{logn}{calculate N-base log}
\funcref{power}{raise float to arbitrary power}
\end{funclist}
\subsection{Number converting}
\begin{funclist}
\funcref{ceil}{Round to infinity}
\funcref{floor}{Round to minus infinity}
\procref{frexp}{Return mantissa and exponent}
\end{funclist}
\subsection{Statistical functions}
\begin{funclist}
\funcref{mean}{Mean of values}
\procref{meanandstddev}{Mean and standard deviation of values}
\procref{momentskewkurtosis}{Moments, skew and kurtosis}
\funcref{popnstddev}{Population standarddeviation }
\funcref{popnvariance}{Population variance}
\funcref{randg}{Gaussian distributed randum value}
\funcref{stddev}{Standard deviation}
\funcref{sum}{Sum of values}
\funcref{sumofsquares}{Sum of squared values}
\procref{sumsandsquares}{Sum of values and squared values}
\funcref{totalvariance}{Total variance of values}
\funcref{variance}{variance of values}
\end{funclist}
\subsection{Geometrical functions}
\begin{funclist}
\funcref{hypot}{Hypotenuse of triangle}
\funcref{norm}{Euclidian norm}
\end{funclist}

\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 : float; var exponent : integer);
\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.
Stddev is zero if there is only one value.

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;
Function popnstddev(const data : PFloat; Const N : Integer) : float;
\Description
\var{Popnstddev} returns the square root of the population variance of
the values in the  \var{Data} array. It returns zero if there is only one value.

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

\FPCexample{ex35}


\begin{function}{popnvariance}
\Declaration
Function popnvariance(const data : array of float) : float;
Function popnvariance(const data : PFloat; Const N : Integer) : float;
\Description
\var{Popnvariance} returns the square root of the population variance of
the values in the  \var{Data} array. It returns zero if there is only one value.

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

\FPCexample{ex36}


\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{ex34}


\begin{function}{radtocycle}
\Declaration
Function radtocycle(rad : float) : float;
\Description
\var{Radtocycle} converts its argument \var{rad} (an angle expressed in
radians) to an angle in cycles.

(1 cycle equals 2 pi radians)
\Errors
None.
\SeeAlso
\seef{degtograd}, \seef{degtorad}, \seef{radtodeg},
\seef{radtograd}, \seef{cycletorad}
\end{function}

\FPCexample{ex37}


\begin{function}{radtodeg}
\Declaration
Function radtodeg(rad : float) : float;
\Description
\var{Radtodeg} converts its argument \var{rad} (an angle expressed in
radians) to an angle in degrees.

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

\FPCexample{ex38}


\begin{function}{radtograd}
\Declaration
Function radtograd(rad : float) : float;
\Description
\var{Radtodeg} converts its argument \var{rad} (an angle expressed in
radians) to an angle in grads.

(200 grads equals pi radians)
\Errors
None.
\SeeAlso
\seef{degtograd}, \seef{degtorad}, \seef{radtocycle},
\seef{radtodeg}, \seef{cycletorad}
\end{function}

\FPCexample{ex39}


\begin{function}{randg}
\Declaration
Function randg(mean,stddev : float) : float;
\Description
\var{randg} returns a random number which - when produced in large
quantities - has a Gaussian distribution with mean \var{mean} and 
standarddeviation \var{stddev}. 
\Errors
None.
\SeeAlso
\seef{mean}, \seef{stddev}, \seep{meanandstddev}
\end{function}

\FPCexample{ex40}


\begin{procedure}{sincos}
\Declaration
Procedure sincos(theta : float;var sinus,cosinus : float);
\Description
\var{Sincos} calculates the sine and cosine of the angle \var{theta},
and returns the result in \var{sinus} and \var{cosinus}.

On Intel hardware, This calculation will be faster than making 2 calls
to clculatet he sine and cosine separately.
\Errors
None.
\SeeAlso
\seef{arcsin}, \seef{arccos}.
\end{procedure}

\FPCexample{ex41}


\begin{function}{sinh}
\Declaration
Function sinh(x : float) : float;
\Description
\var{Sinh} returns the hyperbolic sine of its argument \var{x}.
\Errors
\SeeAlso
\seef{cosh}, \seef{arsinh}, \seef{tanh}, \seef{artanh}
\end{function}

\FPCexample{ex42}


\begin{function}{stddev}
\Declaration
Function stddev(const data : array of float) : float;
Function stddev(const data : PFloat; Const N : Integer) : float;
\Description
\var{Stddev} returns the standard deviation of the values in \var{Data}.
It returns zero if there is only one value.

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

\FPCexample{ex43}


\begin{function}{sum}
\Declaration
Function sum(const data : array of float) : float;
Function sum(const data : PFloat; Const N : Integer) : float;
\Description
\var{Sum} returns the sum of the values in the \var{data} array.

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

\FPCexample{ex44}


\begin{function}{sumofsquares}
\Declaration
Function sumofsquares(const data : array of float) : float;
Function sumofsquares(const data : PFloat; Const N : Integer) : float;
\Description
\var{Sumofsquares} returns the sum of the squares of the values in the \var{data} 
array.

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

\FPCexample{ex45}


\begin{procedure}{sumsandsquares}
\Declaration
Procedure sumsandsquares(const data : array of float;
  var sum,sumofsquares : float);
Procedure sumsandsquares(const data : PFloat; Const N : Integer;
  var sum,sumofsquares : float);
\Description
\var{sumsandsquares} calculates the sum of the values and the sum of 
the squares of the values in the \var{data} array and returns the
results in \var{sum} and \var{sumofsquares}.

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

\FPCexample{ex46}


\begin{function}{tan}
\Declaration
Function tan(x : float) : float;
\Description
\var{Tan} returns the tangent of \var{x}.
\Errors
If \var{x} (normalized) is pi/2 or 3pi/2 then an overflow will occur.
\SeeAlso
\seef{tanh}, \seef{arcsin}, \seep{sincos}, \seef{arccos}
\end{function}

\FPCexample{ex47}


\begin{function}{tanh}
\Declaration
Function tanh(x : float) : float;
\Description
\var{Tanh} returns the hyperbolic tangent of \var{x}.
\Errors
None.
\SeeAlso
\seef{arcsin}, \seep{sincos}, \seef{arccos}
\end{function}

\FPCexample{ex48}


\begin{function}{totalvariance}
\Declaration
Function totalvariance(const data : array of float) : float;
Function totalvariance(const data : PFloat; Const N : Integer) : float;
\Description
\var{TotalVariance} returns the total variance of the values in the 
\var{data} array. It returns zero if there is only one value.

The second form of the function accepts a pointer to an array of \var{N}
values.
\Errors
None.
\SeeAlso
\seef{variance}, \seef{stddev}, \seef{mean}
\end{function}

\FPCexample{ex49}


\begin{function}{variance}
\Declaration
Function variance(const data : array of float) : float;
Function variance(const data : PFloat; Const N : Integer) : float;
\Description
\var{Variance} returns the variance of the values in the 
\var{data} array. It returns zero if there is only one value.

The second form of the function accepts a pointer to an array of \var{N}
values.
\Errors
None.
\SeeAlso
\seef{totalvariance}, \seef{stddev}, \seef{mean}
\end{function}

\FPCexample{ex50}