tango.math.Math

Elementary Mathematical Functions

License:
BSD style: see license.txt, Digital Mars.

Authors:
Walter Bright, Don Clugston, Sean Kelly

const real E ;

const real LOG2T ;

log₂10

const real LOG2E ;

log₂e

const real LOG2 ;

log₁₀2

const real LOG10E ;

log₁₀e

const real LN2 ;

ln 2

const real LN10 ;

ln 10

const real PI ;

const real PI_2 ;

π / 2

const real PI_4 ;

π / 4

const real M_1_PI ;

1 / π

const real M_2_PI ;

2 / π

const real M_2_SQRTPI ;

2 / √π

const real SQRT2 ;

√2

const real SQRT1_2 ;

√½

const real MAXLOG ;

log(real.max)

const real MINLOG ;

log(real.min*real.epsilon)

const real EULERGAMMA ;

Euler-Mascheroni constant 0.57721566..

real abs (real x); long abs (long x); int abs (int x); real abs (creal z); real abs (ireal y);

Calculates the absolute value

For complex numbers, abs (z) = sqrt( z.re² + z.im² ) = hypot(z.re, z.im).

creal conj (creal z); ireal conj (ireal y);

Complex conjugate

conj (x + iy) = x - iy

Note that z * conj (z) = z.re² + z.im² is always a real number

minmaxtype!(T) min (T...)(T arg);

Return the minimum of the supplied arguments.

Note:
If the arguments are floating-point numbers, and at least one is a NaN, the result is undefined.

minmaxtype!(T) max (T...)(T arg);

Return the maximum of the supplied arguments.

Note:
If the arguments are floating-point numbers, and at least one is a NaN, the result is undefined.

real minNum (real x, real y);

Returns the minimum number of x and y, favouring numbers over NaNs.

If both x and y are numbers, the minimum is returned. If both parameters are NaN, either will be returned. If one parameter is a NaN and the other is a number, the number is returned (this behaviour is mandated by IEEE 754R, and is useful for determining the range of a function).

real maxNum (real x, real y);

Returns the maximum number of x and y, favouring numbers over NaNs.

If both x and y are numbers, the maximum is returned. If both parameters are NaN, either will be returned. If one parameter is a NaN and the other is a number, the number is returned (this behaviour is mandated by IEEE 754R, and is useful for determining the range of a function).

real minNaN (real x, real y);

Returns the minimum of x and y, favouring NaNs over numbers

If both x and y are numbers, the minimum is returned. If both parameters are NaN, either will be returned. If one parameter is a NaN and the other is a number, the NaN is returned.

real maxNaN (real x, real y);

Returns the maximum of x and y, favouring NaNs over numbers

If both x and y are numbers, the maximum is returned. If both parameters are NaN, either will be returned. If one parameter is a NaN and the other is a number, the NaN is returned.

real cos (real x);

Returns cosine of x. x is in radians.

Special Values
x	cos (x)	invalid?
NAN	NAN	yes
±∞	NAN	yes

BUGS:
Results are undefined if |x| >= 2⁶⁴.

real sin (real x);

Returns sine of x. x is in radians.

Special Values
x	sin (x)	invalid?
NAN	NAN	yes
±0.0	±0.0	no
±∞	NAN	yes

BUGS:
Results are undefined if |x| >= 2⁶⁴.

real tan (real x);

Returns tangent of x. x is in radians.

Special Values
x	tan (x)	invalid?
NAN	NAN	yes
±0.0	±0.0	no
±∞	NAN	yes

real cosPi (real x); real sinPi (real x); real atanPi (real x);

Sine, cosine, and arctangent of multiple of π

Accuracy is preserved for large values of x.

creal sin (creal z); ireal sin (ireal y);

sine, complex and imaginary

sin (z) = sin (z.re)*cosh(z.im) + cos(z.re)*sinh(z.im)i

If both sin (θ) and cos(θ) are required, it is most efficient to use expi(&theta).

creal cos (creal z); real cos (ireal y);

cosine, complex and imaginary

cos (z) = cos (z.re)*cosh(z.im) + sin(z.re)*sinh(z.im)i

real acos (real x);

Calculates the arc cosine of x, returning a value ranging from -π/2 to π/2.

Special Values
x	acos (x)	invalid?
>1.0	NAN	yes
<-1.0	NAN	yes
NAN	NAN	yes

real asin (real x);

Calculates the arc sine of x, returning a value ranging from -π/2 to π/2.

