std.math.exponential

pure nothrow @nogc @trusted Unqual!F pow(F, G)(F x, G n)
if (isFloatingPoint!F && isIntegral!G);

Compute the value of x ⁿ, where n is an integer

Examples:

import std.math.operations : feqrel;

writeln(pow(2.0, 5)); // 32.0
assert(pow(1.5, 9).feqrel(38.4433) > 16);
assert(pow(real.nan, 2) is real.nan);
writeln(pow(real.infinity, 2)); // real.infinity

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 power of two integral numbers.

Parameters:

F x	base
G n	exponent

Returns:

x raised to the power of n. If n is negative the result is 1 / pow(x, -n), which is calculated as integer division with remainder. This may result in a division by zero error.

If both x and n are 0, the result is 1.

Throws:

If x is 0 and n is negative, the result is the same as the result of a division by zero.

Examples:

writeln(pow(2, 3)); // 8
writeln(pow(3, 2)); // 9

writeln(pow(2, 10)); // 1_024
writeln(pow(2, 20)); // 1_048_576
writeln(pow(2, 30)); // 1_073_741_824

writeln(pow(0, 0)); // 1

writeln(pow(1, -5)); // 1
writeln(pow(1, -6)); // 1
writeln(pow(-1, -5)); // -1
writeln(pow(-1, -6)); // 1

writeln(pow(-2, 5)); // -32
writeln(pow(-2, -5)); // 0
writeln(pow(cast(double)-2, -5)); // -0.03125

pure nothrow @nogc @trusted real pow(I, F)(I x, F y)
if (isIntegral!I && isFloatingPoint!F);

Computes integer to floating point powers.

Examples:

writeln(pow(2, 5.0)); // 32.0
writeln(pow(7, 3.0)); // 343.0
assert(pow(2, real.nan) is real.nan);
writeln(pow(2, real.infinity)); // real.infinity

pure nothrow @nogc @trusted Unqual!(Largest!(F, G)) pow(F, G)(F x, G y)
if (isFloatingPoint!F && isFloatingPoint!G);

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

Examples:

import std.math.operations : isClose;

assert(isClose(pow(2.0, 3.0), 8.0));
assert(isClose(pow(1.5, 10.0), 57.6650390625));

// square root of 9
assert(isClose(pow(9.0, 0.5), 3.0));
// 10th root of 1024
assert(isClose(pow(1024.0, 0.1), 2.0));

assert(isClose(pow(-4.0, 3.0), -64.0));

// reciprocal of 4 ^^ 2
assert(isClose(pow(4.0, -2.0), 0.0625));
// reciprocal of (-2) ^^ 3
assert(isClose(pow(-2.0, -3.0), -0.125));

assert(isClose(pow(-2.5, 3.0), -15.625));
// reciprocal of 2.5 ^^ 3
assert(isClose(pow(2.5, -3.0), 0.064));
// reciprocal of (-2.5) ^^ 3
assert(isClose(pow(-2.5, -3.0), -0.064));

// reciprocal of square root of 4
assert(isClose(pow(4.0, -0.5), 0.5));

// per definition
assert(isClose(pow(0.0, 0.0), 1.0));

Examples:

import std.math.operations : isClose;

// the result is a complex number
// which cannot be represented as floating point number
import std.math.traits : isNaN;
assert(isNaN(pow(-2.5, -1.5)));

// use the ^^-operator of std.complex instead
import std.complex : complex;
auto c1 = complex(-2.5, 0.0);
auto c2 = complex(-1.5, 0.0);
auto result = c1 ^^ c2;
// exact result apparently depends on `real` precision => increased tolerance
assert(isClose(result.re, -4.64705438e-17, 2e-4));
assert(isClose(result.im, 2.52982e-1, 2e-4));

Unqual!(Largest!(F, H)) powmod(F, G, H)(F x, G n, H m)
if (isUnsigned!F && isUnsigned!G && isUnsigned!H);

Computes the value of a positive integer x, raised to the power n, modulo m.

Parameters:

F x	base
G n	exponent
H m	modulus

Returns:

x to the power n, modulo m. The return type is the largest of x's and m's type.

The function requires that all values have unsigned types.

Examples:

