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.   Source Edit

Consts

PI = 3.141592653589793
the circle constant PI (Ludolph's number)   Source Edit
TAU = 6.283185307179586
the circle constant TAU (= 2 * PI)   Source Edit
E = 2.718281828459045
Euler's number   Source Edit
MaxFloat64Precision = 16
maximum number of meaningful digits after the decimal point for Nim's float64 type.   Source Edit
MaxFloat32Precision = 8
maximum number of meaningful digits after the decimal point for Nim's float32 type.   Source Edit
MaxFloatPrecision = 16
maximum number of meaningful digits after the decimal point for Nim's float type.   Source Edit

Procs

proc binom(n, k: int): int {...}{.noSideEffect, raises: [], tags: [].}
Computes the binomial coefficient.
echo binom(6, 2) ## 15
  Source Edit
proc fac(n: int): int {...}{.raises: [], tags: [].}
Computes the factorial of a non-negative integer n
echo fac(4) ## 24
  Source Edit
proc classify(x: float): FloatClass {...}{.raises: [], tags: [].}
Classifies a floating point value. Returns x's class as specified by FloatClass.
echo classify(0.3) ## fcNormal
echo classify(0.0) ## fcZero
echo classify(0.3/0.0) ## fcInf
  Source Edit
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.
echo isPowerOfTwo(5) ## false
echo isPowerOfTwo(8) ## true
  Source Edit
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.
echo nextPowerOfTwo(8) ## 8
echo nextPowerOfTwo(9) ## 16
  Source Edit
proc countBits32(n: int32): int {...}{.noSideEffect, raises: [], tags: [].}
Counts the set bits in n.
echo countBits32(13'i32) ## 3
  Source Edit
proc sum[T](x: openArray[T]): T {...}{.noSideEffect.}
Computes the sum of the elements in x. If x is empty, 0 is returned.
echo sum([1.0, 2.5, -3.0, 4.3]) ## 4.8
  Source Edit
proc prod[T](x: openArray[T]): T {...}{.noSideEffect.}
Computes the product of the elements in x. If x is empty, 1 is returned.
echo prod([1.0, 3.0, -0.2]) ## -0.6
  Source Edit
proc sqrt(x: float32): float32 {...}{.importc: "sqrtf", header: "<math.h>", noSideEffect.}
  Source Edit
proc sqrt(x: float64): float64 {...}{.importc: "sqrt", header: "<math.h>", noSideEffect.}
Computes the square root of x.
echo sqrt(1.44) ## 1.2
  Source Edit
proc cbrt(x: float32): float32 {...}{.importc: "cbrtf", header: "<math.h>", noSideEffect.}
  Source Edit
proc cbrt(x: float64): float64 {...}{.importc: "cbrt", header: "<math.h>", noSideEffect.}
Computes the cubic root of x.
echo cbrt(2.197) ## 1.3
  Source Edit
proc ln(x: float32): float32 {...}{.importc: "logf", header: "<math.h>", noSideEffect.}
  Source Edit
proc ln(x: float64): float64 {...}{.importc: "log", header: "<math.h>", noSideEffect.}
Computes the natural logarithm of x.
echo ln(exp(4.0)) ## 4.0
  Source Edit
proc log[T: SomeFloat](x, base: T): T {...}{.noSideEffect.}
Computes the logarithm of x to base base.
echo log(9.0, 3.0) ## 2.0
  Source Edit
proc log10(x: float32): float32 {...}{.importc: "log10f", header: "<math.h>", noSideEffect.}
  Source Edit
proc log10(x: float64): float64 {...}{.importc: "log10", header: "<math.h>", noSideEffect.}
Computes the common logarithm (base 10) of x.
echo log10(100.0) ## 2.0
  Source Edit
proc exp(x: float32): float32 {...}{.importc: "expf", header: "<math.h>", noSideEffect.}
  Source Edit
proc exp(x: float64): float64 {...}{.importc: "exp", header: "<math.h>", noSideEffect.}
Computes the exponential function of x (pow(E, x)).
echo exp(1.0) ## 2.718281828459045
echo ln(exp(4.0)) ## 4.0
  Source Edit
proc sin(x: float32): float32 {...}{.importc: "sinf", header: "<math.h>", noSideEffect.}
  Source Edit
proc sin(x: float64): float64 {...}{.importc: "sin", header: "<math.h>", noSideEffect.}
Computes the sine of x.
echo sin(PI / 6) ## 0.4999999999999999
echo sin(degToRad(90.0)) ## 1.0
  Source Edit
proc cos(x: float32): float32 {...}{.importc: "cosf", header: "<math.h>", noSideEffect.}
  Source Edit
proc cos(x: float64): float64 {...}{.importc: "cos", header: "<math.h>", noSideEffect.}
Computes the cosine of x.
echo cos(2 * PI) ## 1.0
echo cos(degToRad(60.0)) ## 0.5000000000000001
  Source Edit
proc tan(x: float32): float32 {...}{.importc: "tanf", header: "<math.h>", noSideEffect.}
  Source Edit
proc tan(x: float64): float64 {...}{.importc: "tan", header: "<math.h>", noSideEffect.}
Computes the tangent of x.
echo tan(degToRad(45.0)) ## 0.9999999999999999
echo tan(PI / 4) ## 0.9999999999999999
  Source Edit
proc sinh(x: float32): float32 {...}{.importc: "sinhf", header: "<math.h>", noSideEffect.}
  Source Edit
proc sinh(x: float64): float64 {...}{.importc: "sinh", header: "<math.h>", noSideEffect.}
Computes the hyperbolic sine of x.
echo sinh(1.0) ## 1.175201193643801
  Source Edit
proc cosh(x: float32): float32 {...}{.importc: "coshf", header: "<math.h>", noSideEffect.}
  Source Edit
proc cosh(x: float64): float64 {...}{.importc: "cosh", header: "<math.h>", noSideEffect.}
Computes the hyperbolic cosine of x.
echo cosh(1.0) ## 1.543080634815244
  Source Edit
proc tanh(x: float32): float32 {...}{.importc: "tanhf", header: "<math.h>", noSideEffect.}
  Source Edit
proc tanh(x: float64): float64 {...}{.importc: "tanh", header: "<math.h>", noSideEffect.}
Computes the hyperbolic tangent of x.
echo tanh(1.0) ## 0.7615941559557649
  Source Edit
proc arccos(x: float32): float32 {...}{.importc: "acosf", header: "<math.h>", noSideEffect.}
  Source Edit
proc arccos(x: float64): float64 {...}{.importc: "acos", header: "<math.h>", noSideEffect.}
Computes the arc cosine of x.
echo arccos(1.0) ## 0.0
  Source Edit
proc arcsin(x: float32): float32 {...}{.importc: "asinf", header: "<math.h>", noSideEffect.}
  Source Edit
proc arcsin(x: float64): float64 {...}{.importc: "asin", header: "<math.h>", noSideEffect.}
Computes the arc sine of x.   Source Edit
proc arctan(x: float32): float32 {...}{.importc: "atanf", header: "<math.h>", noSideEffect.}
  Source Edit
proc arctan(x: float64): float64 {...}{.importc: "atan", header: "<math.h>", noSideEffect.}
Calculate the arc tangent of x.
echo arctan(1.0) ## 0.7853981633974483
echo radToDeg(arctan(1.0)) ## 45.0
  Source Edit
proc arctan2(y, x: float32): float32 {...}{.importc: "atan2f", header: "<math.h>",
                                  noSideEffect.}
  Source Edit
proc arctan2(y, x: float64): float64 {...}{.importc: "atan2", header: "<math.h>", noSideEffect.}
Calculate the arc tangent of y / x. arctan2 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).
echo arctan2(1.0, 0.0) ## 1.570796326794897
echo radToDeg(arctan2(1.0, 0.0)) ## 90.0
  Source Edit
proc arcsinh(x: float32): float32 {...}{.importc: "asinhf", header: "<math.h>", noSideEffect.}
  Source Edit
proc arcsinh(x: float64): float64 {...}{.importc: "asinh", header: "<math.h>", noSideEffect.}
Computes the inverse hyperbolic sine of x.   Source Edit
proc arccosh(x: float32): float32 {...}{.importc: "acoshf", header: "<math.h>", noSideEffect.}
  Source Edit
proc arccosh(x: float64): float64 {...}{.importc: "acosh", header: "<math.h>", noSideEffect.}
Computes the inverse hyperbolic cosine of x.   Source Edit
proc arctanh(x: float32): float32 {...}{.importc: "atanhf", header: "<math.h>", noSideEffect.}
  Source Edit
proc arctanh(x: float64): float64 {...}{.importc: "atanh", header: "<math.h>", noSideEffect.}
Computes the inverse hyperbolic tangent of x.   Source Edit
proc cot[T: float32 | float64](x: T): T {...}{.noSideEffect.}
Computes the cotangent of x.   Source Edit
proc sec[T: float32 | float64](x: T): T {...}{.noSideEffect.}
Computes the secant of x.   Source Edit
proc csc[T: float32 | float64](x: T): T {...}{.noSideEffect.}
Computes the cosecant of x.   Source Edit
proc coth[T: float32 | float64](x: T): T {...}{.noSideEffect.}
Computes the hyperbolic cotangent of x.   Source Edit
proc sech[T: float32 | float64](x: T): T {...}{.noSideEffect.}
Computes the hyperbolic secant of x.   Source Edit
proc csch[T: float32 | float64](x: T): T {...}{.noSideEffect.}
Computes the hyperbolic cosecant of x.   Source Edit
proc arccot[T: float32 | float64](x: T): T {...}{.noSideEffect.}
Computes the inverse cotangent of x.   Source Edit
proc arcsec[T: float32 | float64](x: T): T {...}{.noSideEffect.}
Computes the inverse secant of x.   Source Edit
proc arccsc[T: float32 | float64](x: T): T {...}{.noSideEffect.}
Computes the inverse cosecant of x.   Source Edit
proc arccoth[T: float32 | float64](x: T): T {...}{.noSideEffect.}
Computes the inverse hyperbolic cotangent of x.   Source Edit
proc arcsech[T: float32 | float64](x: T): T {...}{.noSideEffect.}
Computes the inverse hyperbolic secant of x.   Source Edit
proc arccsch[T: float32 | float64](x: T): T {...}{.noSideEffect.}
Computes the inverse hyperbolic cosecant of x.   Source Edit
proc hypot(x, y: float32): float32 {...}{.importc: "hypotf", header: "<math.h>", noSideEffect.}
  Source Edit
proc hypot(x, y: float64): float64 {...}{.importc: "hypot", header: "<math.h>", noSideEffect.}
Computes the hypotenuse of a right-angle triangle with x and y as its base and height. Equivalent to sqrt(x*x + y*y).
echo hypot(4.0, 3.0) ## 5.0
  Source Edit
proc pow(x, y: float32): float32 {...}{.importc: "powf", header: "<math.h>", noSideEffect.}
  Source Edit
proc pow(x, y: float64): float64 {...}{.importc: "pow", header: "<math.h>", noSideEffect.}

computes x to power raised of y.

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

echo pow(16.0, 0.5) ## 4.0
  Source Edit
proc erf(x: float32): float32 {...}{.importc: "erff", header: "<math.h>", noSideEffect.}
  Source Edit
proc erf(x: float64): float64 {...}{.importc: "erf", header: "<math.h>", noSideEffect.}
Computes the error function for x.   Source Edit
proc erfc(x: float32): float32 {...}{.importc: "erfcf", header: "<math.h>", noSideEffect.}
  Source Edit
proc erfc(x: float64): float64 {...}{.importc: "erfc", header: "<math.h>", noSideEffect.}
Computes the complementary error function for x.   Source Edit
proc gamma(x: float32): float32 {...}{.importc: "tgammaf", header: "<math.h>", noSideEffect.}
  Source Edit
proc gamma(x: float64): float64 {...}{.importc: "tgamma", header: "<math.h>", noSideEffect.}
Computes the the gamma function for x.   Source Edit
proc tgamma(x: float32): float32 {...}{.deprecated: "use gamma instead",
                               importc: "tgammaf", header: "<math.h>", noSideEffect.}
  Source Edit
proc tgamma(x: float64): float64 {...}{.deprecated: "use gamma instead", importc: "tgamma",
                               header: "<math.h>", noSideEffect.}
The gamma function Deprecated since version 0.19.0: Use gamma instead.   Source Edit
proc lgamma(x: float32): float32 {...}{.importc: "lgammaf", header: "<math.h>", noSideEffect.}
  Source Edit
proc lgamma(x: float64): float64 {...}{.importc: "lgamma", header: "<math.h>", noSideEffect.}
Computes the natural log of the gamma function for x.   Source Edit
proc floor(x: float32): float32 {...}{.importc: "floorf", header: "<math.h>", noSideEffect.}
  Source Edit
proc floor(x: float64): float64 {...}{.importc: "floor", header: "<math.h>", noSideEffect.}
Computes the floor function (i.e., the largest integer not greater than x).
echo floor(-3.5) ## -4.0
  Source Edit
proc ceil(x: float32): float32 {...}{.importc: "ceilf", header: "<math.h>", noSideEffect.}
  Source Edit
proc ceil(x: float64): float64 {...}{.importc: "ceil", header: "<math.h>", noSideEffect.}
Computes the ceiling function (i.e., the smallest integer not less than x).
echo ceil(-2.1) ## -2.0
  Source Edit
proc trunc(x: float32): float32 {...}{.importc: "truncf", header: "<math.h>", noSideEffect.}
  Source Edit
proc trunc(x: float64): float64 {...}{.importc: "trunc", header: "<math.h>", noSideEffect.}
Truncates x to the decimal point.
echo trunc(PI) # 3.0
echo trunc(-1.85) # -1.0
  Source Edit
proc fmod(x, y: float32): float32 {...}{.deprecated: "use mod instead", importc: "fmodf",
                               header: "<math.h>", noSideEffect.}
  Source Edit
proc fmod(x, y: float64): float64 {...}{.deprecated: "use mod instead", importc: "fmod",
                               header: "<math.h>", noSideEffect.}
Computes the remainder of x divided by y. Deprecated since version 0.19.0: Use the mod operator instead.   Source Edit
proc `mod`(x, y: float32): float32 {...}{.importc: "fmodf", header: "<math.h>", noSideEffect.}
  Source Edit
proc `mod`(x, y: float64): float64 {...}{.importc: "fmod", header: "<math.h>", noSideEffect.}
Computes the modulo operation for float values (the remainder of x divided by y).
( 6.5 mod  2.5) ==  1.5
(-6.5 mod  2.5) == -1.5
( 6.5 mod -2.5) ==  1.5
(-6.5 mod -2.5) == -1.5
  Source Edit
proc round[T: float32 | float64](x: T; places: int = 0): T {...}{.noSideEffect.}

Round a floating point number.

This function is NOT reliable. Floating point numbers cannot hold non integer decimals precisely. 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.350000000000001421.... If places is negative, round to the left of the decimal place, e.g. round(537.345, -1) -> 540.0

  Source Edit
proc floorDiv[T: SomeInteger](x, y: T): T {...}{.noSideEffect.}
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.
echo floorDiv( 13,  3) #  4
echo floorDiv(-13,  3) # -5
echo floorDiv( 13, -3) # -5
echo floorDiv(-13, -3) #  4
  Source Edit
proc floorMod[T: SomeNumber](x, y: T): T {...}{.noSideEffect.}
Floor modulus is conceptually defined as x - (floorDiv(x, y) * y). This proc behaves the same as the % operator in Python.
echo floorMod( 13,  3) #  1
echo floorMod(-13,  3) #  2
echo floorMod( 13, -3) # -2
echo floorMod(-13, -3) # -1
  Source Edit
proc c_frexp(x: float32; exponent: var int32): float32 {...}{.importc: "frexp",
    header: "<math.h>", noSideEffect.}
  Source Edit
proc c_frexp(x: float64; exponent: var int32): float64 {...}{.importc: "frexp",
    header: "<math.h>", noSideEffect.}
  Source Edit
proc frexp[T, U](x: T; exponent: var U): T {...}{.noSideEffect.}
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.
var x : int
echo frexp(5.0, x) # 0.625
echo x # 3
  Source Edit
proc log2(x: float32): float32 {...}{.importc: "log2f", header: "<math.h>", noSideEffect.}
  Source Edit
proc log2(x: float64): float64 {...}{.importc: "log2", header: "<math.h>", noSideEffect.}
Computes the binary logarithm (base 2) of x   Source Edit
proc splitDecimal[T: float32 | float64](x: T): tuple[intpart: T, floatpart: T] {...}{.
    noSideEffect.}

Breaks x into an integer 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.

echo splitDecimal(5.25) # (intpart: 5.0, floatpart: 0.25)
  Source Edit
proc degToRad[T: float32 | float64](d: T): T {...}{.inline.}
Convert from degrees to radians
echo degToRad(180.0) # 3.141592653589793
  Source Edit
proc radToDeg[T: float32 | float64](d: T): T {...}{.inline.}
Convert from radians to degrees   Source Edit
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.
echo sgn(-5) # 1
echo sgn(-4.1) # -1
  Source Edit
proc `^`[T](x: T; y: Natural): T
Computes x to the power y. x must be non-negative, use pow for negative exponents.
echo 2 ^ 3 # 8
  Source Edit
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."   Source Edit
proc gcd(x, y: SomeInteger): SomeInteger
Computes the greatest common (positive) divisor of x and y. Using binary GCD (aka Stein's) algorithm.
echo gcd(24, 30) # 6
  Source Edit
proc lcm[T](x, y: T): T
Computes the least common multiple of x and y.
echo lcm(24, 30) # 120
  Source Edit