Menu

- Learn
- Documentation
  - Language Reference
  - Library Reference
  - Command-line Reference
  - Feature Overview
  - Articles
- Downloads
- Packages
- Community
  - Blog
  - Orgs using D
  - Twitter
  - Calendar
  - 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

Contains the elementary mathematical functions (powers, roots, and trigonometric functions), and low-level floating-point operations. Mathematical special functions are available in std.mathspecial.

Category | Members
--- | ---
Constants | E PI PI_2 PI_4 M_1_PI M_2_PI M_2_SQRTPI LN10 LN2 LOG2 LOG2E LOG2T LOG10E SQRT2 SQRT1_2
Classics | abs fabs sqrt cbrt hypot poly nextPow2 truncPow2
Trigonometry | sin cos tan asin acos atan atan2 sinh cosh tanh asinh acosh atanh
Rounding | ceil floor round lround trunc rint lrint nearbyint rndtol quantize
Exponentiation & Logarithms | pow exp exp2 expm1 ldexp frexp log log2 log10 logb ilogb log1p scalbn
Modulus | fmod modf remainder
Floating-point operations | approxEqual feqrel fdim fmax fmin fma isClose nextDown nextUp nextafter NaN getNaNPayload cmp
Introspection | isFinite isIdentical isInfinity isNaN isNormal isSubnormal signbit sgn copysign isPowerOf2
Hardware Control | IeeeFlags FloatingPointControl

The functionality closely follows the IEEE754-2008 standard for floating-point arithmetic, including the use of camelCase names rather than C99-style lower case names. All of these functions behave correctly when presented with an infinity or NaN.
The following IEEE 'real' formats are currently supported:

- 64 bit Big-endian 'double' (eg PowerPC)
- 128 bit Big-endian 'quadruple' (eg SPARC)
- 64 bit Little-endian 'double' (eg x86-SSE2)
- 80 bit Little-endian, with implied bit 'real80' (eg x87, Itanium)
- 128 bit Little-endian 'quadruple' (not implemented on any known processor!)
- Non-IEEE 128 bit Big-endian 'doubledouble' (eg PowerPC) has partial support

Unlike C, there is no global 'errno' variable. Consequently, almost all of these functions are pure nothrow.
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.d

enum real `E`;
  e = 2.718281...
enum real `LOG2T`;
  log210 = 3.321928...
enum real `LOG2E`;
  log2e = 1.442695...
enum real `LOG2`;
  log102 = 0.301029...
enum real `LOG10E`;
  log10e = 0.434294...
enum real `LN2`;
  ln 2 = 0.693147...
enum real `LN10`;
  ln 10 = 2.302585...
enum real `PI`;
  π = 3.141592...
enum real `PI_2`;
  π / 2 = 1.570796...
enum real `PI_4`;
  π / 4 = 0.785398...
enum real `M_1_PI`;
  1 / π = 0.318309...
enum real `M_2_PI`;
  2 / π = 0.636619...
enum real `M_2_SQRTPI`;
  2 / √π = 1.128379...
enum real `SQRT2`;
  √2 = 1.414213...
enum real `SQRT1_2`;
  √½ = 0.707106...
pure nothrow @nogc auto `abs`(Num)(Num `x`)
if (is(immutable(Num) == immutable(short)) || is(immutable(Num) == immutable(byte)) || is(typeof(Num.init >= 0)) && is(typeof(-Num.init)));
  Calculates the absolute value of a number.
  Parameters:

  Num | (template parameter) type of number
  Num `x` | real number value

  Returns:
  The absolute value of the number. If floating-point or integral, the return type will be the same as the input.

  Limitations Does not work correctly for signed intergal types and value Num.min.

  Examples:
  ditto

      assert(isIdentical(abs(-0.0L), 0.0L));
      assert(isNaN(abs(real.nan)));
      writeln(abs(-real.infinity)); // real.infinity
      writeln(abs(-56)); // 56
      writeln(abs(2321312L)); // 2321312L

pure nothrow @nogc @safe real `cos`(real `x`);
pure nothrow @nogc @safe double `cos`(double `x`);
pure nothrow @nogc @safe float `cos`(float `x`);
  Returns cosine of x. x is in radians.

  Special Values
  x | cos(x) | invalid?
  --- | --- | ---
  NAN | NAN | yes
  ±∞ | NAN | yes

  Bugs:
  Results are undefined if |x| >= 264.
  Examples:

      writeln(cos(0.0)); // 1.0
      assert(cos(1.0).approxEqual(0.540));
      assert(cos(3.0).approxEqual(-0.989));

pure nothrow @nogc @safe real `sin`(real `x`);
pure nothrow @nogc @safe double `sin`(double `x`);
pure nothrow @nogc @safe float `sin`(float `x`);
  Returns sine of x. x is in radians.

  Special Values
  x | sin(x) | invalid?
  --- | --- | ---
  NAN | NAN | yes
  ±0.0 | ±0.0 | no
  ±∞ | NAN | yes

  Parameters:

  real `x` | angle in radians (not degrees)

  Returns:
  sine of x
  See Also:
  cos , tan , asin
  Bugs:
  Results are undefined if |x| >= 264.
  Examples:

      import std.math : sin, PI;
      import std.stdio : writefln;

      void someFunc()
      {
        real x = 30.0;
        auto result = sin(x * (PI / 180)); // convert degrees to radians
        writefln("The sine of %s degrees is %s", x, result);
      }

pure nothrow @nogc @trusted real `tan`(real `x`);
pure nothrow @nogc @safe double `tan`(double `x`);
pure nothrow @nogc @safe float `tan`(float `x`);
  Returns tangent of x. x is in radians.

  Special Values
  x | tan(x) | invalid?
  --- | --- | ---
  NAN | NAN | yes
  ±0.0 | ±0.0 | no
  ±∞ | NAN | yes

  Examples:

      assert(isIdentical(tan(0.0), 0.0));
      assert(tan(PI).approxEqual(0));
      assert(tan(PI / 3).approxEqual(sqrt(3.0)));

pure nothrow @nogc @safe real `acos`(real `x`);
pure nothrow @nogc @safe double `acos`(double `x`);
pure nothrow @nogc @safe float `acos`(float `x`);
  Calculates the arc cosine of x, returning a value ranging from 0 to π.

  Special Values
  x | acos(x) | invalid?
  --- | --- | ---
  >1.0 | NAN | yes
  <-1.0 | NAN | yes
  NAN | NAN | yes

  Examples:

      assert(acos(0.0).approxEqual(1.570));
      assert(acos(0.5).approxEqual(std.math.PI / 3));
      assert(acos(PI).isNaN);

