# std.math

**Source:**

std/math.d

- const real
__E__; - e

- const real
__LOG2T__; - log
_{2}10

- const real
__LOG2E__; - log
_{2}e

- const real
__LOG2__; - log
_{10}2

- const real
__LOG10E__; - log
_{10}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__; - √½

- 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^{2}+ z.im^{2}) = 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^{2}-*z*.im^{2}is always a real number

- 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^{64}.

- 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^{64}.

- 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(θ).

- 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
__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
__acos__(real*x*); - Calculates the arc cosine of
*x*, returning a value ranging from 0 to π.

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 -π to π.

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

- 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

- real
__acosh__(real*x*); - Calculates the inverse hyperbolic cosine of
*x*.

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

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*); - 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

Special Values *x*acosh( *x*)NAN NAN ±0 ±0 -∞ -0

- long
__rndtol__(real*x*); - Returns
*x*rounded to a long value using the current rounding mode. If the integer value of*x*is greater than long.max, the result is indeterminate.

- real
__rndtonl__(real*x*); - Returns
*x*rounded to a long value using the FE_TONEAREST rounding mode. If the integer value of*x*is greater than long.max, the result is indeterminate.

- float
__sqrt__(float*x*);

double__sqrt__(double*x*);

real__sqrt__(real*x*); - Compute square root of
*x*.

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

- real
__exp__(real*x*); - Calculates e
*x*.

Special Values *x*e *x*+∞ +∞ -∞ +0.0 NAN NAN

- 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*e *x*-1±0.0 ±0.0 +∞ +∞ -∞ -1.0 NAN NAN

- real
__exp2__(real*x*); - Calculates 2
*x*.

Special Values *x*__exp2__(*x*)+∞ +∞ -∞ +0.0 NAN NAN

- creal
__expi__(real*y*); - Calculate cos(
*y*) + i sin(*y*).

On many CPUs (such as x86), this is a very efficient operation; almost twice as fast as calculating sin(*y*) and cos(*y*) separately, and is the preferred method when both are required.

- real
__frexp__(real*value*, out int*exp*); - Separate floating point
*value*into significand and exponent.

**Returns:**

Calculate and return*x*andsuch that*exp**value*=*x**2*exp*and .5 <= |*x*| < 1.0

*x*has same sign as*value*.

Special Values *value*returns *exp*±0.0 ±0.0 0 +∞ +∞ int.max -∞ -∞ int.min ±NAN ±NAN int.min

- int
__ilogb__(real*x*); - Extracts the exponent of
*x*as a signed integral value.

If*x*is not a special value, the result is the same as .

Special Values *x*__ilogb__(*x*)Range error? 0 FP_ILOGB0 yes ±∞ int.max no NAN FP_ILOGBNAN no

- real
__ldexp__(real*n*, int*exp*); - Compute
*n** 2*exp*

**References:**

frexp

- 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
__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

- 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_{2}*x*

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

- real
__logb__(real*x*); - Extracts the exponent of
*x*as a signed integral value.

If*x*is subnormal, it is treated as if it were normalized. For a positive, finite*x*:

1 <=* FLT_RADIX-*x*__logb__(*x*) < FLT_RADIX

Special Values *x*__logb__(*x*)divide by 0? ±∞ +∞ no ±0.0 -∞ yes

- real
__modf__(real*x*, ref real*i*); - Calculates the remainder from the calculation
*x*/y.

**Returns:**

The value of*x*-*i** y, where*i*is the number of times that y can be completely subtracted from*x*. The result has the same sign as*x*.

Special Values *x*y __modf__(*x*, y)invalid? ±0.0 not 0.0 ±0.0 no ±∞ anything NAN yes anything ±0.0 NAN yes !=±∞ ±∞ *x*no

- real
__scalbn__(real*x*, int*n*); - Efficiently calculates
*x** 2*n*.

__scalbn__handles underflow and overflow in the same fashion as the basic arithmetic operators.

Special Values *x*scalb( *x*)±∞ ±∞ ±0.0 ±0.0