Special Values
x	asin (x)	invalid?
±0.0	±0.0	no
>1.0	NAN	yes
<-1.0	NAN	yes

real atan (real x);

Calculates the arc tangent of x, returning a value ranging from -π/2 to π/2.

Special Values
x	atan (x)	invalid?
±0.0	±0.0	no
±∞	NAN	yes

real atan2 (real y, real x);

Calculates the arc tangent of y / x, returning a value ranging from -π/2 to π/2.

Remarks:
The Complex Argument of a complex number z is given by Arg(z) = atan2 (z.re, z.im)

Special Values
y	x	atan(y, x)
NAN	anything	NAN
anything	NAN	NAN
±0.0	> 0.0	±0.0
±0.0	±0.0	±0.0
±0.0	< 0.0	±π
±0.0	-0.0	±π
> 0.0	±0.0	π/2
< 0.0	±0.0	π/2
> 0.0	∞	±0.0
±∞	anything	±π/2
> 0.0	-∞	±π
±∞	∞	±π/4
±∞	-∞	±3π/4

creal asin (creal z);

Complex inverse sine

asin (z) = -i log( sqrt(1-z²) + iz) where both log and sqrt are complex.

creal acos (creal z);

Complex inverse cosine

acos (z) = &pi/2 - asin(z)

real cosh (real x);

Calculates the hyperbolic cosine of x.

Special Values
x	cosh (x)	invalid?
±∞	±0.0	no

real sinh (real x);

Calculates the hyperbolic sine of x.

Special Values
x	sinh (x)	invalid?
±0.0	±0.0	no
±∞	±∞	no

real tanh (real x);

Calculates the hyperbolic tangent of x.

Special Values
x	tanh (x)	invalid?
±0.0	±0.0	no
±∞	±1.0	no

creal sinh (creal z); ireal sinh (ireal y);

hyperbolic sine, complex and imaginary

sinh (z) = cos(z.im)* sinh (z.re) + sin(z.im)*cosh(z.re)i

creal cosh (creal z); real cosh (ireal y);

hyperbolic cosine, complex and imaginary

cosh (z) = cos(z.im)* cosh (z.re) + sin(z.im)*sinh(z.re)i

real acosh (real x);

Calculates the inverse hyperbolic cosine of x.

Mathematically, acosh (x) = log(x + sqrt( x*x - 1))

Domain	1..∞
Range	1..log(real.max), ∞

Special Values
x	acosh (x)
NAN	NAN
<1	NAN
1	0
+∞	+∞

real asinh (real x);

Calculates the inverse hyperbolic sine of x.

Mathematically,

  asinh(x) =  log( x + sqrt( x*x + 1 )) // if x >= +0
  asinh(x) = -log(-x + sqrt( x*x + 1 )) // if x <= -0

Special Values
x	asinh (x)
NAN	NAN
±0	±0
±∞	±∞

real atanh (real x); creal atanh (ireal y); creal atanh (creal z);

Calculates the inverse hyperbolic tangent of x, returning a value from ranging from -1 to 1.

Mathematically, atanh (x) = log( (1+x)/(1-x) ) / 2

Domain	-∞..∞
Range	-1..1

Special Values
x	atanh (x)
NAN	NAN
±0	±0
±1	±∞

float sqrt (float x); double sqrt (double x); real sqrt (real x); creal sqrt (creal z);

Compute square root of x.

Special Values
x	sqrt (x)	invalid?
-0.0	-0.0	no
<0.0	NAN	yes
+∞	+∞	no

real cbrt (real x);

Calculates the cube root of x.

Special Values
x	cbrt (x)	invalid?
±0.0	±0.0	no
NAN	NAN	yes
±∞	±∞	no

real exp (real x);

Calculates ex.

Special Values
x	exp (x)
+∞	+∞
-∞	+0.0

real expm1 (real x);

Calculates the value of the natural logarithm base (e) raised to the power of x, minus 1.

For very small x, expm1 (x) is more accurate than exp(x)-1.

Special Values
x	ex-1
±0.0	±0.0
+∞	+∞
-∞	-1.0

real exp2 (real x);

Calculates 2x.

Special Values
x	exp2 (x)
+∞	+∞
-∞	+0.0

real log (real x);

Calculate the natural logarithm of x.

Special Values
x	log (x)	divide by 0?	invalid?
±0.0	-∞	yes	no
< 0.0	NAN	no	yes
+∞	+∞	no	no

real log1p (real x);

Calculates the natural logarithm of 1 + x.

For very small x, log1p (x) will be more accurate than log(1 + x).