pure nothrow @nogc @safe real `asin`(real `x`);
pure nothrow @nogc @safe double `asin`(double `x`);
pure nothrow @nogc @safe float `asin`(float `x`);
  Calculates the arc sine of x, returning a value ranging from -π/2 to π/2.

  Special Values
  x | asin(x) | invalid?
  --- | --- | ---
  ±0.0 | ±0.0 | no
  >1.0 | NAN | yes
  <-1.0 | NAN | yes

  Examples:

      assert(isIdentical(asin(0.0), 0.0));
      assert(asin(0.5).approxEqual(PI / 6));
      assert(asin(PI).isNaN);

pure nothrow @nogc @safe real `atan`(real `x`);
pure nothrow @nogc @safe double `atan`(double `x`);
pure nothrow @nogc @safe float `atan`(float `x`);
  Calculates the arc tangent of x, returning a value ranging from -π/2 to π/2.

  Special Values
  x | atan(x) | invalid?
  --- | --- | ---
  ±0.0 | ±0.0 | no
  ±∞ | NAN | yes

  Examples:

      assert(isIdentical(atan(0.0), 0.0));
      assert(atan(sqrt(3.0)).approxEqual(PI / 3));

pure nothrow @nogc @trusted real `atan2`(real `y`, real `x`);
pure nothrow @nogc @safe double `atan2`(double `y`, double `x`);
pure nothrow @nogc @safe float `atan2`(float `y`, float `x`);
  Calculates the arc tangent of y / x, returning a value ranging from -π to π.

  Special Values
  y | x | atan(y, x)
  --- | --- | ---
  NAN | anything | NAN
  anything | NAN | NAN
  ±0.0 | >0.0 | ±0.0
  ±0.0 | +0.0 | ±0.0
  ±0.0 | <0.0 | ±π
  ±0.0 | -0.0 | ±π
  >0.0 | ±0.0 | π/2
  <0.0 | ±0.0 | -π/2
  >0.0 | ∞ | ±0.0
  ±∞ | anything | ±π/2
  >0.0 | -∞ | ±π
  ±∞ | ∞ | ±π/4
  ±∞ | -∞ | ±3π/4

  Examples:

      assert(atan2(1.0, sqrt(3.0)).approxEqual(PI / 6));

pure nothrow @nogc @safe real `cosh`(real `x`);
pure nothrow @nogc @safe double `cosh`(double `x`);
pure nothrow @nogc @safe float `cosh`(float `x`);
  Calculates the hyperbolic cosine of x.

  Special Values
  x | cosh(x) | invalid?
  --- | --- | ---
  ±∞ | ±0.0 | no

  Examples:

      writeln(cosh(0.0)); // 1.0
      assert(cosh(1.0).approxEqual((E + 1.0 / E) / 2));

pure nothrow @nogc @safe real `sinh`(real `x`);
pure nothrow @nogc @safe double `sinh`(double `x`);
pure nothrow @nogc @safe float `sinh`(float `x`);
  Calculates the hyperbolic sine of x.

  Special Values
  x | sinh(x) | invalid?
  --- | --- | ---
  ±0.0 | ±0.0 | no
  ±∞ | ±∞ | no

  Examples:

      assert(isIdentical(sinh(0.0), 0.0));
      assert(sinh(1.0).approxEqual((E - 1.0 / E) / 2));

pure nothrow @nogc @safe real `tanh`(real `x`);
pure nothrow @nogc @safe double `tanh`(double `x`);
pure nothrow @nogc @safe float `tanh`(float `x`);
  Calculates the hyperbolic tangent of x.

  Special Values
  x | tanh(x) | invalid?
  --- | --- | ---
  ±0.0 | ±0.0 | no
  ±∞ | ±1.0 | no

  Examples:

      assert(isIdentical(tanh(0.0), 0.0));
      assert(tanh(1.0).approxEqual(sinh(1.0) / cosh(1.0)));

pure nothrow @nogc @safe real `acosh`(real `x`);
pure nothrow @nogc @safe double `acosh`(double `x`);
pure nothrow @nogc @safe float `acosh`(float `x`);
  Calculates the inverse hyperbolic cosine of x.
  Mathematically, acosh(x) = log(x + sqrt( x*x - 1))

  Domain X | Range Y
  --- | ---
  1..∞ | 0..∞

  Special Values
  x | acosh(x)
  --- | ---
  NAN | NAN
  <1 | NAN
  1 | 0
  +∞ | +∞

  Examples:

      assert(isNaN(acosh(0.9)));
      assert(isNaN(acosh(real.nan)));
      assert(isIdentical(acosh(1.0), 0.0));
      writeln(acosh(real.infinity)); // real.infinity
      assert(isNaN(acosh(0.5)));

pure nothrow @nogc @safe real `asinh`(real `x`);
pure nothrow @nogc @safe double `asinh`(double `x`);
pure nothrow @nogc @safe float `asinh`(float `x`);
  Calculates the inverse hyperbolic sine of x.
  Mathematically,

      asinh(x) =  log( x + sqrt( x*x + 1 )) // if x >= +0
      asinh(x) = -log(-x + sqrt( x*x + 1 )) // if x <= -0

  Special Values
  x | asinh(x)
  --- | ---
  NAN | NAN
  ±0 | ±0
  ±∞ | ±∞

  Examples:

      assert(isIdentical(asinh(0.0), 0.0));
      assert(isIdentical(asinh(-0.0), -0.0));
      writeln(asinh(real.infinity)); // real.infinity
      writeln(asinh(-real.infinity)); // -real.infinity
      assert(isNaN(asinh(real.nan)));

pure nothrow @nogc @safe real `atanh`(real `x`);
pure nothrow @nogc @safe double `atanh`(double `x`);
pure nothrow @nogc @safe float `atanh`(float `x`);
  Calculates the inverse hyperbolic tangent of x, returning a value from ranging from -1 to 1.
  Mathematically, atanh(x) = log( (1+x)/(1-x) ) / 2

  Domain X | Range Y
  --- | ---
  -∞..∞ | -1 .. 1

  Special Values
  x | acosh(x)
  --- | ---
  NAN | NAN
  ±0 | ±0
  -∞ | -0

  Examples:

      assert(isIdentical(atanh(0.0), 0.0));
      assert(isIdentical(atanh(-0.0),-0.0));
      assert(isNaN(atanh(real.nan)));
      assert(isNaN(atanh(-real.infinity)));
      writeln(atanh(0.0)); // 0

pure nothrow @nogc @safe long `rndtol`(real `x`);
pure nothrow @nogc @safe long `rndtol`(double `x`);
pure nothrow @nogc @safe long `rndtol`(float `x`);
  Returns x rounded to a long value using the current rounding mode. If the integer value of x is greater than long.max, the result is indeterminate.
  Examples:

      writeln(rndtol(1.0)); // 1L
      writeln(rndtol(1.2)); // 1L
      writeln(rndtol(1.7)); // 2L
      writeln(rndtol(1.0001)); // 1L

