Search
Report a bug
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.traits

This is a submodule of std.math.
It contains several functions for introspection on numerical values.
Authors:
Walter Bright, Don Clugston, Conversion of CEPHES math library to D by Iain Buclaw and David Nadlinger
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;

static 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?
Examples:
```assert( isIdentical(0.0, 0.0));
assert( isIdentical(1.0, 1.0));
assert( isIdentical(real.infinity, real.infinity));
assert( isIdentical(-real.infinity, -real.infinity));

assert(!isIdentical(0.0, -0.0));
assert(!isIdentical(real.nan, -real.nan));
assert(!isIdentical(real.infinity, -real.infinity));
```
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);

pure nothrow @nogc @trusted R `copysign`(R, X)(X `to`, R `from`)
if (isIntegral!X && isFloatingPoint!R);
Parameters:
 R `to` the numeric value to use X `from` the sign value to use
Returns:
a value composed of to with from's sign bit.
Examples:
```writeln(copysign(1.0, 1.0)); // 1.0
writeln(copysign(1.0, -0.0)); // -1.0
writeln(copysign(1UL, -1.0)); // -1.0
writeln(copysign(-1.0, -1.0)); // -1.0

writeln(copysign(real.infinity, -1.0)); // -real.infinity
assert(copysign(real.nan, 1.0) is real.nan);
assert(copysign(-real.nan, 1.0) is real.nan);
assert(copysign(real.nan, -1.0) is -real.nan);
```
pure nothrow @nogc @safe F `sgn`(F)(F `x`)
if (isFloatingPoint!F || isIntegral!F);
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 @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:
```import std.math.exponential : pow;

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