Menu

- Learn
- Documentation
  - Language Reference
  - Library Reference
  - Command-line Reference
  - Feature Overview
  - Articles
- Downloads
- Packages
- Community
  - Blog
  - Orgs using D
  - Twitter
  - Forums
  - IRC
  - Community Discord
  - Wiki
  - GitHub
  - Issues
  - Get involved
  - Contributors
  - Foundation
  - Security Team
  - Donate
  - Sponsors
- Resources
  - Tour
  - Books
  - Tutorials
  - Tools
  - Editors
  - IDEs
  - run.dlang.io
  - Visual D
  - Acknowledgments
  - D Style
  - Glossary
  - Sitemap

Search
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.
License:
Boost License 1.0.
Authors:
Walter Bright, Don Clugston, Conversion of CEPHES math library to D by Iain Buclaw and David Nadlinger

Source std/math/exponential.d

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`);
pure nothrow @nogc @safe double `log`(double `x`);
pure nothrow @nogc @safe float `log`(float `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

pure nothrow @nogc @safe real `log10`(real `x`);
pure nothrow @nogc @safe double `log10`(double `x`);
pure nothrow @nogc @safe float `log10`(float `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

pure nothrow @nogc @safe real `log1p`(real `x`);
pure nothrow @nogc @safe double `log1p`(double `x`);
pure nothrow @nogc @safe float `log1p`(float `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`);
pure nothrow @nogc @safe double `log2`(double `x`);
pure nothrow @nogc @safe float `log2`(float `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

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

Copyright © 1999-2023 by the D Language Foundation | Page generated by Ddoc on Wed Feb 1 17:27:39 2023