- 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
__fabs__(real*x*); - Returns |
*x*|

Special Values *x*__fabs__(*x*)±0.0 +0.0 ±∞ +∞

- 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( + )

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

- real
__erf__(real*x*); - Returns the error function of
*x*.

- real
__erfc__(real*x*); - Returns the complementary error function of
*x*, which is 1 - erf(*x*).

- real
__lgamma__(real*x*); - Natural logarithm of gamma function.

Returns the base e (2.718...) logarithm of the absolute value of the gamma function of the argument.

For reals,__lgamma__is equivalent to log(fabs(gamma(*x*))).

Special Values *x*__lgamma__(*x*)invalid? NAN NAN yes integer <= 0 +∞ yes ±∞ +∞ no

- real
__tgamma__(real*x*); - The Gamma function, Γ(
*x*)

Γ(*x*) is a generalisation of the factorial function to real and complex numbers. Like*x*!, Γ(*x*+1) =*x**Γ(*x*).

Mathematically, if z.re > 0 then Γ(z) = ∫_{0}^{∞}t^{z-1}e^{-t}dt

Special Values *x*Γ( *x*)invalid? NAN NAN yes ±0.0 ±∞ yes integer >0 ( *x*-1)!no integer <0 NAN yes +∞ +∞ no -∞ NAN yes

**References:**

http://en.wikipedia.org/wiki/Gamma_function, http://www.netlib.org/cephes/ldoubdoc.html#gamma

- real
__ceil__(real*x*); - Returns the value of
*x*rounded upward to the next integer (toward positive infinity).

- real
__floor__(real*x*); - Returns the value of
*x*rounded downward to the next integer (toward negative infinity).

- real
__nearbyint__(real*x*); - Rounds
*x*to the nearest integer value, using the current rounding mode.

Unlike the rint functions,__nearbyint__does not raise the FE_INEXACT exception.

- real
__rint__(real*x*); - Rounds
*x*to the nearest integer value, using the current rounding mode. If the return value is not equal to*x*, the FE_INEXACT exception is raised.**nearbyint**performs the same operation, but does not set the FE_INEXACT exception.

- long
__lrint__(real*x*); - Rounds
*x*to the nearest integer value, using the current rounding mode.

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)__lrint__(4.5) == 4,__lrint__(5.5)==6.

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

