Subsections

12. The MATH unit

mathex

This chapter describes the math unit. The 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, 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:

  1. This unit is compiled in Object Pascal mode so all integers are 32 bit.
  2. Some overloaded functions exist for data arrays of integers and floats. When using the address operator (@) 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.

12.1 Constants and types

The following types are defined in the math unit:

Type
  Float = Extended;
  PFloat = ^FLoat
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.
Type
   TPaymentTime = (PTEndOfPeriod,PTStartOfPeriod);
TPaymentTime is used in the financial calculations.
Type
   EInvalidArgument = Class(EMathError);
The EInvalidArgument exception is used to report invalid arguments.

12.2 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.

12.2.1 Min/max determination

Functions to determine the minimum or maximum of numbers: max Maximum of 2 values]
maxIntValue Maximum of an array of integer values
maxvalue Maximum of an array of values
min Minimum of 2 values
minIntValue Minimum of an array of integer values
minvalue Minimum of an array of values

12.2.2 Angle conversion

cycletorad convert cycles to radians]
degtograd convert degrees to grads
degtorad convert degrees to radians
gradtodeg convert grads to degrees
gradtorad convert grads to radians
radtocycle convert radians to cycles
radtodeg convert radians to degrees
radtograd convert radians to grads

12.2.3 Trigoniometric functions

arccos calculate reverse cosine]
arcsin calculate reverse sine
arctan2 calculate reverse tangent
cotan calculate cotangent
sincos calculate sine and cosine
tan calculate tangent

12.2.4 Hyperbolic functions

arcosh caculate reverse hyperbolic cosine]
arsinh caculate reverse hyperbolic sine
artanh caculate reverse hyperbolic tangent
cosh calculate hyperbolic cosine
sinh calculate hyperbolic sine
tanh calculate hyperbolic tangent

12.2.5 Exponential and logarithmic functions

intpower Raise float to integer power]
ldexp Calculate 6#6
lnxp1 calculate log(x+1)
log10 calculate 10-base log
log2 calculate 2-base log
logn calculate N-base log
power raise float to arbitrary power

12.2.6 Number converting

ceil Round to infinity]
floor Round to minus infinity
frexp Return mantissa and exponent

12.2.7 Statistical functions

mean Mean of values]
meanandstddev Mean and standard deviation of values
momentskewkurtosis Moments, skew and kurtosis
popnstddev Population standarddeviation
popnvariance Population variance
randg Gaussian distributed randum value
stddev Standard deviation
sum Sum of values
sumofsquares Sum of squared values
sumsandsquares Sum of values and squared values
totalvariance Total variance of values
variance variance of values

12.2.8 Geometrical functions

hypot Hypotenuse of triangle]
norm Euclidian norm

12.3 Functions and Procedures


12.3.1 arccos

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

7#7


12.3.2 arcosh

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

The arccosh variant of this function is supplied for compatibility.

Errors
If the argument x is not in the allowed range, an EInvalidArgument exception is raised.
See also
cosh, sinh, arcsin, arsinh, artanh, tanh

8#8


12.3.3 arcsin

Declaration
Function arcsin(x : float) : float;
Description
Arcsin returns the inverse sine of its argument x. The argument x should lie between -1 and 1.
Errors
If the argument x is not in the allowed range, an EInvalidArgument exception is raised.
See also
arccos, arcosh, arsinh, artanh

9#9


12.3.4 arctan2

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

On Intel systems this function is implemented with the native intel fpatan instruction.

Errors
If x is zero, an overflow error will occur.
See also
arccos, arcosh, arsinh, artanh

12#12


12.3.5 arsinh

Declaration
Function arsinh(x : float) : float; Function arcsinh(x : float) : float;
Description
arsinh returns the inverse hyperbolic sine of its argument x.

The arscsinh variant of this function is supplied for compatibility.

Errors
None.
See also
arcosh, arccos, arcsin, artanh

13#13


12.3.6 artanh

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

The arctanh variant of this function is supplied for compatibility.

Errors
In case x is not in the interval [-1,1], an EInvalidArgument exception is raised.
See also
arcosh, arccos, arcsin, artanh
Errors
See also

14#14


12.3.7 ceil

Declaration
Function ceil(x : float) : longint;
Description
Ceil returns the lowest integer number greater than or equal to x. The absolute value of x should be less than maxint.
Errors
If the asolute value of x is larger than maxint, an overflow error will occur.
See also
floor

15#15


12.3.8 cosh

Declaration
Function cosh(x : float) : float;
Description
Cosh returns the hyperbolic cosine of it's argument x.
Errors
None.
See also
arcosh, sinh, arsinh

16#16


12.3.9 cotan

Declaration
Function cotan(x : float) : float;
Description
Cotan returns the cotangent of it's argument x. x should be different from zero.
Errors
If x is zero then a overflow error will occur.
See also
tanh

17#17


12.3.10 cycletorad

Declaration
Function cycletorad(cycle : float) : float;
Description
Cycletorad transforms it's argument cycle (an angle expressed in cycles) to radians. (1 cycle is 18#18 radians).
Errors
None.
See also
degtograd, degtorad, radtodeg, radtograd, radtocycle

