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.

Imports

bitops

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 {...}{.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 prod[T](x: openArray[T]): T {...}{.noSideEffect.}

Computes the product of the elements in x. If x is empty, 1 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 log[T: SomeFloat](x, base: T): T

Computes the logarithm base 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 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 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 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 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 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 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 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 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 arcsinh(x: float32): float32 {...}{.importc: "asinhf", header: "<math.h>".}

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

Computes the inverse hyperbolic sine of x

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

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

Computes the inverse hyperbolic cosine of x

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

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

Computes the inverse hyperbolic tangent of x

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

Computes the cotangent of x

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

Computes the secant of x.

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

Computes the cosecant of x

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

Computes the hyperbolic cotangent of x

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

Computes the hyperbolic secant of x

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

Computes the hyperbolic cosecant of x

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

Computes the inverse cotangent of x

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

Computes the inverse secant of x

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

Computes the inverse cosecant of x

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

Computes the inverse hyperbolic cotangent of x

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

Computes the inverse hyperbolic secant of x

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

Computes the inverse hyperbolic cosecant 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 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.

To compute power between integers, use ^ e.g. 2 ^ 6

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 gamma(x: float32): float32 {...}{.importc: "tgammaf", header: "<math.h>".}

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

The gamma function

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

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

The gamma function Deprecated since version 0.19.0: Use gamma instead.

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 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 {...}{.deprecated: "use mod instead", importc: "fmodf",
                               header: "<math.h>".}

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

Computes the remainder of x divided by y

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

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

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

Computes the modulo operation for float operators.

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 floorDiv[T: SomeInteger](x, y: T): T

Floor division is conceptually defined as floor(x / y). This is different from the div operator, which is defined as trunc(x / y). That is, div rounds towards 0 and floorDiv rounds down.

proc floorMod[T: SomeNumber](x, y: T): T

Floor modulus is conceptually defined as x - (floorDiv(x, y) * y). This proc behaves the same as the ``% operator in python.

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

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

proc frexp[T, U](x: T; exponent: var U): T

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 log2(x: float32): float32 {...}{.importc: "log2f", header: "<math.h>".}

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

Computes the binary logarithm (base 2) of x

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 `^`[T](x: T; y: Natural): T

Computes x to the power y. x must be non-negative, use pow for negative exponents.

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

Computes the greatest common (positive) 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 gcd(x, y: SomeInteger): SomeInteger

Computes the greatest common (positive) divisor of x and y. Using binary GCD (aka Stein's) algorithm.

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

Computes the least common multiple of x and y.