Report a bug
If you spot a problem with this page, click here to create a Bugzilla issue.
Improve this page
Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using a local clone.

std.math

Contains the elementary mathematical functions (powers, roots, and trigonometric functions), and low-level floating-point operations. Mathematical special functions are available in std.mathspecial.
Category Members
Constants E  PI  PI_2  PI_4  M_1_PI  M_2_PI  M_2_SQRTPI  LN10  LN2  LOG2  LOG2E  LOG2T  LOG10E  SQRT2  SQRT1_2 
Classics abs  fabs  sqrt  cbrt  hypot  poly  nextPow2  truncPow2 
Trigonometry sin  cos  tan  asin  acos  atan  atan2  sinh  cosh  tanh  asinh  acosh  atanh  expi 
Rounding ceil  floor  round  lround  trunc  rint  lrint  nearbyint  rndtol  quantize 
Exponentiation & Logarithms pow  exp  exp2  expm1  ldexp  frexp  log  log2  log10  logb  ilogb  log1p  scalbn 
Modulus fmod  modf  remainder 
Floating-point operations approxEqual  feqrel  fdim  fmax  fmin  fma  nextDown  nextUp  nextafter  NaN  getNaNPayload  cmp 
Introspection isFinite  isIdentical  isInfinity  isNaN  isNormal  isSubnormal  signbit  sgn  copysign  isPowerOf2 
Complex Numbers abs  conj  sin  cos  expi 
Hardware Control IeeeFlags  FloatingPointControl 
The functionality closely follows the IEEE754-2008 standard for floating-point arithmetic, including the use of camelCase names rather than C99-style lower case names. All of these functions behave correctly when presented with an infinity or NaN.
The following IEEE 'real' formats are currently supported:
  • 64 bit Big-endian 'double' (eg PowerPC)
  • 128 bit Big-endian 'quadruple' (eg SPARC)
  • 64 bit Little-endian 'double' (eg x86-SSE2)
  • 80 bit Little-endian, with implied bit 'real80' (eg x87, Itanium)
  • 128 bit Little-endian 'quadruple' (not implemented on any known processor!)
  • Non-IEEE 128 bit Big-endian 'doubledouble' (eg PowerPC) has partial support
Unlike C, there is no global 'errno' variable. Consequently, almost all of these functions are pure nothrow.

Status The semantics and names of feqrel and approxEqual will be revised.

Authors:
Walter Bright, Don Clugston, Conversion of CEPHES math library to D by Iain Buclaw and David Nadlinger

Source std/math.d

enum real E;
e = 2.718281...
enum real LOG2T;
log210 = 3.321928...
enum real LOG2E;
log2e = 1.442695...
enum real LOG2;
log102 = 0.301029...
enum real LOG10E;
log10e = 0.434294...
enum real LN2;
ln 2 = 0.693147...
enum real LN10;
ln 10 = 2.302585...
enum real PI;
π = 3.141592...
enum real PI_2;
π / 2 = 1.570796...
enum real PI_4;
π / 4 = 0.785398...
enum real M_1_PI;
1 / π = 0.318309...
enum real M_2_PI;
2 / π = 0.636619...
enum real M_2_SQRTPI;
2 / √π = 1.128379...
enum real SQRT2;
√2 = 1.414213...
enum real SQRT1_2;
√½ = 0.707106...
pure nothrow @safe Num abs(Num)(Num x)
if (is(typeof(Num.init >= 0)) && is(typeof(-Num.init)) && !(is(Num* : const(ifloat*)) || is(Num* : const(idouble*)) || is(Num* : const(ireal*))));

pure nothrow @nogc @safe auto abs(Num)(Num z)
if (is(Num* : const(cfloat*)) || is(Num* : const(cdouble*)) || is(Num* : const(creal*)));

pure nothrow @nogc @safe auto abs(Num)(Num y)
if (is(Num* : const(ifloat*)) || is(Num* : const(idouble*)) || is(Num* : const(ireal*)));
Calculates the absolute value of a number
Parameters:
Num (template parameter) type of number
Num x real number value
Num z complex number value
Num y imaginary number value
Returns:
The absolute value of the number. If floating-point or integral, the return type will be the same as the input; if complex or imaginary, the returned value will be the corresponding floating point type.
For complex numbers, abs(z) = sqrt( z.re2 + z.im2 ) = hypot(z.re, z.im).
Examples:
ditto
assert(isIdentical(abs(-0.0L), 0.0L));
assert(isNaN(abs(real.nan)));
writeln(abs(-real.infinity)); // real.infinity
writeln(abs(-3.2Li)); // 3.2L
writeln(abs(71.6Li)); // 71.6L
writeln(abs(-56)); // 56
writeln(abs(2321312L)); // 2321312L
writeln(abs(-1L + 1i)); // sqrt(2.0L)
pure nothrow @nogc @safe auto conj(Num)(Num z)
if (is(Num* : const(cfloat*)) || is(Num* : const(cdouble*)) || is(Num* : const(creal*)));

