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