19#19


12.3.11 degtograd

Declaration
Function degtograd(deg : float) : float;
Description
Degtograd transforms it's argument deg (an angle in degrees) to grads.

(90 degrees is 100 grad.)

Errors
None.
See also
cycletorad, degtorad, radtodeg, radtograd, radtocycle

20#20


12.3.12 degtorad

Declaration
Function degtorad(deg : float) : float;
Description
Degtorad converts it's argument deg (an angle in degrees) to radians.

(pi radians is 180 degrees)

Errors
None.
See also
cycletorad, degtograd, radtodeg, radtograd, radtocycle

21#21


12.3.13 floor

Declaration
Function floor(x : float) : longint;
Description
Floor returns the largest integer smaller than or equal to x. The absolute value of x should be less than maxint.
Errors
If x is larger than maxint, an overflow will occur.
See also
ceil

22#22


12.3.14 frexp

Declaration
Procedure frexp(x : float;var mantissa,exponent : float);
Description
Frexp returns the mantissa and exponent of it's argument x in mantissa and exponent.
Errors
None
See also

23#23


12.3.15 gradtodeg

Declaration
Function gradtodeg(grad : float) : float;
Description
Gradtodeg converts its argument grad (an angle in grads) to degrees.

(100 grad is 90 degrees)

Errors
None.
See also
cycletorad, degtograd, radtodeg, radtograd, radtocycle, gradtorad

24#24


12.3.16 gradtorad

Declaration
Function gradtorad(grad : float) : float;
Description
Gradtorad converts its argument grad (an angle in grads) to radians.

(200 grad is pi degrees).

Errors
None.
See also
cycletorad, degtograd, radtodeg, radtograd, radtocycle, gradtodeg

25#25


12.3.17 hypot

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

The function uses Pythagoras' rule for this.

Errors
None.
See also

26#26


12.3.18 intpower

Declaration
Function intpower(base : float;exponent : longint) : float;
Description
Intpower returns base to the power exponent, where exponent is an integer value.
Errors
If base is zero and the exponent is negative, then an overflow error will occur.
See also
power

27#27


12.3.19 ldexp

Declaration
Function ldexp(x : float;p : longint) : float;
Description
Ldexp returns 6#6.
Errors
None.
See also
lnxp1, log10,log2,logn

28#28


12.3.20 lnxp1

Declaration
Function lnxp1(x : float) : float;
Description
Lnxp1 returns the natural logarithm of 1+X. The result is more precise for small values of x. x should be larger than -1.
Errors
If 29#29 then an EInvalidArgument exception will be raised.
See also
ldexp, log10,log2,logn

30#30


12.3.21 log10

Declaration
Function log10(x : float) : float;
Description
Log10 returns the 10-base logarithm of X.
Errors
If x is less than or equal to 0 an 'invalid fpu operation' error will occur.
See also
ldexp, lnxp1,log2,logn

31#31


12.3.22 log2

Declaration
Function log2(x : float) : float;
Description
Log2 returns the 2-base logarithm of X.
Errors
If x is less than or equal to 0 an 'invalid fpu operation' error will occur.
See also
ldexp, lnxp1,log10,logn

32#32


12.3.23 logn

Declaration
Function logn(n,x : float) : float;
Description
Logn returns the n-base logarithm of X.
Errors
If x is less than or equal to 0 an 'invalid fpu operation' error will occur.
See also
ldexp, lnxp1,log10,log2

33#33


12.3.24 max

Declaration
Function max(Int1,Int2:Cardinal):Cardinal; Function max(Int1,Int2:Integer):Integer;
Description
Max returns the maximum of Int1 and Int2.
Errors
None.
See also
min, maxIntValue, maxvalue

34#34


12.3.25 maxIntValue

Declaration
function MaxIntValue(const Data: array of Integer): Integer;
Description
MaxIntValue returns the largest integer out of the Data array.

This function is provided for compatibility, use the maxvalue function instead.

Errors
None.
See also
maxvalue, minvalue, minIntValue

35#35


12.3.26 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
Maxvalue returns the largest value in the 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 N integer or float values.

Errors
None.
See also
maxIntValue, minvalue, minIntValue

36#36


12.3.27 mean

Declaration
Function mean(const data : array of float) : float; Function mean(const data : PFloat; Const N : longint) : float;
Description
Mean returns the average value of data.

The second form accepts a pointer to an array of N values.

Errors
None.
See also
meanandstddev, momentskewkurtosis, sum

37#37


12.3.28 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
meanandstddev calculates the mean and standard deviation of data and returns the result in mean and stddev, respectively. Stddev is zero if there is only one value.

The second form accepts a pointer to an array of N values.

Errors
None.
See also
mean,sum, sumofsquares, momentskewkurtosis

38#38


12.3.29 min

Declaration
Function min(Int1,Int2:Cardinal):Cardinal; Function min(Int1,Int2:Integer):Integer;
Description
min returns the smallest value of Int1 and Int2;
Errors
None.
See also
max

