std.math - D Programming Language - Digital Mars

D Programming Language 2.0

- Comments
- D
- Search
- Home

Last update Wed Sep 2 00:11:54 2009

# std.math

Elementary mathematical functions.

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.

Unlike C, there is no global 'errno' variable. Consequently, almost all of these functions are pure nothrow.

Authors:
Walter Bright, Don Clugston

real E;
  e

real LOG2T;
  log210

real LOG2E;
  log2e

real LOG2;
  log102

real LOG10E;
  log10e

real LN2;
  ln 2

real LN10;
  ln 10

real PI;
  π

real PI_2;
  π / 2

real PI_4;
  π / 4

real M_1_PI;
  1 / π

real M_2_PI;
  2 / π

real M_2_SQRTPI;
  2 / &radix;π

real SQRT2;
  &radix;2

real SQRT1_2;
  &radix;½

Num abs(Num)(Num x);
real abs(Num)(Num y);
  Calculates the absolute value

  For complex numbers, abs(z) = sqrt( z.re2 + z.im2 ) = hypot(z.re, z.im).

creal conj(creal z);
ireal conj(ireal y);
  Complex conjugate

  conj(x + iy) = x - iy

  Note that z * conj(z) = z.re2 - z.im2 is always a real number

real cos(real 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.

real sin(real 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

  BUGS:
  Results are undefined if |x| >= 264.

creal sin(creal z);
ireal sin(ireal y);
  sine, complex and imaginary

  sin(z) = sin(z.re)*cosh(z.im) + cos(z.re)*sinh(z.im)i

  If both sin(θ) and cos(θ) are required, it is most efficient to use expi(θ).

creal cos(creal z);
real cos(ireal y);
  cosine, complex and imaginary

  cos(z) = cos(z.re)*cosh(z.im) - sin(z.re)*sinh(z.im)i

real tan(real 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

float acos(float x);
double acos(double x);
real acos(real 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

float asin(float x);
double asin(double x);
real asin(real 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

float atan(float x);
double atan(double x);
real atan(real 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

float atan2(float y, float x);
double atan2(double y, double x);
real atan2(real y, real 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

real cosh(real x);
double cosh(double x);
float cosh(float x);
  Calculates the hyperbolic cosine of x.

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

real sinh(real x);
double sinh(double x);
float sinh(float x);
  Calculates the hyperbolic sine of x.

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

real tanh(real x);
double tanh(double x);
float tanh(float x);
  Calculates the hyperbolic tangent of x.

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

real acosh(real x);
double acosh(double x);
float acosh(float x);
  Calculates the inverse hyperbolic cosine of x.

  Mathematically, acosh(x) = log(x + sqrt( x*x - 1))

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

real asinh(real x);
double asinh(double x);
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
  ±∞ | ±∞

real atanh(real x);
double atanh(double x);
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

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

long rndtol(real 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.

real rndtonl(real x);
  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.

float sqrt(float x);
  Compute square root of x.

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

double sqrt(double x);
  ditto

  Compute square root of x.

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

real sqrt(real x);
  ditto

  Compute square root of x.

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

real exp(real x);
double exp(double x);
float exp(float x);
  Calculates ex.

  Special Values
  x | ex
  --- | ---
  +∞ | +∞

  -∞ +0.0

  NAN NAN

)
real expm1(real 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
) )
real exp2(real x);
  Calculates 2x.

  Special Values
  x | exp2(x) | +∞ | +∞
  -∞ | +0.0

  NAN NAN

)
creal expi(real y);
  Calculate cos(y) + i sin(y).

  On many CPUs (such as x86), this is a very efficient operation; almost twice as fast as calculating sin(y) and cos(y) separately, and is the preferred method when both are required.

real frexp(real value, out int exp);
  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

int ilogb(real x);
  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

real ldexp(real n, int exp);
  Compute n * 2exp

  References:
  frexp

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

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

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

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

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

real modf(real x, ref 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 | modf(x, y) | invalid?
  --- | --- | --- | ---
  ±0.0 | not 0.0 | ±0.0 | no
  ±∞ | anything | NAN | yes
  anything | ±0.0 | NAN | yes
  !=±∞ | ±∞ | x | no

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

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

real fabs(real x);
  Returns |x|

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

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( + )

  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

real erf(real x);
  Returns the error function of x.

real erfc(real x);
  Returns the complementary error function of x, which is 1 - erf(x).

real lgamma(real x);
  Natural logarithm of gamma function.

  Returns the base e (2.718...) logarithm of the absolute value of the gamma function of the argument.

  For reals, lgamma is equivalent to log(fabs(gamma(x))).

  Special Values
  x | lgamma(x) | invalid?
  --- | --- | ---
  NAN | NAN | yes
  integer <= 0 | +∞ | yes
  ±∞ | +∞ | no

real tgamma(real x);
  The Gamma function, Γ(x)

  Γ(x) is a generalisation of the factorial function to real and complex numbers. Like x!, Γ(x+1) = x*Γ(x).

  Mathematically, if z.re > 0 then Γ(z) = ∫0∞ tz-1e-t dt

  Special Values
  x | Γ(x) | invalid?
  --- | --- | ---
  NAN | NAN | yes
  ±0.0 | ±∞ | yes
  integer >0 | (x-1)! | no
  integer <0 | NAN | yes
  +∞ | +∞ | no
  -∞ | NAN | yes

  References:
  http://en.wikipedia.org/wiki/Gamma_function, http://www.netlib.org/cephes/ldoubdoc.html#gamma

real ceil(real x);
  Returns the value of x rounded upward to the next integer (toward positive infinity).

real floor(real x);
  Returns the value of x rounded downward to the next integer (toward negative infinity).

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.

real rint(real 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.

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.

real 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 to the even integer.

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.

real trunc(real x);
  Returns the integer portion of x, dropping the fractional portion.

  This is also known as "chop" rounding.

real remainder(real x, real y);
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

  Note:
  remquo not supported on windows

bool isNaN(real x);
  Returns !=0 if e is a NaN.

int isFinite(real e);
  Returns !=0 if e is finite (not infinite or NAN).

int isNormal(X)(X x);
  Returns !=0 if x is normalized (not zero, subnormal, infinite, or NAN).

int isSubnormal(float f);
int isSubnormal(double d);
int isSubnormal(real x);
  Is number subnormal? (Also called "denormal".) Subnormals have a 0 exponent and a 0 most significant mantissa bit.

bool isInfinity(real x);
  Return !=0 if e is ±∞.

bool isIdentical(real x, real y);
  Is the binary representation of x identical to y?

  Same as ==, except that positive and negative zero are not identical, and two NANs are identical if they have the same 'payload'.

int signbit(real x);
  Return 1 if sign bit of e is set, 0 if not.

real copysign(real to, real from);
  Return a value composed of to with from's sign bit.

F sgn(F)(F x);
  Returns -1 if x < 0, x if x == 0, 1 if x > 0, and NAN if x==NAN.

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.

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.

real nextUp(real x);
double nextUp(double x);
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*real.epsilon
  real.max | ∞
  ∞ | ∞
  NAN | NAN

real nextDown(real x);
double nextDown(double x);
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*real.epsilon
  -real.max | -∞
  -∞ | -∞
  NAN | NAN

T nextafter(T)(T x, 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.

  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.

real fdim(real x, real y);
  Returns the positive difference between x and y.

  Returns:

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

real fmax(real x, real y);
  Returns the larger of x and y.

real fmin(real x, real y);
  Returns the smaller of x and y.

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.

F pow(F)(F x, uint n);
F pow(F)(F x, int n);
  Fast integral powers.

F pow(F)(F x, F y);
  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

int feqrel(X)(X x, X y);
  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

real poly(real x, const real[] A);
  Evaluate polynomial A(x) = a0 + a1x + a2x2 + a3x3; ...

  Uses Horner's rule A(x) = a0 + x(a1 + x(a2 + x(a3 + ...)))

  Parameters:

  real[] A | array of coefficients a0, a1, etc.

bool approxEqual(T, U, V)(T lhs, U rhs, V maxRelDiff, V maxAbsDiff = 0);
  Computes whether lhs is approximately equal to rhs admitting a maximum relative difference maxRelDiff and a maximum absolute difference maxAbsDiff.

  If the two inputs are ranges, 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.

bool approxEqual(T, U)(T lhs, U rhs);
  Returns approxEqual(lhs, rhs, 0.01).

)
Copyright © 1999-2009 by Digital Mars, All Rights Reserved | Page generated by Ddoc.