pure nothrow @nogc @safe auto conj(Num)(Num y)
if (is(Num* : const(ifloat*)) || is(Num* : const(idouble*)) || is(Num* : const(ireal*)));
Complex conjugate
conj(x + iy) = x - iy
Note that z * conj(z) = z.re2 - z.im2 is always a real number
Examples:
creal c = 7 + 3Li;
writeln(conj(c)); // 7 - 3Li
ireal z = -3.2Li;
writeln(conj(z)); // -z
pure nothrow @nogc @safe real cos(real x);

pure nothrow @nogc @safe double cos(double x);

pure nothrow @nogc @safe float cos(float 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| >= 264.
pure nothrow @nogc @safe real sin(real x);

pure nothrow @nogc @safe double sin(double x);

pure nothrow @nogc @safe float sin(float 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
Parameters:
real x angle in radians (not degrees)
Returns:
sine of x
See Also:
cos , tan , asin 
Bugs:
Results are undefined if |x| >= 264.
Examples:
import std.math : sin, PI;
import std.stdio : writefln;

void someFunc()
{
  real x = 30.0;
  auto result = sin(x * (PI / 180)); // convert degrees to radians
  writefln("The sine of %s degrees is %s", x, result);
}
pure nothrow @nogc @safe creal sin(creal z);

pure nothrow @nogc @safe ireal sin(ireal y);
Returns sine for complex and imaginary arguments.
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(θ).
Examples:
writeln(sin(0.0 + 0.0i)); // 0.0
writeln(sin(2.0 + 0.0i)); // sin(2.0L)
pure nothrow @nogc @safe creal cos(creal z);

pure nothrow @nogc @safe real cos(ireal y);
cosine, complex and imaginary
cos(z) = cos(z.re)*cosh(z.im) - sin(z.re)*sinh(z.im)i
Examples:
writeln(cos(0.0 + 0.0i)); // 1.0
writeln(cos(1.3L + 0.0i)); // cos(1.3L)
writeln(cos(5.2Li)); // cosh(5.2L)
pure nothrow @nogc @trusted 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
pure nothrow @nogc @safe real acos(real x);

pure nothrow @nogc @safe double acos(double x);

pure nothrow @nogc @safe float acos(float 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
pure nothrow @nogc @safe real asin(real x);

pure nothrow @nogc @safe double asin(double x);

pure nothrow @nogc @safe float asin(float 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
pure nothrow @nogc @safe real atan(real x);

pure nothrow @nogc @safe double atan(double x);

pure nothrow @nogc @safe float atan(float 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
pure nothrow @nogc @trusted real atan2(real y, real x);

pure nothrow @nogc @safe double atan2(double y, double x);

pure nothrow @nogc @safe float atan2(float y, float 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
pure nothrow @nogc @safe real cosh(real x);

pure nothrow @nogc @safe double cosh(double x);

pure nothrow @nogc @safe float cosh(float x);
Calculates the hyperbolic cosine of x.
Special Values
x cosh(x) invalid?
±∞ ±0.0 no
pure nothrow @nogc @safe real sinh(real x);

pure nothrow @nogc @safe double sinh(double x);

pure nothrow @nogc @safe float sinh(float x);
Calculates the hyperbolic sine of x.
Special Values
x sinh(x) invalid?
±0.0 ±0.0 no
±∞ ±∞ no
pure nothrow @nogc @safe real tanh(real x);

pure nothrow @nogc @safe double tanh(double x);

pure nothrow @nogc @safe float tanh(float x);
Calculates the hyperbolic tangent of x.
Special Values
x tanh(x) invalid?
±0.0 ±0.0 no
±∞ ±1.0 no
pure nothrow @nogc @safe real acosh(real x);

pure nothrow @nogc @safe double acosh(double x);

pure nothrow @nogc @safe float acosh(float x);
Calculates the inverse hyperbolic cosine of x.
Mathematically, acosh(x) = log(x + sqrt( x*x - 1))
Domain X Range Y
1..∞ 0..∞
Special Values
x acosh(x)
NAN NAN
<1 NAN
1 0
+∞ +∞
pure nothrow @nogc @safe real asinh(real x);

pure nothrow @nogc @safe double asinh(double x);

pure nothrow @nogc @safe float asinh(float 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
±∞ ±∞
pure nothrow @nogc @safe real atanh(real x);

pure nothrow @nogc @safe double atanh(double x);

pure nothrow @nogc @safe float atanh(float 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
Domain X Range Y
-∞..∞ -1 .. 1

Special Values
x acosh(x)
NAN NAN
±0 ±0
-∞ -0
pure nothrow @nogc @safe long rndtol(real x);

pure nothrow @nogc @safe long rndtol(double x);

pure nothrow @nogc @safe long rndtol(float 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.
pure nothrow @nogc @safe float sqrt(float x);

pure nothrow @nogc @safe double sqrt(double x);

pure nothrow @nogc @safe 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
pure nothrow @nogc @trusted real exp(real x);

pure nothrow @nogc @safe double exp(double x);

pure nothrow @nogc @safe float exp(float x);
Calculates ex.
Special Values
x ex
+∞ +∞
-∞ +0.0
NAN NAN
pure nothrow @nogc @trusted 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
NAN NAN
pure nothrow @nogc @trusted real exp2(real x);
Calculates 2x.
Special Values
x exp2(x)
+∞ +∞
-∞ +0.0
NAN NAN
pure nothrow @nogc @trusted 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.
Examples:
writeln(expi(1.3e5L)); // cos(1.3e5L) + sin(1.3e5L) * 1i
writeln(expi(0.0L)); // 1L + 0.0Li
pure nothrow @nogc @trusted T frexp(T)(const T value, out int exp)
if (isFloatingPoint!T);
Separate floating point value into significand and exponent.
Returns:
Calculate and return x and exp such that value =x*2exp 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
Examples:
int exp;
real mantissa = frexp(123.456L, exp);

// check if values are equal to 19 decimal digits of precision
assert(equalsDigit(mantissa * pow(2.0L, cast(real) exp), 123.456L, 19));

assert(frexp(-real.nan, exp) && exp == int.min);
assert(frexp(real.nan, exp) && exp == int.min);
assert(frexp(-real.infinity, exp) == -real.infinity && exp == int.min);
assert(frexp(real.infinity, exp) == real.infinity && exp == int.max);
assert(frexp(-0.0, exp) == -0.0 && exp == 0);
assert(frexp(0.0, exp) == 0.0 && exp == 0);
pure nothrow @nogc @trusted int ilogb(T)(const T x)
if (isFloatingPoint!T);

pure nothrow @nogc @safe int ilogb(T)(const T x)
if (isIntegral!T && isUnsigned!T);

pure nothrow @nogc @safe int ilogb(T)(const T x)
if (isIntegral!T && isSigned!T);
Extracts the exponent of x as a signed integral value.
If x is not a special value, the result is the same as cast(int) logb(x).
Special Values
x ilogb(x) Range error?
0 FP_ILOGB0 yes
±∞ int.max no
NAN FP_ILOGBNAN no
pure nothrow @nogc @safe real ldexp(real n, int exp);

pure nothrow @nogc @safe double ldexp(double n, int exp);

pure nothrow @nogc @safe float ldexp(float n, int exp);
Compute n * 2exp

References frexp

Examples:
import std.meta : AliasSeq;
foreach (T; AliasSeq!(float, double, real))
{
    T r;

    r = ldexp(3.0L, 3);
    writeln(r); // 24

    r = ldexp(cast(T) 3.0, cast(int) 3);
    writeln(r); // 24

    T n = 3.0;
    int exp = 3;
    r = ldexp(n, exp);
    writeln(r); // 24
}
pure nothrow @nogc @safe 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
Examples:
writeln(log(E)); // 1
pure nothrow @nogc @safe 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
Examples:
assert(fabs(log10(1000) - 3) < .000001);
pure nothrow @nogc @safe 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
pure nothrow @nogc @safe real log2(real x);
Calculates the base-2 logarithm of x: log2x
Special Values
x log2(x) divide by 0? invalid?
±0.0 -∞ yes no
<0.0 NAN no yes
+∞ +∞ no no
Examples:
// check if values are equal to 19 decimal digits of precision
assert(equalsDigit(log2(1024.0L), 10, 19));
nothrow @nogc @trusted 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 <= x * FLT_RADIX-logb(x) < FLT_RADIX
Special Values
x logb(x) divide by 0?
±∞ +∞ no
±0.0 -∞ yes
nothrow @nogc @trusted real fmod(real x, real y);
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 fmod(x, y) invalid?
±0.0 not 0.0 ±0.0 no
±∞ anything NAN yes
anything ±0.0 NAN yes
!=±∞ ±∞ x no
nothrow @nogc @trusted real modf(real x, ref real i);
Breaks x into an integral part and a fractional part, each of which has the same sign as x. The integral part is stored in i.
Returns:
The fractional part of x.
Special Values
x i (on input) modf(x, i) i (on return)
±∞ anything ±0.0 ±∞
nothrow @nogc @trusted real scalbn(real x, int n);
Efficiently calculates x * 2n.
scalbn handles underflow and overflow in the same fashion as the basic arithmetic operators.
Special Values
x scalb(x)
±∞ ±∞
±0.0 ±0.0
Examples:
writeln(scalbn(-real.infinity, 5)); // -real.infinity
nothrow @nogc @trusted 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
pure nothrow @nogc @safe real fabs(real x);

pure nothrow @nogc @safe double fabs(double x);

pure nothrow @nogc @safe float fabs(float x);
Returns |x|
Special Values
x fabs(x)
±0.0 +0.0
±∞ +∞
pure nothrow @nogc @safe 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(x2 + y2)
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
pure nothrow @nogc @trusted real ceil(real x);
Returns the value of x rounded upward to the next integer (toward positive infinity).
Examples:
writeln(ceil(+123.456L)); // +124
writeln(ceil(-123.456L)); // -123
writeln(ceil(-1.234L)); // -1
writeln(ceil(-0.123L)); // 0
writeln(ceil(0.0L)); // 0
writeln(ceil(+0.123L)); // 1
writeln(ceil(+1.234L)); // 2
writeln(ceil(real.infinity)); // real.infinity
assert(isNaN(ceil(real.nan)));
assert(isNaN(ceil(real.init)));
pure nothrow @nogc @trusted real floor(real x);
Returns the value of x rounded downward to the next integer (toward negative infinity).
Examples:
writeln(floor(+123.456L)); // +123
writeln(floor(-123.456L)); // -124
writeln(floor(-1.234L)); // -2
writeln(floor(-0.123L)); // -1
writeln(floor(0.0L)); // 0
writeln(floor(+0.123L)); // 0
writeln(floor(+1.234L)); // 1
writeln(floor(real.infinity)); // real.infinity
assert(isNaN(floor(real.nan)));
assert(isNaN(floor(real.init)));
Unqual!F quantize(alias rfunc = rint, F)(const F val, const F unit)
if (is(typeof(rfunc(F.init)) : F) && isFloatingPoint!F);
Round val to a multiple of unit. rfunc specifies the rounding function to use; by default this is rint, which uses the current rounding mode.
Examples:
writeln(12345.6789L.quantize(0.01L)); // 12345.68L
writeln(12345.6789L.quantize!floor(0.01L)); // 12345.67L
writeln(12345.6789L.quantize(22.0L)); // 12342.0L
Examples:
writeln(12345.6789L.quantize(0)); // 12345.6789L
assert(12345.6789L.quantize(real.infinity).isNaN);
assert(12345.6789L.quantize(real.nan).isNaN);
writeln(real.infinity.quantize(0.01L)); // real.infinity
assert(real.infinity.quantize(real.nan).isNaN);
assert(real.nan.quantize(0.01L).isNaN);
assert(real.nan.quantize(real.infinity).isNaN);
assert(real.nan.quantize(real.nan).isNaN);
Unqual!F quantize(real base, alias rfunc = rint, F, E)(const F val, const E exp)
if (is(typeof(rfunc(F.init)) : F) && isFloatingPoint!F && isIntegral!E);

Unqual!F quantize(real base, long exp = 1, alias rfunc = rint, F)(const F val)
if (is(typeof(rfunc(F.init)) : F) && isFloatingPoint!F);
Round val to a multiple of pow(base, exp). rfunc specifies the rounding function to use; by default this is rint, which uses the current rounding mode.
Examples:
writeln(12345.6789L.quantize!10(-2)); // 12345.68L
writeln(12345.6789L.quantize!(10, -2)); // 12345.68L
writeln(12345.6789L.quantize!(10, floor)(-2)); // 12345.67L
writeln(12345.6789L.quantize!(10, -2, floor)); // 12345.67L

writeln(12345.6789L.quantize!22(1)); // 12342.0L
writeln(12345.6789L.quantize!22); // 12342.0L
nothrow @nogc @trusted 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.
pure nothrow @nogc @safe real rint(real x);

pure nothrow @nogc @safe double rint(double x);

pure nothrow @nogc @safe float rint(float 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.
pure nothrow @nogc @trusted 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.
Examples:
writeln(lrint(4.5)); // 4
writeln(lrint(5.5)); // 6
writeln(lrint(-4.5)); // -4
writeln(lrint(-5.5)); // -6

writeln(lrint(int.max - 0.5)); // 2147483646L
writeln(lrint(int.max + 0.5)); // 2147483648L
writeln(lrint(int.min - 0.5)); // -2147483648L
writeln(lrint(int.min + 0.5)); // -2147483648L
nothrow @nogc @trusted 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 away from zero.
nothrow @nogc @trusted 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.
This function is Posix-Only.
nothrow @nogc @trusted real trunc(real x);
Returns the integer portion of x, dropping the fractional portion.
This is also known as "chop" rounding.
nothrow @nogc @trusted real remainder(real x, real y);
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
remquo and remainder not supported on Windows.
struct IeeeFlags;
IEEE exception status flags ('sticky bits')
These flags indicate that an exceptional floating-point condition has occurred. They indicate that a NaN or an infinity has been generated, that a result is inexact, or that a signalling NaN has been encountered. If floating-point exceptions are enabled (unmasked), a hardware exception will be generated instead of setting these flags.
Examples:
static void func() {
    int a = 10 * 10;
}

real a=3.5;
// Set all the flags to zero
resetIeeeFlags();
assert(!ieeeFlags.divByZero);
// Perform a division by zero.
a/=0.0L;
writeln(a); // real.infinity
assert(ieeeFlags.divByZero);
// Create a NaN
a*=0.0L;
assert(ieeeFlags.invalid);
assert(isNaN(a));

// Check that calling func() has no effect on the
// status flags.
IeeeFlags f = ieeeFlags;
func();
writeln(ieeeFlags); // f
const @property bool inexact();
The result cannot be represented exactly, so rounding occurred.

Example x = sin(0.1);

const @property bool underflow();
A zero was generated by underflow

Example x = real.min*real.epsilon/2;

const @property bool overflow();
An infinity was generated by overflow

Example x = real.max*2;

const @property bool divByZero();
An infinity was generated by division by zero

Example x = 3/0.0;

const @property bool invalid();
A machine NaN was generated.

Example x = real.infinity * 0.0;

@nogc void resetIeeeFlags();
Set all of the floating-point status flags to false.
@property IeeeFlags ieeeFlags();
Returns:
snapshot of the current state of the floating-point status flags
struct FloatingPointControl;
Control the Floating point hardware
Change the IEEE754 floating-point rounding mode and the floating-point hardware exceptions.
By default, the rounding mode is roundToNearest and all hardware exceptions are disabled. For most applications, debugging is easier if the division by zero, overflow, and invalid operation exceptions are enabled. These three are combined into a severeExceptions value for convenience. Note in particular that if invalidException is enabled, a hardware trap will be generated whenever an uninitialized floating-point variable is used.
All changes are temporary. The previous state is restored at the end of the scope.

Example

{
    FloatingPointControl fpctrl;

    // Enable hardware exceptions for division by zero, overflow to infinity,
    // invalid operations, and uninitialized floating-point variables.
    fpctrl.enableExceptions(FloatingPointControl.severeExceptions);

    // This will generate a hardware exception, if x is a
    // default-initialized floating point variable:
    real x; // Add `= 0` or even `= real.nan` to not throw the exception.
    real y = x * 3.0;

    // The exception is only thrown for default-uninitialized NaN-s.
    // NaN-s with other payload are valid:
    real z = y * real.nan; // ok

    // Changing the rounding mode:
    fpctrl.rounding = FloatingPointControl.roundUp;
    assert(rint(1.1) == 2);

    // The set hardware exceptions will be disabled when leaving this scope.
    // The original rounding mode will also be restored.
}

// Ensure previous values are returned:
assert(!FloatingPointControl.enabledExceptions);
assert(FloatingPointControl.rounding == FloatingPointControl.roundToNearest);
assert(rint(1.1) == 1);

alias RoundingMode = uint;
roundToNearest

roundDown

roundUp

roundToZero
IEEE rounding modes. The default mode is roundToNearest.
@nogc @property void rounding(RoundingMode newMode);
Change the floating-point hardware rounding mode
static @nogc @property RoundingMode rounding();
Returns:
the currently active rounding mode
subnormalException

inexactException

underflowException

overflowException

divByZeroException

invalidException

severeExceptions

allExceptions
IEEE hardware exceptions. By default, all exceptions are masked (disabled).
severeExceptions = The overflow, division by zero, and invalid exceptions.
static nothrow @nogc @property @safe bool hasExceptionTraps();
Returns:
true if the current FPU supports exception trapping
@nogc void enableExceptions(uint exceptions);
Enable (unmask) specific hardware exceptions. Multiple exceptions may be ORed together.
@nogc void disableExceptions(uint exceptions);
Disable (mask) specific hardware exceptions. Multiple exceptions may be ORed together.
static @nogc @property uint enabledExceptions();
Returns:
the exceptions which are currently enabled (unmasked)
pure nothrow @nogc @trusted bool isNaN(X)(X x)
if (isFloatingPoint!X);
Determines if x is NaN.
Parameters:
X x a floating point number.
Returns:
true if x is Nan.
Examples:
assert( isNaN(float.init));
assert( isNaN(-double.init));
assert( isNaN(real.nan));
assert( isNaN(-real.nan));
assert(!isNaN(cast(float) 53.6));
assert(!isNaN(cast(real)-53.6));
pure nothrow @nogc @trusted bool isFinite(X)(X x);
Determines if x is finite.
Parameters:
X x a floating point number.
Returns:
true if x is finite.
Examples:
assert( isFinite(1.23f));
assert( isFinite(float.max));
assert( isFinite(float.min_normal));
assert(!isFinite(float.nan));
assert(!isFinite(float.infinity));
pure nothrow @nogc @trusted bool isNormal(X)(X x);
Determines if x is normalized.
A normalized number must not be zero, subnormal, infinite nor NAN.
Parameters:
X x a floating point number.
Returns:
true if x is normalized.
Examples:
float f = 3;
double d = 500;
real e = 10e+48;

assert(isNormal(f));
assert(isNormal(d));
assert(isNormal(e));
f = d = e = 0;
assert(!isNormal(f));
assert(!isNormal(d));
assert(!isNormal(e));
assert(!isNormal(real.infinity));
assert(isNormal(-real.max));
assert(!isNormal(real.min_normal/4));
pure nothrow @nogc @trusted bool isSubnormal(X)(X x);
Determines if x is subnormal.
Subnormals (also known as "denormal number"), have a 0 exponent and a 0 most significant mantissa bit.
Parameters:
X x a floating point number.
Returns:
true if x is a denormal number.
Examples:
import std.meta : AliasSeq;

foreach (T; AliasSeq!(float, double, real))
{
    T f;
    for (f = 1.0; !isSubnormal(f); f /= 2)
        assert(f != 0);
}
pure nothrow @nogc @trusted bool isInfinity(X)(X x)
if (isFloatingPoint!X);
Determines if x is ±∞.
Parameters:
X x a floating point number.
Returns:
true if x is ±∞.
Examples:
assert(!isInfinity(float.init));
assert(!isInfinity(-float.init));
assert(!isInfinity(float.nan));
assert(!isInfinity(-float.nan));
assert(isInfinity(float.infinity));
assert(isInfinity(-float.infinity));
assert(isInfinity(-1.0f / 0.0f));
pure nothrow @nogc @trusted 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'.
pure nothrow @nogc @trusted int signbit(X)(X x);
Return 1 if sign bit of e is set, 0 if not.
Examples:
assert(!signbit(float.nan));
assert(signbit(-float.nan));
assert(!signbit(168.1234f));
assert(signbit(-168.1234f));
assert(!signbit(0.0f));
assert(signbit(-0.0f));
assert(signbit(-float.max));
assert(!signbit(float.max));

assert(!signbit(double.nan));
assert(signbit(-double.nan));
assert(!signbit(168.1234));
assert(signbit(-168.1234));
assert(!signbit(0.0));
assert(signbit(-0.0));
assert(signbit(-double.max));
assert(!signbit(double.max));

assert(!signbit(real.nan));
assert(signbit(-real.nan));
assert(!signbit(168.1234L));
assert(signbit(-168.1234L));
assert(!signbit(0.0L));
assert(signbit(-0.0L));
assert(signbit(-real.max));
assert(!signbit(real.max));
pure nothrow @nogc @trusted R copysign(R, X)(R to, X from)
if (isFloatingPoint!R && isFloatingPoint!X);
Return a value composed of to with from's sign bit.
pure nothrow @nogc @safe F sgn(F)(F x);
Returns -1 if x < 0, x if x == 0, 1 if x > 0, and NAN if x==NAN.
Examples:
writeln(sgn(168.1234)); // 1
writeln(sgn(-168.1234)); // -1
writeln(sgn(0.0)); // 0
writeln(sgn(-0.0)); // 0
pure nothrow @nogc @trusted real NaN(ulong payload);
Create a quiet NAN, storing an integer inside the payload.
For floats, the largest possible payload is 0x3F_FFFF. For doubles, it is 0x3_FFFF_FFFF_FFFF. For 80-bit or 128-bit reals, it is 0x3FFF_FFFF_FFFF_FFFF.
pure nothrow @nogc @trusted ulong getNaNPayload(real x);
Extract an integral payload from a NAN.
Returns:
the integer payload as a ulong.
For floats, the largest possible payload is 0x3F_FFFF. For doubles, it is 0x3_FFFF_FFFF_FFFF. For 80-bit or 128-bit reals, it is 0x3FFF_FFFF_FFFF_FFFF.
pure nothrow @nogc @trusted real nextUp(real x);

pure nothrow @nogc @trusted double nextUp(double x);

pure nothrow @nogc @trusted 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_normal*real.epsilon
real.max
NAN NAN
pure nothrow @nogc @safe real nextDown(real x);

pure nothrow @nogc @safe double nextDown(double x);

pure nothrow @nogc @safe 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_normal*real.epsilon
-real.max -∞
-∞ -∞
NAN NAN
Examples:
writeln(nextDown(1.0 + real.epsilon)); // 1.0
pure nothrow @nogc @safe T nextafter(T)(const T x, const T 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.

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.

Examples:
float a = 1;
assert(is(typeof(nextafter(a, a)) == float));
assert(nextafter(a, a.infinity) > a);

double b = 2;
assert(is(typeof(nextafter(b, b)) == double));
assert(nextafter(b, b.infinity) > b);

real c = 3;
assert(is(typeof(nextafter(c, c)) == real));
assert(nextafter(c, c.infinity) > c);
pure nothrow @nogc @safe 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
pure nothrow @nogc @safe real fmax(real x, real y);
Returns the larger of x and y.
pure nothrow @nogc @safe real fmin(real x, real y);
Returns the smaller of x and y.
pure nothrow @nogc @safe 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.
pure nothrow @nogc @trusted Unqual!F pow(F, G)(F x, G n)
if (isFloatingPoint!F && isIntegral!G);
Compute the value of x n, where n is an integer
pure nothrow @nogc @trusted typeof(Unqual!F.init * Unqual!G.init) pow(F, G)(F x, G n)
if (isIntegral!F && isIntegral!G);
Compute the value of an integer x, raised to the power of a positive integer n.
If both x and n are 0, the result is 1. If n is negative, an integer divide error will occur at runtime, regardless of the value of x.
Examples:
immutable int one = 1;
immutable byte two = 2;
immutable ubyte three = 3;
immutable short four = 4;
immutable long ten = 10;

writeln(pow(two, three)); // 8
writeln(pow(two, ten)); // 1024
writeln(pow(one, ten)); // 1
writeln(pow(ten, four)); // 10_000
writeln(pow(four, 10)); // 1_048_576
writeln(pow(three, four)); // 81
pure nothrow @nogc @trusted real pow(I, F)(I x, F y)
if (isIntegral!I && isFloatingPoint!F);
Computes integer to floating point powers.
pure nothrow @nogc @trusted Unqual!(Largest!(F, G)) pow(F, G)(F x, G y)
if (isFloatingPoint!F && isFloatingPoint!G);
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
pure nothrow @nogc @trusted int feqrel(X)(const X x, const X y)
if (isFloatingPoint!X);
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
pure nothrow @nogc @trusted Unqual!(CommonType!(T1, T2)) poly(T1, T2)(T1 x, in T2[] A)
if (isFloatingPoint!T1 && isFloatingPoint!T2);
Evaluate polynomial A(x) = a0 + a1x + a2x2 + a3x3; ...
Uses Horner's rule A(x) = a0 + x(a1 + x(a2 + x(a3 + ...)))
Parameters:
T1 x the value to evaluate.
T2[] A array of coefficients a0, a1, etc.
Examples:
real x = 3.1;
static real[] pp = [56.1, 32.7, 6];

writeln(poly(x, pp)); // (56.1L + (32.7L + 6.0L * x) * x)
bool approxEqual(T, U, V)(T lhs, U rhs, V maxRelDiff, V maxAbsDiff = 1e-05);
Computes whether two values are approximately equal, admitting a maximum relative difference, and a maximum absolute difference.
Parameters:
T lhs First item to compare.
U rhs Second item to compare.
V maxRelDiff Maximum allowable difference relative to rhs.
V maxAbsDiff Maximum absolute difference.
Returns:
true if the two items are approximately equal under either criterium. If one item is a range, and the other is a single value, then the result is the logical and-ing of calling approxEqual on each element of the ranged item against the single item. If both items are ranges, then approxEqual returns true if and only if the ranges have the same number of elements and if approxEqual evaluates to true for each pair of elements.
bool approxEqual(T, U)(T lhs, U rhs);
Returns approxEqual(lhs, rhs, 1e-2, 1e-5).
Examples:
assert(approxEqual(1.0, 1.0099));
assert(!approxEqual(1.0, 1.011));
float[] arr1 = [ 1.0, 2.0, 3.0 ];
double[] arr2 = [ 1.001, 1.999, 3 ];
assert(approxEqual(arr1, arr2));

real num = real.infinity;
assert(num == real.infinity);  // Passes.
assert(approxEqual(num, real.infinity));  // Fails.
num = -real.infinity;
assert(num == -real.infinity);  // Passes.
assert(approxEqual(num, -real.infinity));  // Fails.

assert(!approxEqual(3, 0));
assert(approxEqual(3, 3));
assert(approxEqual(3.0, 3));
assert(approxEqual([3, 3, 3], 3.0));
assert(approxEqual([3.0, 3.0, 3.0], 3));
int a = 10;
assert(approxEqual(10, a));
pure nothrow @nogc @trusted int cmp(T)(const(T) x, const(T) y)
if (isFloatingPoint!T);
Defines a total order on all floating-point numbers.
The order is defined as follows:
  • All numbers in [-∞, +∞] are ordered the same way as by built-in comparison, with the exception of -0.0, which is less than +0.0;
  • If the sign bit is set (that is, it's 'negative'), NAN is less than any number; if the sign bit is not set (it is 'positive'), NAN is greater than any number;
  • NANs of the same sign are ordered by the payload ('negative' ones - in reverse order).
Returns:
negative value if x precedes y in the order specified above; 0 if x and y are identical, and positive value otherwise.
See Also:
Standards:
Conforms to IEEE 754-2008
Examples:
Most numbers are ordered naturally.
assert(cmp(-double.infinity, -double.max) < 0);
assert(cmp(-double.max, -100.0) < 0);
assert(cmp(-100.0, -0.5) < 0);
assert(cmp(-0.5, 0.0) < 0);
assert(cmp(0.0, 0.5) < 0);
assert(cmp(0.5, 100.0) < 0);
assert(cmp(100.0, double.max) < 0);
assert(cmp(double.max, double.infinity) < 0);

writeln(cmp(1.0, 1.0)); // 0
Examples:
Positive and negative zeroes are distinct.
assert(cmp(-0.0, +0.0) < 0);
assert(cmp(+0.0, -0.0) > 0);
Examples:
Depending on the sign, NANs go to either end of the spectrum.
assert(cmp(-double.nan, -double.infinity) < 0);
assert(cmp(double.infinity, double.nan) < 0);
assert(cmp(-double.nan, double.nan) < 0);
Examples:
NANs of the same sign are ordered by the payload.
assert(cmp(NaN(10), NaN(20)) < 0);
assert(cmp(-NaN(20), -NaN(10)) < 0);
T nextPow2(T)(const T val)
if (isIntegral!T);

T nextPow2(T)(const T val)
if (isFloatingPoint!T);
Gives the next power of two after val. T can be any built-in numerical type.
If the operation would lead to an over/underflow, this function will return 0.
Parameters:
T val any number
Returns:
the next power of two after val
Examples:
writeln(nextPow2(2)); // 4
writeln(nextPow2(10)); // 16
writeln(nextPow2(4000)); // 4096

writeln(nextPow2(-2)); // -4
writeln(nextPow2(-10)); // -16

writeln(nextPow2(uint.max)); // 0
writeln(nextPow2(uint.min)); // 0
writeln(nextPow2(size_t.max)); // 0
writeln(nextPow2(size_t.min)); // 0

writeln(nextPow2(int.max)); // 0
writeln(nextPow2(int.min)); // 0
writeln(nextPow2(long.max)); // 0
writeln(nextPow2(long.min)); // 0
Examples:
writeln(nextPow2(2.1)); // 4.0
writeln(nextPow2(-2.0)); // -4.0
writeln(nextPow2(0.25)); // 0.5
writeln(nextPow2(-4.0)); // -8.0

writeln(nextPow2(double.max)); // 0.0
writeln(nextPow2(double.infinity)); // double.infinity
T truncPow2(T)(const T val)
if (isIntegral!T);

T truncPow2(T)(const T val)
if (isFloatingPoint!T);
Gives the last power of two before val. <> can be any built-in numerical type.
Parameters:
T val any number
Returns:
the last power of two before val
Examples:
writeln(truncPow2(3)); // 2
writeln(truncPow2(4)); // 4
writeln(truncPow2(10)); // 8
writeln(truncPow2(4000)); // 2048

writeln(truncPow2(-5)); // -4
writeln(truncPow2(-20)); // -16

writeln(truncPow2(uint.max)); // int.max + 1
writeln(truncPow2(uint.min)); // 0
writeln(truncPow2(ulong.max)); // long.max + 1
writeln(truncPow2(ulong.min)); // 0

writeln(truncPow2(int.max)); // (int.max / 2) + 1
writeln(truncPow2(int.min)); // int.min
writeln(truncPow2(long.max)); // (long.max / 2) + 1
writeln(truncPow2(long.min)); // long.min
Examples:
writeln(truncPow2(2.1)); // 2.0
writeln(truncPow2(7.0)); // 4.0
writeln(truncPow2(-1.9)); // -1.0
writeln(truncPow2(0.24)); // 0.125
writeln(truncPow2(-7.0)); // -4.0

writeln(truncPow2(double.infinity)); // double.infinity
pure nothrow @nogc @safe bool isPowerOf2(X)(const X x)
if (isNumeric!X);
Check whether a number is an integer power of two.
Note that only positive numbers can be integer powers of two. This function always return false if x is negative or zero.
Parameters:
X x the number to test
Returns:
true if x is an integer power of two.
Examples:
assert( isPowerOf2(1.0L));
assert( isPowerOf2(2.0L));
assert( isPowerOf2(0.5L));
assert( isPowerOf2(pow(2.0L, 96)));
assert( isPowerOf2(pow(2.0L, -77)));

assert(!isPowerOf2(-2.0L));
assert(!isPowerOf2(-0.5L));
assert(!isPowerOf2(0.0L));
assert(!isPowerOf2(4.315));
assert(!isPowerOf2(1.0L / 3.0L));

assert(!isPowerOf2(real.nan));
assert(!isPowerOf2(real.infinity));
Examples:
assert( isPowerOf2(1));
assert( isPowerOf2(2));
assert( isPowerOf2(1uL << 63));

assert(!isPowerOf2(-4));
assert(!isPowerOf2(0));
assert(!isPowerOf2(1337u));