writeln(powmod(1U, 10U, 3U)); // 1
writeln(powmod(3U, 2U, 6U)); // 3
writeln(powmod(5U, 5U, 15U)); // 5
writeln(powmod(2U, 3U, 5U)); // 3
writeln(powmod(2U, 4U, 5U)); // 1
writeln(powmod(2U, 5U, 5U)); // 2

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 e^x.

Special Values

x	ex
+∞	+∞
-∞	+0.0
NAN	NAN

Examples:

import std.math.operations : feqrel;
import std.math.constants : E;

writeln(exp(0.0)); // 1.0
assert(exp(3.0).feqrel(E * E * E) > 16);

pure nothrow @nogc @trusted real expm1(real x);

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

pure nothrow @nogc @safe float expm1(float 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

Examples:

import std.math.traits : isIdentical;
import std.math.operations : feqrel;

assert(isIdentical(expm1(0.0), 0.0));
assert(expm1(1.0).feqrel(1.71828) > 16);
assert(expm1(2.0).feqrel(6.3890) > 16);

pure nothrow @nogc @trusted real exp2(real x);

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

pure nothrow @nogc @safe float exp2(float x);

Calculates 2^x.

Special Values

x	exp2(x)
+∞	+∞
-∞	+0.0
NAN	NAN

Examples:

import std.math.traits : isIdentical;
import std.math.operations : feqrel;

assert(isIdentical(exp2(0.0), 1.0));
assert(exp2(2.0).feqrel(4.0) > 16);
assert(exp2(8.0).feqrel(256.0) > 16);

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

Examples:

import std.math.operations : isClose;

int exp;
real mantissa = frexp(123.456L, exp);

assert(isClose(mantissa * pow(2.0L, cast(real) exp), 123.456L));

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

Examples:

writeln(ilogb(1)); // 0
writeln(ilogb(3)); // 1
writeln(ilogb(3.0)); // 1
writeln(ilogb(100_000_000)); // 26

writeln(ilogb(0)); // FP_ILOGB0
writeln(ilogb(0.0)); // FP_ILOGB0
writeln(ilogb(double.nan)); // FP_ILOGBNAN
writeln(ilogb(double.infinity)); // int.max

alias FP_ILOGB0 = core.stdc.math.FP_ILOGB0;

alias FP_ILOGBNAN = core.stdc.math.FP_ILOGBNAN;

Special return values of ilogb.

Examples:

writeln(ilogb(0)); // FP_ILOGB0
writeln(ilogb(0.0)); // FP_ILOGB0
writeln(ilogb(double.nan)); // FP_ILOGBNAN

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 * 2^exp

References frexp

Examples:

import std.meta : AliasSeq;
static 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:

import std.math.operations : feqrel;
import std.math.constants : E;

assert(feqrel(log(E), 1) >= real.mant_dig - 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:

import std.math.algebraic : fabs;

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

Examples:

import std.math.traits : isIdentical, isNaN;
import std.math.operations : feqrel;

assert(isIdentical(log1p(0.0), 0.0));
assert(log1p(1.0).feqrel(0.69314) > 16);

writeln(log1p(-1.0)); // -real.infinity
assert(isNaN(log1p(-2.0)));
assert(log1p(real.nan) is real.nan);
assert(log1p(-real.nan) is -real.nan);
writeln(log1p(real.infinity)); // real.infinity

pure nothrow @nogc @safe real log2(real x);

Calculates the base-2 logarithm of x: ⊂x

Special Values

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

Examples:

import std.math.operations : isClose;

assert(isClose(log2(1024.0L), 10));

pure nothrow @nogc @trusted real logb(real x);

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

pure nothrow @nogc @trusted float logb(float 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

Examples:

writeln(logb(1.0)); // 0
writeln(logb(100.0)); // 6

writeln(logb(0.0)); // -real.infinity
writeln(logb(real.infinity)); // real.infinity
writeln(logb(-real.infinity)); // real.infinity

pure nothrow @nogc @safe real scalbn(real x, int n);

pure nothrow @nogc @safe double scalbn(double x, int n);

pure nothrow @nogc @safe float scalbn(float x, int n);

Efficiently calculates x * 2ⁿ.

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(0x1.2345678abcdefp0L, 999)); // 0x1.2345678abcdefp999L
writeln(scalbn(-real.infinity, 5)); // -real.infinity
writeln(scalbn(2.0, 10)); // 2048.0
writeln(scalbn(2048.0f, -10)); // 2.0f