Module math

Constructive mathematics is naturally typed. -- Simon Thompson

Basic math routines for Nim. This module is available for the JavaScript target.

Note that the trigonometric functions naturally operate on radians. The helper functions degToRad and radToDeg provide conversion between radians and degrees.

Types

FloatClass = enum
  fcNormal,                   ## value is an ordinary nonzero floating point value
  fcSubnormal,                ## value is a subnormal (a very small) floating point value
  fcZero,                     ## value is zero
  fcNegZero,                  ## value is the negative zero
  fcNan,                      ## value is Not-A-Number (NAN)
  fcInf,                      ## value is positive infinity
  fcNegInf                    ## value is negative infinity

describes the class a floating point value belongs to. This is the type that is returned by classify.

Consts

PI = 3.141592653589793

the circle constant PI (Ludolph's number)

TAU = 6.283185307179586

the circle constant TAU (= 2 * PI)

E = 2.718281828459045

Euler's number

MaxFloat64Precision = 16

maximum number of meaningful digits after the decimal point for Nim's float64 type.

MaxFloat32Precision = 8

maximum number of meaningful digits after the decimal point for Nim's float32 type.

MaxFloatPrecision = 16

maximum number of meaningful digits after the decimal point for Nim's float type.

Procs

proc binom(n, k: int): int {.noSideEffect, raises: [], tags: [].}

Computes the binomial coefficient

proc fac(n: int): int {.noSideEffect, raises: [], tags: [].}

Computes the faculty/factorial function.

proc classify(x: float): FloatClass {.raises: [], tags: [].}

Classifies a floating point value. Returns x's class as specified by FloatClass.

proc isPowerOfTwo(x: int): bool {.noSideEffect, raises: [], tags: [].}

Returns true, if x is a power of two, false otherwise. Zero and negative numbers are not a power of two.

proc nextPowerOfTwo(x: int): int {.noSideEffect, raises: [], tags: [].}

Returns x rounded up to the nearest power of two. Zero and negative numbers get rounded up to 1.

proc countBits32(n: int32): int {.noSideEffect, raises: [], tags: [].}

Counts the set bits in n.

proc sum[T](x: openArray[T]): T {.noSideEffect.}

Computes the sum of the elements in x. If x is empty, 0 is returned.

proc sqrt(x: float32): float32 {.importc: "sqrtf", header: "<math.h>".}

proc sqrt(x: float64): float64 {.importc: "sqrt", header: "<math.h>".}

Computes the square root of x.

proc cbrt(x: float32): float32 {.importc: "cbrtf", header: "<math.h>".}

proc cbrt(x: float64): float64 {.importc: "cbrt", header: "<math.h>".}

Computes the cubic root of x

proc ln(x: float32): float32 {.importc: "logf", header: "<math.h>".}

proc ln(x: float64): float64 {.importc: "log", header: "<math.h>".}

Computes the natural log of x

proc log10(x: float32): float32 {.importc: "log10f", header: "<math.h>".}

proc log10(x: float64): float64 {.importc: "log10", header: "<math.h>".}

Computes the common logarithm (base 10) of x

proc log2[T: float32 | float64](x: T): T

Computes the binary logarithm (base 2) of x

proc exp(x: float32): float32 {.importc: "expf", header: "<math.h>".}

proc exp(x: float64): float64 {.importc: "exp", header: "<math.h>".}

Computes the exponential function of x (pow(E, x))

proc arccos(x: float32): float32 {.importc: "acosf", header: "<math.h>".}

proc arccos(x: float64): float64 {.importc: "acos", header: "<math.h>".}

Computes the arc cosine of x

proc arcsin(x: float32): float32 {.importc: "asinf", header: "<math.h>".}

proc arcsin(x: float64): float64 {.importc: "asin", header: "<math.h>".}

Computes the arc sine of x

proc arctan(x: float32): float32 {.importc: "atanf", header: "<math.h>".}

proc arctan(x: float64): float64 {.importc: "atan", header: "<math.h>".}

Calculate the arc tangent of y / x

proc arctan2(y, x: float32): float32 {.importc: "atan2f", header: "<math.h>".}

proc arctan2(y, x: float64): float64 {.importc: "atan2", header: "<math.h>".}

Calculate the arc tangent of y / x. atan2 returns the arc tangent of y / x; it produces correct results even when the resulting angle is near pi/2 or -pi/2 (x near 0).

proc cos(x: float32): float32 {.importc: "cosf", header: "<math.h>".}

proc cos(x: float64): float64 {.importc: "cos", header: "<math.h>".}

Computes the cosine of x

proc cosh(x: float32): float32 {.importc: "coshf", header: "<math.h>".}

proc cosh(x: float64): float64 {.importc: "cosh", header: "<math.h>".}

Computes the hyperbolic cosine of x

proc hypot(x, y: float32): float32 {.importc: "hypotf", header: "<math.h>".}

proc hypot(x, y: float64): float64 {.importc: "hypot", header: "<math.h>".}

Computes the hypotenuse of a right-angle triangle with x and y as its base and height. Equivalent to sqrt(x*x + y*y).

proc sinh(x: float32): float32 {.importc: "sinhf", header: "<math.h>".}

proc sinh(x: float64): float64 {.importc: "sinh", header: "<math.h>".}

Computes the hyperbolic sine of x

proc sin(x: float32): float32 {.importc: "sinf", header: "<math.h>".}

proc sin(x: float64): float64 {.importc: "sin", header: "<math.h>".}

Computes the sine of x

proc tan(x: float32): float32 {.importc: "tanf", header: "<math.h>".}

proc tan(x: float64): float64 {.importc: "tan", header: "<math.h>".}

Computes the tangent of x

proc tanh(x: float32): float32 {.importc: "tanhf", header: "<math.h>".}

proc tanh(x: float64): float64 {.importc: "tanh", header: "<math.h>".}

Computes the hyperbolic tangent of x

proc pow(x, y: float32): float32 {.importc: "powf", header: "<math.h>".}

proc pow(x, y: float64): float64 {.importc: "pow", header: "<math.h>".}

computes x to power raised of y.

proc erf(x: float32): float32 {.importc: "erff", header: "<math.h>".}

proc erf(x: float64): float64 {.importc: "erf", header: "<math.h>".}

The error function

proc erfc(x: float32): float32 {.importc: "erfcf", header: "<math.h>".}

proc erfc(x: float64): float64 {.importc: "erfc", header: "<math.h>".}

The complementary error function

proc lgamma(x: float32): float32 {.importc: "lgammaf", header: "<math.h>".}

proc lgamma(x: float64): float64 {.importc: "lgamma", header: "<math.h>".}

Natural log of the gamma function

proc tgamma(x: float32): float32 {.importc: "tgammaf", header: "<math.h>".}

proc tgamma(x: float64): float64 {.importc: "tgamma", header: "<math.h>".}

The gamma function

proc floor(x: float32): float32 {.importc: "floorf", header: "<math.h>".}

proc floor(x: float64): float64 {.importc: "floor", header: "<math.h>".}

Computes the floor function (i.e., the largest integer not greater than x)

echo floor(-3.5) ## -4.0

proc ceil(x: float32): float32 {.importc: "ceilf", header: "<math.h>".}

proc ceil(x: float64): float64 {.importc: "ceil", header: "<math.h>".}

Computes the ceiling function (i.e., the smallest integer not less than x)

echo ceil(-2.1) ## -2.0

proc trunc(x: float32): float32 {.importc: "truncf", header: "<math.h>".}

proc trunc(x: float64): float64 {.importc: "trunc", header: "<math.h>".}

Truncates x to the decimal point

echo trunc(PI) # 3.0

proc fmod(x, y: float32): float32 {.importc: "fmodf", header: "<math.h>".}

proc fmod(x, y: float64): float64 {.importc: "fmod", header: "<math.h>".}

Computes the remainder of x divided by y

echo fmod(-2.5, 0.3) ## -0.1

proc round[T: float32 | float64](x: T; places: int = 0): T

Round a floating point number.

If places is 0 (or omitted), round to the nearest integral value following normal mathematical rounding rules (e.g. round(54.5) -> 55.0). If places is greater than 0, round to the given number of decimal places, e.g. round(54.346, 2) -> 54.35. If places is negative, round to the left of the decimal place, e.g. round(537.345, -1) -> 540.0

proc frexp(x: float32; exponent: var int): float32 {.importc: "frexp", header: "<math.h>".}

proc frexp(x: float64; exponent: var int): float64 {.importc: "frexp", header: "<math.h>".}

Split a number into mantissa and exponent. frexp calculates the mantissa m (a float greater than or equal to 0.5 and less than 1) and the integer value n such that x (the original float value) equals m * 2**n. frexp stores n in exponent and returns m.

proc splitDecimal[T: float32 | float64](x: T): tuple[intpart: T, floatpart: T]

Breaks x into an integral and a fractional part.

Returns a tuple containing intpart and floatpart representing the integer part and the fractional part respectively.

Both parts have the same sign as x. Analogous to the modf function in C.

proc degToRad[T: float32 | float64](d: T): T {.inline.}

Convert from degrees to radians

proc radToDeg[T: float32 | float64](d: T): T {.inline.}

Convert from radians to degrees

proc sgn[T: SomeNumber](x: T): int {.inline.}

Sign function. Returns -1 for negative numbers and NegInf, 1 for positive numbers and Inf, and 0 for positive zero, negative zero and NaN.

proc `mod`[T: float32 | float64](x, y: T): T

Computes the modulo operation for float operators. Equivalent to x - y * floor(x/y). Note that the remainder will always have the same sign as the divisor.

echo (4.0 mod -3.1) # -2.2

proc `^`[T](x: T; y: Natural): T

Computes x to the power y`. ``x must be non-negative, use pow <#pow,float,float> for negative exponents.

proc gcd[T](x, y: T): T

Computes the greatest common divisor of x and y. Note that for floats, the result cannot always be interpreted as "greatest decimal z such that z*N == x and z*M == y where N and M are positive integers."

proc lcm[T](x, y: T): T

Computes the least common multiple of x and y.