- long
__lround__(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 away from zero.

**Note:**

Not supported on windows

- real
__trunc__(real*x*); - Returns the integer portion of
*x*, dropping the fractional portion.

This is also known as "chop" rounding.

- real
__remainder__(real*x*, real*y*);

real__remquo__(real*x*, real*y*, out int*n*); - Calculate the
__remainder__*x*REM*y*, following IEC 60559.

REM is the value of*x*-*y** n, where n is the integer nearest the exact value of*x*/*y*. If |n -*x*/*y*| == 0.5, n is even. If the result is zero, it has the same sign as*x*. Otherwise, the sign of the result is the sign of*x*/*y*. Precision mode has no effect on the__remainder__functions.

remquo returns n in the parameter n.

Special Values *x**y*__remainder__(*x*,*y*)n invalid? ±0.0 not 0.0 ±0.0 0.0 no ±∞ anything NAN ? yes anything ±0.0 NAN ? yes != ±∞ ±∞ *x*? no

**Note:**

remquo not supported on windows

- int
__isnan__(real*x*); - Returns !=0 if e is a NaN.

- int
__isfinite__(real*e*); - Returns !=0 if
*e*is finite (not infinite or NAN).

- int
__isnormal__(X)(X*x*); - Returns !=0 if x is normalized (not zero, subnormal, infinite, or NAN).

- int
__issubnormal__(float*f*);

int__issubnormal__(double*d*);

int__issubnormal__(real*x*); - Is number subnormal? (Also called "denormal".)
Subnormals have a 0 exponent and a 0 most significant mantissa bit.

- int
__isinf__(real*x*); - Return !=0 if e is ±∞.

- bool
__isIdentical__(real*x*, real*y*); - Is the binary representation of
*x*identical to*y*?

Same as ==, except that positive and negative zero are not identical, and two NANs are identical if they have the same 'payload'.

- int
__signbit__(real*x*); - Return 1 if sign bit of e is set, 0 if not.

- real
__copysign__(real*to*, real*from*); - Return a value composed of
*to*with*from*'s sign bit.

- real
__nan__(char[]*tagp*); - Creates a quiet NAN with the information from
*tagp*[] embedded in it.

BUGS:

DMD always returns real.__nan__, ignoring the payload.

- real
__nextUp__(real*x*);

double__nextUp__(double*x*);

float__nextUp__(float*x*); - Calculate the next largest floating point value after
*x*.

Return the least number greater than*x*that is representable as a real; thus, it gives the next point on the IEEE number line.

Special Values *x*__nextUp__(*x*)-∞ -real.max ±0.0 real.min*real.epsilon real.max ∞ ∞ ∞ NAN NAN

**Remarks:**

This function is included in the forthcoming IEEE 754R standard.

- real
__nextDown__(real*x*);

double__nextDown__(double*x*);

float__nextDown__(float*x*); - Calculate the next smallest floating point value before
*x*.

Return the greatest number less than*x*that is representable as a real; thus, it gives the previous point on the IEEE number line.

Special Values *x*__nextDown__(*x*)∞ real.max ±0.0 -real.min*real.epsilon -real.max -∞ -∞ -∞ NAN NAN

**Remarks:**

This function is included in the forthcoming IEEE 754R standard.

- real
__nextafter__(real*x*, real*y*);

float__nextafter__(float*x*, float*y*);

double__nextafter__(double*x*, double*y*); - Calculates the next representable value after
*x*in the direction of*y*.

If*y*>*x*, the result will be the next largest floating-point value; if*y*<*x*, the result will be the next smallest value. If*x*==*y*, the result is*y*.

**Remarks:**

This function is not generally very useful; it's almost always better to use the faster functions nextUp() or nextDown() instead.

IEEE 754 requirements not implemented on Windows: The FE_INEXACT and FE_OVERFLOW exceptions will be raised if*x*is finite and the function result is infinite. The FE_INEXACT and FE_UNDERFLOW exceptions will be raised if the function value is subnormal, and*x*is not equal to*y*.

- real
__fdim__(real*x*, real*y*); - Returns the positive difference between
*x*and*y*.

**Returns:**

Special Values *x*,*y*__fdim__(*x*,*y*)*x*>*y**x*-*y**x*<=*y*+0.0

- real
__fmax__(real*x*, real*y*); - Returns the larger of
*x*and*y*.

- real
__fmin__(real*x*, real*y*); - Returns the smaller of
*x*and*y*.

- real
__fma__(real*x*, real*y*, real*z*); - Returns (
*x***y*) +*z*, rounding only once according to the current rounding mode.

BUGS:

Not currently implemented - rounds twice.

- real
__pow__(real*x*, uint*n*);

real__pow__(real*x*, int*n*); - Fast integral powers.

- real
__pow__(real*x*, real*y*); - Calculates
*x**y*.

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

- int
__feqrel__(X)(X*x*, X*y*); - To what precision is x equal to y?

**Returns:**

the number of mantissa bits which are equal in x and y. eg, 0x1.F8p+60 and 0x1.F1p+60 are equal to 5 bits of precision.

Special Values x y __feqrel__(x, y)x x real.mant_dig x >= 2*x 0 x <= x/2 0 NAN any 0 any NAN 0

- real
__poly__(real*x*, real[]*A*); - Evaluate polynomial
*A*(*x*) = a_{0}+ a_{1}*x*+ a_{2}² + a_{3}*x*³ ...

Uses Horner's rule*A*(*x*) = a_{0}+*x*(a_{1}+*x*(a_{2}+*x*(a_{3}+ ...)))

**Params:**

real[] *A*array of coefficients a _{0}, a_{1}, etc.