/Nim

# Module math

Constructive mathematics is naturally typed. -- Simon Thompson

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

## 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.}`
`proc radToDeg[T: float32 | float64](d: T): T {.inline.}`
`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`.