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

This is a submodule of std.math.
It contains several exponential and logarithm functions.
Authors:
Walter Bright, Don Clugston, Conversion of CEPHES math library to D by Iain Buclaw and David Nadlinger
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
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 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
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 ex.
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 2x.
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*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:
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 * 2exp

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