39#39


12.3.30 minIntValue

Declaration
Function minIntValue(const Data: array of Integer): Integer;
Description
MinIntvalue returns the smallest value in the Data array.

This function is provided for compatibility, use minvalue instead.

Errors
None
See also
minvalue, maxIntValue, maxvalue

40#40


12.3.31 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
Minvalue returns the smallest value in the 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 N integer or float values.

Errors
None.
See also
maxIntValue, maxvalue, minIntValue

41#41


12.3.32 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
momentskewkurtosis calculates the 4 first moments of the distribution of valuesin data and returns them in m1,m2,m3 and m4, as well as the skew and kurtosis.
Errors
None.
See also
mean, meanandstddev

42#42


12.3.33 norm

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

The second form accepts a pointer to an array of N values.

Errors
None.
See also
sumofsquares

43#43


12.3.34 popnstddev

Declaration
Function popnstddev(const data : array of float) : float; Function popnstddev(const data : PFloat; Const N : Integer) : float;
Description
Popnstddev returns the square root of the population variance of the values in the Data array. It returns zero if there is only one value.

The second form of this function accepts a pointer to an array of N values.

Errors
None.
See also
popnvariance, mean, meanandstddev, stddev, momentskewkurtosis

44#44


12.3.35 popnvariance

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

The second form of this function accepts a pointer to an array of N values.

Errors
None.
See also
popnstddev, mean, meanandstddev, stddev, momentskewkurtosis

45#45


12.3.36 power

Declaration
Function power(base,exponent : float) : float;
Description
power raises base to the power power. This is equivalent to exp(power*ln(base)). Therefore base should be non-negative.
Errors
None.
See also
intpower

46#46


12.3.37 radtocycle

Declaration
Function radtocycle(rad : float) : float;
Description
Radtocycle converts its argument rad (an angle expressed in radians) to an angle in cycles.

(1 cycle equals 2 pi radians)

Errors
None.
See also
degtograd, degtorad, radtodeg, radtograd, cycletorad

47#47


12.3.38 radtodeg

Declaration
Function radtodeg(rad : float) : float;
Description
Radtodeg converts its argument rad (an angle expressed in radians) to an angle in degrees.

(180 degrees equals pi radians)

Errors
None.
See also
degtograd, degtorad, radtocycle, radtograd, cycletorad

48#48


12.3.39 radtograd

Declaration
Function radtograd(rad : float) : float;
Description
Radtodeg converts its argument rad (an angle expressed in radians) to an angle in grads.

(200 grads equals pi radians)

Errors
None.
See also
degtograd, degtorad, radtocycle, radtodeg, cycletorad

49#49


12.3.40 randg

Declaration
Function randg(mean,stddev : float) : float;
Description
randg returns a random number which - when produced in large quantities - has a Gaussian distribution with mean mean and standarddeviation stddev.
Errors
None.
See also
mean, stddev, meanandstddev

50#50


12.3.41 sincos

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

On Intel hardware, This calculation will be faster than making 2 calls to clculatet he sine and cosine separately.

Errors
None.
See also
arcsin, arccos.

51#51


12.3.42 sinh

Declaration
Function sinh(x : float) : float;
Description
Sinh returns the hyperbolic sine of its argument x.
Errors
See also
cosh, arsinh, tanh, artanh

52#52


12.3.43 stddev

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

The second form of the function accepts a pointer to an array of N values.

Errors
None.
See also
mean, meanandstddev, variance, totalvariance

53#53


12.3.44 sum

Declaration
Function sum(const data : array of float) : float; Function sum(const data : PFloat; Const N : Integer) : float;
Description
Sum returns the sum of the values in the data array.

The second form of the function accepts a pointer to an array of N values.

Errors
None.
See also
sumofsquares, sumsandsquares, totalvariance , variance

54#54


12.3.45 sumofsquares

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

The second form of the function accepts a pointer to an array of N values.

Errors
None.
See also
sum, sumsandsquares, totalvariance , variance

55#55


12.3.46 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
sumsandsquares calculates the sum of the values and the sum of the squares of the values in the data array and returns the results in sum and sumofsquares.

The second form of the function accepts a pointer to an array of N values.

Errors
None.
See also
sum, sumofsquares, totalvariance , variance

56#56


12.3.47 tan

Declaration
Function tan(x : float) : float;
Description
Tan returns the tangent of x.
Errors
If x (normalized) is pi/2 or 3pi/2 then an overflow will occur.
See also
tanh, arcsin, sincos, arccos

57#57


12.3.48 tanh

Declaration
Function tanh(x : float) : float;
Description
Tanh returns the hyperbolic tangent of x.
Errors
None.
See also
arcsin, sincos, arccos

58#58


12.3.49 totalvariance

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

The second form of the function accepts a pointer to an array of N values.

Errors
None.
See also
variance, stddev, mean

59#59


12.3.50 variance

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

The second form of the function accepts a pointer to an array of N values.

Errors
None.
See also
totalvariance, stddev, mean

60#60


root
2000-09-24