deprecated real `rndtonl`(real `x`);
  Deprecated. Please use round instead.
  Returns `x` rounded to a long value using the FE_TONEAREST rounding mode. If the integer value of `x` is greater than long.max, the result is indeterminate.
  Only works with the Digital Mars C Runtime.
  Parameters:

  real `x` | the number to round

  Returns:
  `x` rounded to an integer value
  Examples:

      version (CRuntime_DigitalMars)
      {
          assert(rndtonl(1.0) is -real.nan);
          assert(rndtonl(1.2) is -real.nan);
          assert(rndtonl(1.7) is -real.nan);
          assert(rndtonl(1.0001) is -real.nan);
      }

pure nothrow @nogc @safe float `sqrt`(float `x`);
pure nothrow @nogc @safe double `sqrt`(double `x`);
pure nothrow @nogc @safe real `sqrt`(real `x`);
  Compute square root of x.

  Special Values
  x | sqrt(x) | invalid?
  --- | --- | ---
  -0.0 | -0.0 | no
  <0.0 | NAN | yes
  +∞ | +∞ | no

  Examples:

      assert(sqrt(2.0).feqrel(1.4142) > 16);
      assert(sqrt(9.0).feqrel(3.0) > 16);

      assert(isNaN(sqrt(-1.0f)));
      assert(isNaN(sqrt(-1.0)));
      assert(isNaN(sqrt(-1.0L)));

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:

      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:

      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:

      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:

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

      assert(approxEqual(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:

      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:

      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:

      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: log2x

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

  Examples:

      assert(approxEqual(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

nothrow @nogc @trusted real `fmod`(real `x`, real `y`);
  Calculates the remainder from the calculation x/y.
  Returns:
  The value of x - i * y, where i is the number of times that y can be completely subtracted from x. The result has the same sign as x.

  Special Values
  x | y | fmod(x, y) | invalid?
  --- | --- | --- | ---
  ±0.0 | not 0.0 | ±0.0 | no
  ±∞ | anything | NAN | yes
  anything | ±0.0 | NAN | yes
  !=±∞ | ±∞ | x | no

  Examples:

      assert(isIdentical(fmod(0.0, 1.0), 0.0));
      assert(fmod(5.0, 3.0).feqrel(2.0) > 16);
      assert(isNaN(fmod(5.0, 0.0)));

nothrow @nogc @trusted real `modf`(real `x`, ref real `i`);
  Breaks x into an integral part and a fractional part, each of which has the same sign as x. The integral part is stored in i.
  Returns:
  The fractional part of x.

  Special Values
  x | i (on input) | modf(x, i) | i (on return)
  --- | --- | --- | ---
  ±∞ | anything | ±0.0 | ±∞

  Examples:

      real frac;
      real intpart;

      frac = modf(3.14159, intpart);
      assert(intpart.feqrel(3.0) > 16);
      assert(frac.feqrel(0.14159) > 16);

pure nothrow @nogc @safe real `scalbn`(real `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.2345678abcdefp0, 999)); // 0x1.2345678abcdefp999
      writeln(scalbn(-real.infinity, 5)); // -real.infinity

nothrow @nogc @trusted real `cbrt`(real `x`);
  Calculates the cube root of x.

  Special Values
  x | cbrt(x) | invalid?
  --- | --- | ---
  ±0.0 | ±0.0 | no
  NAN | NAN | yes
  ±∞ | ±∞ | no

  Examples:

      assert(cbrt(1.0).feqrel(1.0) > 16);
      assert(cbrt(27.0).feqrel(3.0) > 16);
      assert(cbrt(15.625).feqrel(2.5) > 16);

pure nothrow @nogc @safe real `fabs`(real `x`);
pure nothrow @nogc @trusted double `fabs`(double `d`);
pure nothrow @nogc @trusted float `fabs`(float `f`);
  Returns |x|

  Special Values
  x | fabs(x)
  --- | ---
  ±0.0 | +0.0
  ±∞ | +∞

  Examples:

      assert(isIdentical(fabs(0.0f), 0.0f));
      assert(isIdentical(fabs(-0.0f), 0.0f));
      writeln(fabs(-10.0f)); // 10.0f

      assert(isIdentical(fabs(0.0), 0.0));
      assert(isIdentical(fabs(-0.0), 0.0));
      writeln(fabs(-10.0)); // 10.0

      assert(isIdentical(fabs(0.0L), 0.0L));
      assert(isIdentical(fabs(-0.0L), 0.0L));
      writeln(fabs(-10.0L)); // 10.0L

pure nothrow @nogc @safe real `hypot`(real `x`, real `y`);
  Calculates the length of the hypotenuse of a right-angled triangle with sides of length x and y. The hypotenuse is the value of the square root of the sums of the squares of x and y:
  sqrt(x2 + y2)
  Note that hypot(x, y), hypot(y, x) and hypot(x, -y) are equivalent.

  Special Values
  x | y | hypot(x, y) | invalid?
  --- | --- | --- | ---
  x | ±0.0 | |x| | no
  ±∞ | y | +∞ | no
  ±∞ | NAN | +∞ | no

  Examples:

      assert(hypot(1.0, 1.0).feqrel(1.4142) > 16);
      assert(hypot(3.0, 4.0).feqrel(5.0) > 16);
      writeln(hypot(real.infinity, 1.0)); // real.infinity
      writeln(hypot(real.infinity, real.nan)); // real.infinity

pure nothrow @nogc @trusted real `ceil`(real `x`);
pure nothrow @nogc @trusted double `ceil`(double `x`);
pure nothrow @nogc @trusted float `ceil`(float `x`);
  Returns the value of x rounded upward to the next integer (toward positive infinity).
  Examples:

      writeln(ceil(+123.456L)); // +124
      writeln(ceil(-123.456L)); // -123
      writeln(ceil(-1.234L)); // -1
      writeln(ceil(-0.123L)); // 0
      writeln(ceil(0.0L)); // 0
      writeln(ceil(+0.123L)); // 1
      writeln(ceil(+1.234L)); // 2
      writeln(ceil(real.infinity)); // real.infinity
      assert(isNaN(ceil(real.nan)));
      assert(isNaN(ceil(real.init)));

pure nothrow @nogc @trusted real `floor`(real `x`);
pure nothrow @nogc @trusted double `floor`(double `x`);
pure nothrow @nogc @trusted float `floor`(float `x`);
  Returns the value of x rounded downward to the next integer (toward negative infinity).
  Examples:

      writeln(floor(+123.456L)); // +123
      writeln(floor(-123.456L)); // -124
      writeln(floor(+123.0L)); // +123
      writeln(floor(-124.0L)); // -124
      writeln(floor(-1.234L)); // -2
      writeln(floor(-0.123L)); // -1
      writeln(floor(0.0L)); // 0
      writeln(floor(+0.123L)); // 0
      writeln(floor(+1.234L)); // 1
      writeln(floor(real.infinity)); // real.infinity
      assert(isNaN(floor(real.nan)));
      assert(isNaN(floor(real.init)));

Unqual!F `quantize`(alias rfunc = rint, F)(const F `val`, const F `unit`)
if (is(typeof(rfunc(F.init)) : F) && isFloatingPoint!F);
  Round `val` to a multiple of `unit`. rfunc specifies the rounding function to use; by default this is rint, which uses the current rounding mode.
  Examples:

      writeln(12345.6789L.quantize(0.01L)); // 12345.68L
      writeln(12345.6789L.quantize!floor(0.01L)); // 12345.67L
      writeln(12345.6789L.quantize(22.0L)); // 12342.0L

  Examples:

      writeln(12345.6789L.quantize(0)); // 12345.6789L
      assert(12345.6789L.quantize(real.infinity).isNaN);
      assert(12345.6789L.quantize(real.nan).isNaN);
      writeln(real.infinity.quantize(0.01L)); // real.infinity
      assert(real.infinity.quantize(real.nan).isNaN);
      assert(real.nan.quantize(0.01L).isNaN);
      assert(real.nan.quantize(real.infinity).isNaN);
      assert(real.nan.quantize(real.nan).isNaN);

Unqual!F `quantize`(real base, alias rfunc = rint, F, E)(const F `val`, const E `exp`)
if (is(typeof(rfunc(F.init)) : F) && isFloatingPoint!F && isIntegral!E);
Unqual!F `quantize`(real base, long exp = 1, alias rfunc = rint, F)(const F `val`)
if (is(typeof(rfunc(F.init)) : F) && isFloatingPoint!F);
  Round `val` to a multiple of pow(base, `exp`). rfunc specifies the rounding function to use; by default this is rint, which uses the current rounding mode.
  Examples:

      writeln(12345.6789L.quantize!10(-2)); // 12345.68L
      writeln(12345.6789L.quantize!(10, -2)); // 12345.68L
      writeln(12345.6789L.quantize!(10, floor)(-2)); // 12345.67L
      writeln(12345.6789L.quantize!(10, -2, floor)); // 12345.67L

      writeln(12345.6789L.quantize!22(1)); // 12342.0L
      writeln(12345.6789L.quantize!22); // 12342.0L

pure nothrow @nogc @safe real `nearbyint`(real `x`);
  Rounds x to the nearest integer value, using the current rounding mode.
  Unlike the rint functions, nearbyint does not raise the FE_INEXACT exception.
  Examples:

      writeln(nearbyint(0.4)); // 0
      writeln(nearbyint(0.5)); // 0
      writeln(nearbyint(0.6)); // 1
      writeln(nearbyint(100.0)); // 100

      assert(isNaN(nearbyint(real.nan)));
      writeln(nearbyint(real.infinity)); // real.infinity
      writeln(nearbyint(-real.infinity)); // -real.infinity

pure nothrow @nogc @safe real `rint`(real `x`);
pure nothrow @nogc @safe double `rint`(double `x`);
pure nothrow @nogc @safe float `rint`(float `x`);
  Rounds x to the nearest integer value, using the current rounding mode.
  If the return value is not equal to x, the FE_INEXACT exception is raised.
  nearbyint performs the same operation, but does not set the FE_INEXACT exception.
  Examples:

      version (IeeeFlagsSupport) resetIeeeFlags();
      writeln(rint(0.4)); // 0
      version (IeeeFlagsSupport) assert(ieeeFlags.inexact);

      writeln(rint(0.5)); // 0
      writeln(rint(0.6)); // 1
      writeln(rint(100.0)); // 100

      assert(isNaN(rint(real.nan)));
      writeln(rint(real.infinity)); // real.infinity
      writeln(rint(-real.infinity)); // -real.infinity

pure nothrow @nogc @trusted long `lrint`(real `x`);
  Rounds x to the nearest integer value, using the current rounding mode.
  This is generally the fastest method to convert a floating-point number to an integer. Note that the results from this function depend on the rounding mode, if the fractional part of x is exactly 0.5. If using the default rounding mode (ties round to even integers) lrint(4.5) == 4, lrint(5.5)==6.
  Examples:

      writeln(lrint(4.5)); // 4
      writeln(lrint(5.5)); // 6
      writeln(lrint(-4.5)); // -4
      writeln(lrint(-5.5)); // -6

      writeln(lrint(int.max - 0.5)); // 2147483646L
      writeln(lrint(int.max + 0.5)); // 2147483648L
      writeln(lrint(int.min - 0.5)); // -2147483648L
      writeln(lrint(int.min + 0.5)); // -2147483648L

nothrow @nogc @trusted auto `round`(real `x`);
  Return the value of x rounded to the nearest integer. If the fractional part of x is exactly 0.5, the return value is rounded away from zero.
  Returns:
  A real.
  Examples:

      writeln(round(4.5)); // 5
      writeln(round(5.4)); // 5
      writeln(round(-4.5)); // -5
      writeln(round(-5.1)); // -5

nothrow @nogc @trusted long `lround`(real `x`);
  Return the value of x rounded to the nearest integer.
  If the fractional part of x is exactly 0.5, the return value is rounded away from zero.
  This function is not implemented for Digital Mars C runtime.
  Examples:

      version (CRuntime_DigitalMars) {}
      else
      {
          writeln(lround(0.49)); // 0
          writeln(lround(0.5)); // 1
          writeln(lround(1.5)); // 2
      }

pure nothrow @nogc @trusted real `trunc`(real `x`);
  Returns the integer portion of x, dropping the fractional portion. This is also known as "chop" rounding. pure on all platforms.
  Examples:

      writeln(trunc(0.01)); // 0
      writeln(trunc(0.49)); // 0
      writeln(trunc(0.5)); // 0
      writeln(trunc(1.5)); // 1

nothrow @nogc @trusted real `remainder`(real `x`, real `y`);
nothrow @nogc @trusted real `remquo`(real `x`, real `y`, out int `n`);
  Calculate the remainder x REM y, following IEC 60559.
  REM is the value of x - y * n, where n is the integer nearest the exact value of x / y. If |n - x / y| == 0.5, n is even. If the result is zero, it has the same sign as x. Otherwise, the sign of the result is the sign of x / y. Precision mode has no effect on the remainder functions.
  remquo returns `n` in the parameter `n`.

  Special Values
  x | y | remainder(x, y) | n | invalid?
  --- | --- | --- | --- | ---
  ±0.0 | not 0.0 | ±0.0 | 0.0 | no
  ±∞ | anything | -NAN | ? | yes
  anything | ±0.0 | ±NAN | ? | yes
  != ±∞ | ±∞ | x | ? | no

  Examples:

      assert(remainder(5.1, 3.0).feqrel(-0.9) > 16);
      assert(remainder(-5.1, 3.0).feqrel(0.9) > 16);
      writeln(remainder(0.0, 3.0)); // 0.0

      assert(isNaN(remainder(1.0, 0.0)));
      assert(isNaN(remainder(-1.0, 0.0)));

  Examples:

      int n;

      assert(remquo(5.1, 3.0, n).feqrel(-0.9) > 16 && n == 2);
      assert(remquo(-5.1, 3.0, n).feqrel(0.9) > 16 && n == -2);
      assert(remquo(0.0, 3.0, n) == 0.0 && n == 0);

struct `IeeeFlags`;
  IEEE exception status flags ('sticky bits')
  These flags indicate that an exceptional floating-point condition has occurred. They indicate that a NaN or an infinity has been generated, that a result is inexact, or that a signalling NaN has been encountered. If floating-point exceptions are enabled (unmasked), a hardware exception will be generated instead of setting these flags.
  Examples:

      static void func() {
          int a = 10 * 10;
      }
      pragma(inline, false) static void blockopt(ref real x) {}
      real a = 3.5;
      // Set all the flags to zero
      resetIeeeFlags();
      assert(!ieeeFlags.divByZero);
      blockopt(a); // avoid constant propagation by the optimizer
      // Perform a division by zero.
      a /= 0.0L;
      writeln(a); // real.infinity
      assert(ieeeFlags.divByZero);
      blockopt(a); // avoid constant propagation by the optimizer
      // Create a NaN
      a *= 0.0L;
      assert(ieeeFlags.invalid);
      assert(isNaN(a));

      // Check that calling func() has no effect on the
      // status flags.
      IeeeFlags f = ieeeFlags;
      func();
      writeln(ieeeFlags); // f

  const nothrow @nogc @property @safe bool `inexact`();
    The result cannot be represented exactly, so rounding occurred.

    Example x = sin(0.1);

  const nothrow @nogc @property @safe bool `underflow`();
    A zero was generated by underflow

    Example x = real.min*real.epsilon/2;

  const nothrow @nogc @property @safe bool `overflow`();
    An infinity was generated by overflow

    Example x = real.max*2;

  const nothrow @nogc @property @safe bool `divByZero`();
    An infinity was generated by division by zero

    Example x = 3/0.0;

  const nothrow @nogc @property @safe bool `invalid`();
    A machine NaN was generated.

    Example x = real.infinity * 0.0;

nothrow @nogc @trusted void `resetIeeeFlags`();
  Set all of the floating-point status flags to false.
  Examples:

      pragma(inline, false) static void blockopt(ref real x) {}
      resetIeeeFlags();
      real a = 3.5;
      blockopt(a); // avoid constant propagation by the optimizer
      a /= 0.0L;
      blockopt(a); // avoid constant propagation by the optimizer
      writeln(a); // real.infinity
      assert(ieeeFlags.divByZero);

      resetIeeeFlags();
      assert(!ieeeFlags.divByZero);

pure nothrow @nogc @property @trusted IeeeFlags `ieeeFlags`();
  Returns:
  snapshot of the current state of the floating-point status flags
  Examples:

      pragma(inline, false) static void blockopt(ref real x) {}
      resetIeeeFlags();
      real a = 3.5;
      blockopt(a); // avoid constant propagation by the optimizer

      a /= 0.0L;
      writeln(a); // real.infinity
      assert(ieeeFlags.divByZero);
      blockopt(a); // avoid constant propagation by the optimizer

      a *= 0.0L;
      assert(isNaN(a));
      assert(ieeeFlags.invalid);

struct `FloatingPointControl`;
  Control the Floating point hardware
  Change the IEEE754 floating-point rounding mode and the floating-point hardware exceptions.
  By default, the rounding mode is roundToNearest and all hardware exceptions are disabled. For most applications, debugging is easier if the division by zero, overflow, and invalid operation exceptions are enabled. These three are combined into a severeExceptions value for convenience. Note in particular that if invalidException is enabled, a hardware trap will be generated whenever an uninitialized floating-point variable is used.
  All changes are temporary. The previous state is restored at the end of the scope.

  Example

      {
          FloatingPointControl fpctrl;

          // Enable hardware exceptions for division by zero, overflow to infinity,
          // invalid operations, and uninitialized floating-point variables.
          fpctrl.enableExceptions(FloatingPointControl.severeExceptions);

          // This will generate a hardware exception, if x is a
          // default-initialized floating point variable:
          real x; // Add `= 0` or even `= real.nan` to not throw the exception.
          real y = x * 3.0;

          // The exception is only thrown for default-uninitialized NaN-s.
          // NaN-s with other payload are valid:
          real z = y * real.nan; // ok

          // The set hardware exceptions and rounding modes will be disabled when
          // leaving this scope.
      }

  Examples:

      FloatingPointControl fpctrl;

      fpctrl.rounding = FloatingPointControl.roundDown;
      writeln(lrint(1.5)); // 1.0

      fpctrl.rounding = FloatingPointControl.roundUp;
      writeln(lrint(1.4)); // 2.0

      fpctrl.rounding = FloatingPointControl.roundToNearest;
      writeln(lrint(1.5)); // 2.0

  alias `RoundingMode` = uint;
  `roundToNearest`
  `roundDown`
  `roundUp`
  `roundToZero`
  `roundingMask`
    IEEE rounding modes. The default mode is roundToNearest.
    roundingMask = A mask of all rounding modes.
  nothrow @nogc @property @trusted void `rounding`(RoundingMode `newMode`);
    Change the floating-point hardware rounding mode
    Changing the rounding mode in the middle of a function can interfere with optimizations of floating point expressions, as the optimizer assumes that the rounding mode does not change. It is best to change the rounding mode only at the beginning of the function, and keep it until the function returns. It is also best to add the line:

        pragma(inline, false);

    as the first line of the function so it will not get inlined.
    Parameters:

    RoundingMode `newMode` | the new rounding mode

  static pure nothrow @nogc @property @trusted RoundingMode `rounding`();
    Returns:
    the currently active rounding mode
  alias `ExceptionMask` = uint;
  `subnormalException`
  `inexactException`
  `underflowException`
  `overflowException`
  `divByZeroException`
  `invalidException`
  `severeExceptions`
  `allExceptions`
    IEEE hardware exceptions. By default, all exceptions are masked (disabled).
    severeExceptions = The overflow, division by zero, and invalid exceptions.
  static pure nothrow @nogc @property @safe bool `hasExceptionTraps`();
    Returns:
    true if the current FPU supports exception trapping
  nothrow @nogc @trusted void `enableExceptions`(ExceptionMask `exceptions`);
    Enable (unmask) specific hardware exceptions. Multiple exceptions may be ORed together.
  nothrow @nogc @trusted void `disableExceptions`(ExceptionMask `exceptions`);
    Disable (mask) specific hardware exceptions. Multiple exceptions may be ORed together.
  static pure nothrow @nogc @property @trusted ExceptionMask `enabledExceptions`();
    Returns:
    the exceptions which are currently enabled (unmasked)
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 @trusted real `NaN`(ulong `payload`);
  Create a quiet NAN, storing an integer inside the payload.
  For floats, the largest possible payload is 0x3F_FFFF. For doubles, it is 0x3_FFFF_FFFF_FFFF. For 80-bit or 128-bit reals, it is 0x3FFF_FFFF_FFFF_FFFF.
  Examples:

      real a = NaN(1_000_000);
      assert(isNaN(a));
      writeln(getNaNPayload(a)); // 1_000_000

pure nothrow @nogc @trusted ulong `getNaNPayload`(real `x`);
  Extract an integral payload from a NAN.
  Returns:
  the integer payload as a ulong.
  For floats, the largest possible payload is 0x3F_FFFF. For doubles, it is 0x3_FFFF_FFFF_FFFF. For 80-bit or 128-bit reals, it is 0x3FFF_FFFF_FFFF_FFFF.
  Examples:

      real a = NaN(1_000_000);
      assert(isNaN(a));
      writeln(getNaNPayload(a)); // 1_000_000

pure nothrow @nogc @trusted real `nextUp`(real `x`);
pure nothrow @nogc @trusted double `nextUp`(double `x`);
pure nothrow @nogc @trusted float `nextUp`(float `x`);
  Calculate the next largest floating point value after x.
  Return the least number greater than x that is representable as a real; thus, it gives the next point on the IEEE number line.

  Special Values
  x | nextUp(x)
  --- | ---
  -∞ | -real.max
  ±0.0 | real.min_normal*real.epsilon
  real.max | ∞
  ∞ | ∞
  NAN | NAN

  Examples:

      assert(nextUp(1.0 - 1.0e-6).feqrel(0.999999) > 16);
      assert(nextUp(1.0 - real.epsilon).feqrel(1.0) > 16);

pure nothrow @nogc @safe real `nextDown`(real `x`);
pure nothrow @nogc @safe double `nextDown`(double `x`);
pure nothrow @nogc @safe float `nextDown`(float `x`);
  Calculate the next smallest floating point value before x.
  Return the greatest number less than x that is representable as a real; thus, it gives the previous point on the IEEE number line.

  Special Values
  x | nextDown(x)
  --- | ---
  ∞ | real.max
  ±0.0 | -real.min_normal*real.epsilon
  -real.max | -∞
  -∞ | -∞
  NAN | NAN

  Examples:

      writeln(nextDown(1.0 + real.epsilon)); // 1.0

pure nothrow @nogc @safe T `nextafter`(T)(const T `x`, const T `y`);
  Calculates the next representable value after x in the direction of y.
  If y > x, the result will be the next largest floating-point value; if y < x, the result will be the next smallest value. If x == y, the result is y. If x or y is a NaN, the result is a NaN.

  Remarks This function is not generally very useful; it's almost always better to use the faster functions nextUp() or nextDown() instead.

  The FE_INEXACT and FE_OVERFLOW exceptions will be raised if x is finite and the function result is infinite. The FE_INEXACT and FE_UNDERFLOW exceptions will be raised if the function value is subnormal, and x is not equal to y.
  Examples:

      float a = 1;
      assert(is(typeof(nextafter(a, a)) == float));
      assert(nextafter(a, a.infinity) > a);
      assert(isNaN(nextafter(a, a.nan)));
      assert(isNaN(nextafter(a.nan, a)));

      double b = 2;
      assert(is(typeof(nextafter(b, b)) == double));
      assert(nextafter(b, b.infinity) > b);
      assert(isNaN(nextafter(b, b.nan)));
      assert(isNaN(nextafter(b.nan, b)));

      real c = 3;
      assert(is(typeof(nextafter(c, c)) == real));
      assert(nextafter(c, c.infinity) > c);
      assert(isNaN(nextafter(c, c.nan)));
      assert(isNaN(nextafter(c.nan, c)));

pure nothrow @nogc @safe real `fdim`(real `x`, real `y`);
  Returns the positive difference between x and y.
  Equivalent to fmax(`x`-`y`, 0).
  Returns:

  Special Values
  x, y | fdim(x, y)
  --- | ---
  x > y | x - y
  x <= y | +0.0

  Examples:

      writeln(fdim(2.0, 0.0)); // 2.0
      writeln(fdim(-2.0, 0.0)); // 0.0
      writeln(fdim(real.infinity, 2.0)); // real.infinity
      assert(isNaN(fdim(real.nan, 2.0)));
      assert(isNaN(fdim(2.0, real.nan)));
      assert(isNaN(fdim(real.nan, real.nan)));

pure nothrow @nogc @safe F `fmax`(F)(const F `x`, const F `y`)
if (__traits(isFloating, F));
  Returns the larger of `x` and `y`.
  If one of the arguments is a NaN, the other is returned.
  See Also:
  std.algorithm.comparison.max is faster because it does not perform the isNaN test.
  Examples:

      import std.meta : AliasSeq;
      static foreach (F; AliasSeq!(float, double, real))
      {
          writeln(fmax(F(0.0), F(2.0))); // 2.0
          writeln(fmax(F(-2.0), 0.0)); // F(0.0)
          writeln(fmax(F.infinity, F(2.0))); // F.infinity
          writeln(fmax(F.nan, F(2.0))); // F(2.0)
          writeln(fmax(F(2.0), F.nan)); // F(2.0)
      }

pure nothrow @nogc @safe F `fmin`(F)(const F `x`, const F `y`)
if (__traits(isFloating, F));
  Returns the smaller of `x` and `y`.
  If one of the arguments is a NaN, the other is returned.
  See Also:
  std.algorithm.comparison.min is faster because it does not perform the isNaN test.
  Examples:

      import std.meta : AliasSeq;
      static foreach (F; AliasSeq!(float, double, real))
      {
          writeln(fmin(F(0.0), F(2.0))); // 0.0
          writeln(fmin(F(-2.0), F(0.0))); // -2.0
          writeln(fmin(F.infinity, F(2.0))); // 2.0
          writeln(fmin(F.nan, F(2.0))); // 2.0
          writeln(fmin(F(2.0), F.nan)); // 2.0
      }

pure nothrow @nogc @safe real `fma`(real `x`, real `y`, real `z`);
  Returns (x * y) + z, rounding only once according to the current rounding mode.
  Bugs:
  Not currently implemented - rounds twice.
  Examples:

      writeln(fma(0.0, 2.0, 2.0)); // 2.0
      writeln(fma(2.0, 2.0, 2.0)); // 6.0
      writeln(fma(real.infinity, 2.0, 2.0)); // real.infinity
      assert(fma(real.nan, 2.0, 2.0) is real.nan);
      assert(fma(2.0, 2.0, real.nan) is real.nan);

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:

      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:

      writeln(pow(1.0, 2.0)); // 1.0
      writeln(pow(0.0, 0.0)); // 1.0
      assert(pow(1.5, 10.0).feqrel(57.665) > 16);

      // special values
      writeln(pow(1.5, real.infinity)); // real.infinity
      writeln(pow(0.5, real.infinity)); // 0.0
      writeln(pow(1.5, -real.infinity)); // 0.0
      writeln(pow(0.5, -real.infinity)); // real.infinity
      writeln(pow(real.infinity, 1.0)); // real.infinity
      writeln(pow(real.infinity, -1.0)); // 0.0
      writeln(pow(-real.infinity, 1.0)); // -real.infinity
      writeln(pow(-real.infinity, 2.0)); // real.infinity
      writeln(pow(-real.infinity, -1.0)); // -0.0
      writeln(pow(-real.infinity, -2.0)); // 0.0
      assert(pow(1.0, real.infinity) is -real.nan);
      writeln(pow(0.0, -1.0)); // real.infinity
      writeln(pow(real.nan, 0.0)); // 1.0

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 int `feqrel`(X)(const X `x`, const X `y`)
if (isFloatingPoint!X);
  To what precision is x equal to y?
  Returns:
  the number of mantissa bits which are equal in x and y. eg, 0x1.F8p+60 and 0x1.F1p+60 are equal to 5 bits of precision.

  Special Values
  x | y | feqrel(x, y)
  --- | --- | ---
  x | x | real.mant_dig
  x | >= 2*x | 0
  x | <= x/2 | 0
  NAN | any | 0
  any | NAN | 0

  Examples:

      writeln(feqrel(2.0, 2.0)); // 53
      writeln(feqrel(2.0f, 2.0f)); // 24
      writeln(feqrel(2.0, double.nan)); // 0

      // Test that numbers are within n digits of each
      // other by testing if feqrel > n * log2(10)

      // five digits
      assert(feqrel(2.0, 2.00001) > 16);
      // ten digits
      assert(feqrel(2.0, 2.00000000001) > 33);

pure nothrow @nogc @trusted Unqual!(CommonType!(T1, T2)) `poly`(T1, T2)(T1 `x`, in T2[] `A`)
if (isFloatingPoint!T1 && isFloatingPoint!T2);
pure nothrow @nogc @safe Unqual!(CommonType!(T1, T2)) `poly`(T1, T2, int N)(T1 `x`, ref const T2[N] `A`)
if (isFloatingPoint!T1 && isFloatingPoint!T2 && (N > 0) && (N <= 10));
  Evaluate polynomial A(x) = a0 + a1x + a2x2 + a3x3; ...
  Uses Horner's rule A(x) = a0 + x(a1 + x(a2 + x(a3 + ...)))
  Parameters:

  T1 `x` | the value to evaluate.
  T2[] `A` | array of coefficients a0, a1, etc.

  Examples:

      real x = 3.1L;
      static real[] pp = [56.1L, 32.7L, 6];

      writeln(poly(x, pp)); // (56.1L + (32.7L + 6.0L * x) * x)

bool `approxEqual`(T, U, V)(T `value`, U `reference`, V `maxRelDiff` = 0.01, V `maxAbsDiff` = 1e-05);
  Computes whether a values is approximately equal to a reference value, admitting a maximum relative difference, and a maximum absolute difference.
  Parameters:

  T `value` | Value to compare.
  U `reference` | Reference value.
  V `maxRelDiff` | Maximum allowable difference relative to `reference`. Setting to 0.0 disables this check. Defaults to 1e-2.
  V `maxAbsDiff` | Maximum absolute difference. This is mainly usefull for comparing values to zero. Setting to 0.0 disables this check. Defaults to 1e-5.

  Returns:
  true if `value` is approximately equal to `reference` under either criterium. It is sufficient, when `value` satisfies one of the two criteria.
  If one item is a range, and the other is a single value, then the result is the logical and-ing of calling `approxEqual` on each element of the ranged item against the single item. If both items are ranges, then `approxEqual` returns true if and only if the ranges have the same number of elements and if `approxEqual` evaluates to true for each pair of elements.
  See Also:
  Use feqrel to get the number of equal bits in the mantissa.
  Examples:

      assert(approxEqual(1.0, 1.0099));
      assert(!approxEqual(1.0, 1.011));
      assert(approxEqual(0.00001, 0.0));
      assert(!approxEqual(0.00002, 0.0));

      assert(approxEqual(3.0, [3, 3.01, 2.99])); // several reference values is strange
      assert(approxEqual([3, 3.01, 2.99], 3.0)); // better

      float[] arr1 = [ 1.0, 2.0, 3.0 ];
      double[] arr2 = [ 1.001, 1.999, 3 ];
      assert(approxEqual(arr1, arr2));

  Examples:

      // relative comparison depends on reference, make sure proper
      // side is used when comparing range to single value. Based on
      // https://issues.dlang.org/show_bug.cgi?id=15763
      auto a = [2e-3 - 1e-5];
      auto b = 2e-3 + 1e-5;
      assert(a[0].approxEqual(b));
      assert(!b.approxEqual(a[0]));
      assert(a.approxEqual(b));
      assert(!b.approxEqual(a));

  Examples:

      assert(!approxEqual(0.0,1e-15,1e-9,0.0));
      assert(approxEqual(0.0,1e-15,1e-9,1e-9));
      assert(!approxEqual(1.0,3.0,0.0,1.0));

      assert(approxEqual(1.00000000099,1.0,1e-9,0.0));
      assert(!approxEqual(1.0000000011,1.0,1e-9,0.0));

  Examples:

      // maybe unintuitive behavior
      assert(approxEqual(1000.0,1010.0));
      assert(approxEqual(9_090_000_000.0,9_000_000_000.0));
      assert(approxEqual(0.0,1e30,1.0));
      assert(approxEqual(0.00001,1e-30));
      assert(!approxEqual(-1e-30,1e-30,1e-2,0.0));

bool `isClose`(T, U, V = CommonType!(FloatingPointBaseType!T, FloatingPointBaseType!U))(T `lhs`, U `rhs`, V `maxRelDiff` = CommonDefaultFor!(T, U), V `maxAbsDiff` = 0.0);
  Computes whether two values are approximately equal, admitting a maximum relative difference, and a maximum absolute difference.
  Parameters:

  T `lhs` | First item to compare.
  U `rhs` | Second item to compare.
  V `maxRelDiff` | Maximum allowable relative difference. Setting to 0.0 disables this check. Default depends on the type of `lhs` and `rhs`: It is approximately half the number of decimal digits of precision of the smaller type.
  V `maxAbsDiff` | Maximum absolute difference. This is mainly usefull for comparing values to zero. Setting to 0.0 disables this check. Defaults to 0.0.

  Returns:
  true if the two items are approximately equal under either criterium. It is sufficient, when value satisfies one of the two criteria.
  If one item is a range, and the other is a single value, then the result is the logical and-ing of calling `isClose` on each element of the ranged item against the single item. If both items are ranges, then `isClose` returns true if and only if the ranges have the same number of elements and if `isClose` evaluates to true for each pair of elements.
  See Also:
  Use feqrel to get the number of equal bits in the mantissa.
  Examples:

      assert(isClose(1.0,0.999_999_999));
      assert(isClose(0.001, 0.000_999_999_999));
      assert(isClose(1_000_000_000.0,999_999_999.0));

      assert(isClose(17.123_456_789, 17.123_456_78));
      assert(!isClose(17.123_456_789, 17.123_45));

      // use explicit 3rd parameter for less (or more) accuracy
      assert(isClose(17.123_456_789, 17.123_45, 1e-6));
      assert(!isClose(17.123_456_789, 17.123_45, 1e-7));

      // use 4th parameter when comparing close to zero
      assert(!isClose(1e-100, 0.0));
      assert(isClose(1e-100, 0.0, 0.0, 1e-90));
      assert(!isClose(1e-10, -1e-10));
      assert(isClose(1e-10, -1e-10, 0.0, 1e-9));
      assert(!isClose(1e-300, 1e-298));
      assert(isClose(1e-300, 1e-298, 0.0, 1e-200));

      // different default limits for different floating point types
      assert(isClose(1.0f, 0.999_99f));
      assert(!isClose(1.0, 0.999_99));
      static if (real.sizeof > double.sizeof)
          assert(!isClose(1.0L, 0.999_999_999L));

  Examples:

      assert(isClose([1.0, 2.0, 3.0], [0.999_999_999, 2.000_000_001, 3.0]));
      assert(!isClose([1.0, 2.0], [0.999_999_999, 2.000_000_001, 3.0]));
      assert(!isClose([1.0, 2.0, 3.0], [0.999_999_999, 2.000_000_001]));

      assert(isClose([2.0, 1.999_999_999, 2.000_000_001], 2.0));
      assert(isClose(2.0, [2.0, 1.999_999_999, 2.000_000_001]));

pure nothrow @nogc @trusted int `cmp`(T)(const(T) `x`, const(T) `y`)
if (isFloatingPoint!T);
  Defines a total order on all floating-point numbers.
  The order is defined as follows:
  - All numbers in [-∞, +∞] are ordered the same way as by built-in comparison, with the exception of -0.0, which is less than +0.0;
  - If the sign bit is set (that is, it's 'negative'), NAN is less than any number; if the sign bit is not set (it is 'positive'), NAN is greater than any number;
  - NANs of the same sign are ordered by the payload ('negative' ones - in reverse order).
  Returns:
  negative value if `x` precedes `y` in the order specified above; 0 if `x` and `y` are identical, and positive value otherwise.
  See Also:
  isIdentical
  Standards:
  Conforms to IEEE 754-2008
  Examples:
  Most numbers are ordered naturally.

      assert(cmp(-double.infinity, -double.max) < 0);
      assert(cmp(-double.max, -100.0) < 0);
      assert(cmp(-100.0, -0.5) < 0);
      assert(cmp(-0.5, 0.0) < 0);
      assert(cmp(0.0, 0.5) < 0);
      assert(cmp(0.5, 100.0) < 0);
      assert(cmp(100.0, double.max) < 0);
      assert(cmp(double.max, double.infinity) < 0);

      writeln(cmp(1.0, 1.0)); // 0

  Examples:
  Positive and negative zeroes are distinct.

      assert(cmp(-0.0, +0.0) < 0);
      assert(cmp(+0.0, -0.0) > 0);

  Examples:
  Depending on the sign, NANs go to either end of the spectrum.

      assert(cmp(-double.nan, -double.infinity) < 0);
      assert(cmp(double.infinity, double.nan) < 0);
      assert(cmp(-double.nan, double.nan) < 0);

  Examples:
  NANs of the same sign are ordered by the payload.

      assert(cmp(NaN(10), NaN(20)) < 0);
      assert(cmp(-NaN(20), -NaN(10)) < 0);

T `nextPow2`(T)(const T `val`)
if (isIntegral!T);
T `nextPow2`(T)(const T `val`)
if (isFloatingPoint!T);
  Gives the next power of two after `val`. T can be any built-in numerical type.
  If the operation would lead to an over/underflow, this function will return 0.
  Parameters:

  T `val` | any number

  Returns:
  the next power of two after `val`
  Examples:

      writeln(nextPow2(2)); // 4
      writeln(nextPow2(10)); // 16
      writeln(nextPow2(4000)); // 4096

      writeln(nextPow2(-2)); // -4
      writeln(nextPow2(-10)); // -16

      writeln(nextPow2(uint.max)); // 0
      writeln(nextPow2(uint.min)); // 0
      writeln(nextPow2(size_t.max)); // 0
      writeln(nextPow2(size_t.min)); // 0

      writeln(nextPow2(int.max)); // 0
      writeln(nextPow2(int.min)); // 0
      writeln(nextPow2(long.max)); // 0
      writeln(nextPow2(long.min)); // 0

  Examples:

      writeln(nextPow2(2.1)); // 4.0
      writeln(nextPow2(-2.0)); // -4.0
      writeln(nextPow2(0.25)); // 0.5
      writeln(nextPow2(-4.0)); // -8.0

      writeln(nextPow2(double.max)); // 0.0
      writeln(nextPow2(double.infinity)); // double.infinity

T `truncPow2`(T)(const T `val`)
if (isIntegral!T);
T `truncPow2`(T)(const T `val`)
if (isFloatingPoint!T);
  Gives the last power of two before `val`. <> can be any built-in numerical type.
  Parameters:

  T `val` | any number

  Returns:
  the last power of two before `val`
  Examples:

      writeln(truncPow2(3)); // 2
      writeln(truncPow2(4)); // 4
      writeln(truncPow2(10)); // 8
      writeln(truncPow2(4000)); // 2048

      writeln(truncPow2(-5)); // -4
      writeln(truncPow2(-20)); // -16

      writeln(truncPow2(uint.max)); // int.max + 1
      writeln(truncPow2(uint.min)); // 0
      writeln(truncPow2(ulong.max)); // long.max + 1
      writeln(truncPow2(ulong.min)); // 0

      writeln(truncPow2(int.max)); // (int.max / 2) + 1
      writeln(truncPow2(int.min)); // int.min
      writeln(truncPow2(long.max)); // (long.max / 2) + 1
      writeln(truncPow2(long.min)); // long.min

  Examples:

      writeln(truncPow2(2.1)); // 2.0
      writeln(truncPow2(7.0)); // 4.0
      writeln(truncPow2(-1.9)); // -1.0
      writeln(truncPow2(0.24)); // 0.125
      writeln(truncPow2(-7.0)); // -4.0

      writeln(truncPow2(double.infinity)); // double.infinity

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:

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

Copyright © 1999-2020 by the D Language Foundation | Page generated by Ddoc on Tue Sep 22 09:13:45 2020