Special Values
x	log1p (x)	divide by 0?	invalid?
±0.0	±0.0	no	no
-1.0	-∞	yes	no
<-1.0	NAN	no	yes
+∞	-∞	no	no

real log2 (real x);

Calculates the base-2 logarithm of x: log₂x

Special Values
x	log2 (x)	divide by 0?	invalid?
±0.0	-∞	yes	no
< 0.0	NAN	no	yes
+∞	+∞	no	no

real log10 (real x);

Calculate the base-10 logarithm of x.

Special Values
x	log10 (x)	divide by 0?	invalid?
±0.0	-∞	yes	no
< 0.0	NAN	no	yes
+∞	+∞	no	no

creal exp (ireal y); creal exp (creal z);

Exponential, complex and imaginary

For complex numbers, the exponential function is defined as

exp (z) = exp (z.re)cos(z.im) + exp (z.re)sin(z.im)i.

For a pure imaginary argument, exp (θi) = cos(θ) + sin(θ)i.

creal log (creal z);

Natural logarithm, complex

Returns complex logarithm to the base e (2.718...) of the complex argument x.

If z = x + iy, then log (z) = log (abs(z)) + i arctan(y/x).

The arctangent ranges from -PI to +PI. There are branch cuts along both the negative real and negative imaginary axes. For pure imaginary arguments, use one of the following forms, depending on which branch is required.

    log( 0.0 + yi) = log(-y) + PI_2i  // y<=-0.0
    log(-0.0 + yi) = log(-y) - PI_2i  // y<=-0.0

real pow (real x, uint n); real pow (real x, int n);

Fast integral powers.

real pow (real x, real y);

Calculates xy.

Special Values
x	y	pow (x, y)	div 0	invalid?
anything	±0.0	1.0	no	no
\|x\| > 1	+∞	+∞	no	no
\|x\| < 1	+∞	+0.0	no	no
\|x\| > 1	-∞	+0.0	no	no
\|x\| < 1	-∞	+∞	no	no
+∞	> 0.0	+∞	no	no
+∞	< 0.0	+0.0	no	no
-∞	odd integer > 0.0	-∞	no	no
-∞	> 0.0, not odd integer	+∞	no	no
-∞	odd integer < 0.0	-0.0	no	no
-∞	< 0.0, not odd integer	+0.0	no	no
±1.0	±∞	NAN	no	yes
< 0.0	finite, nonintegral	NAN	no	yes
±0.0	odd integer < 0.0	±∞	yes	no
±0.0	< 0.0, not odd integer	+∞	yes	no
±0.0	odd integer > 0.0	±0.0	no	no
±0.0	> 0.0, not odd integer	+0.0	no	no

real hypot (real x, real y);

Calculates the length of the hypotenuse of a right-angled triangle with sides of length x and y. The hypotenuse is the value of the square root of the sums of the squares of x and y:

sqrt(x² + y²)

Note that hypot (x, y), hypot (y, x) and hypot (x, -y) are equivalent.

Special Values
x	y	hypot (x, y)	invalid?
x	±0.0	\|x\|	no
±∞	y	+∞	no
±∞	NAN	+∞	no

T poly (T)(T x, T[] A);

Evaluate polynomial A(x) = a₀ + a₁x + a₂x² + a₃x³ ...

Uses Horner's rule A(x) = a₀ + x(a₁ + x(a₂ + x(a₃ + ...)))

Params:

A	array of coefficients a₀, a₁, etc.

bool feq (int precision = MANTDIG_2,XReal = real,YReal = real)(XReal x, YReal y);

Floating point "approximate equality".

Return true if x is equal to y, to within the specified precision If roundoffbits is not specified, a reasonable default is used.

real floor (real x);

Returns the value of x rounded downward to the next integer (toward negative infinity).

real ceil (real x);

Returns the value of x rounded upward to the next integer (toward positive infinity).

real round (real x);

Return the value of x rounded to the nearest integer. If the fractional part of x is exactly 0.5, the return value is rounded to the even integer.

real trunc (real x);

Returns the integer portion of x, dropping the fractional portion.

This is also known as "chop" rounding.

int rndint (real x); long rndlong (real x);

Rounds x to the nearest int or long.

This is generally the fastest method to convert a floating-point number to an integer. Note that the results from this function depend on the rounding mode, if the fractional part of x is exactly 0.5. If using the default rounding mode (ties round to even integers) rndint (4.5) == 4, rndint (5.5)==6.

anchorFromTitle('tango.math.Math', 'source/', 'html');