kex docs Standard Library 0.4.0-alpha kex.run ↗

Mathprelude

module Math

Mathematical constants and functions.

All trigonometric functions work in radians. Every function here accepts a Number (an Integer or a Float) and the transcendental ones answer with a Float.

A Kex Float is always finite, so a domain error (Math.sqrt(-1.0)) or an overflow (Math.exp(1000.0)) raises rather than producing NaN or Infinity: the same rule the BEAM enforces, where those two values cannot exist at all. There is no non-finite float to test for afterwards.

Math.sqrt(2.0)              # => 1.4142135623730951
Math.hypot(3.0, 4.0)        # => 5.0
Math.sin(Math.PI / 2.0)     # => 1.0

The everyday operations on a single number: abs, floor, ceil, round, sqrt: are also methods on Integer and Float, which usually reads better in a chain: x.abs over Math.abs(x).

constant PI ?

The ratio of a circle's circumference to its diameter.

constant E ?

The base of the natural logarithm.

function sqrt

Returns the square root of x. Raises for a negative x, which has no real root.

sqrt(x) : Number -> Float
Parameters
x Number
a non-negative number

Returns: Float — the square root

Examples
Math.sqrt(9.0)    # => 3.0
Math.sqrt(2.0)    # => 1.4142135623730951
Math.sqrt(-1.0)   # raises: Math.sqrt: undefined result (NaN)

Distance between two points

Math.sqrt((x2 - x1) * (x2 - x1) + (y2 - y1) * (y2 - y1))

function cbrt

Returns the cube root of x. Unlike sqrt, negative input is fine: a negative number has a real cube root.

cbrt(x) : Number -> Float
Parameters
x Number
any number

Returns: Float — the cube root

Examples
Math.cbrt(27.0)    # => 3.0
Math.cbrt(-8.0)    # => -2.0

function sin

Returns the sine of x, given in radians.

sin(x) : Number -> Float
Parameters
x Number
the angle in radians

Returns: Float — the sine

Examples
Math.sin(0.0)             # => 0.0
Math.sin(Math.PI / 2.0)   # => 1.0

A point on a circle

let y = centerY + radius * Math.sin(angle)

function cos

Returns the cosine of x, given in radians.

cos(x) : Number -> Float
Parameters
x Number
the angle in radians

Returns: Float — the cosine

Examples
Math.cos(0.0)        # => 1.0
Math.cos(Math.PI)    # => -1.0

function tan

Returns the tangent of x, given in radians.

tan(x) : Number -> Float
Parameters
x Number
the angle in radians

Returns: Float — the tangent

Examples
Math.tan(0.0)             # => 0.0
Math.tan(Math.PI / 4.0)   # => 1.0

function asin

Returns the arc sine of x in radians, in the range -π/2 to π/2.

asin(x) : Number -> Float
Parameters
x Number
a value in -1..1

Returns: Float — the angle in radians

Examples
Math.asin(0.0)   # => 0.0
Math.asin(1.0)   # => 1.5707963267948966

function acos

Returns the arc cosine of x in radians, in the range 0 to π.

acos(x) : Number -> Float
Parameters
x Number
a value in -1..1

Returns: Float — the angle in radians

Examples
Math.acos(1.0)    # => 0.0
Math.acos(0.0)    # => 1.5707963267948966

function atan

Returns the arc tangent of x in radians, in the range -π/2 to π/2.

Use atan2 when you have both coordinates of a vector: it can tell the quadrant apart, and this cannot.

atan(x) : Number -> Float
Parameters
x Number
any number

Returns: Float — the angle in radians

Examples
Math.atan(0.0)   # => 0.0
Math.atan(1.0)   # => 0.7853981633974483

function atan2

Returns the angle of the vector (x, y) in radians, from -π to π.

Both signs are taken into account, so the result lands in the correct quadrant, which is why this, not atan, is what you want for converting a vector to an angle. Note the argument order: y first.

atan2(y, x) : Number -> Number -> Float
Parameters
y Number
the vertical component
x Number
the horizontal component

Returns: Float — the angle in radians

Examples
Math.atan2(1.0, 1.0)    # => 0.7853981633974483    (45°)
Math.atan2(1.0, -1.0)   # => 2.356194490192345     (135°)

The bearing from one point to another, in degrees

Math.atan2(y2 - y1, x2 - x1) * 180.0 / Math.PI

function sinh

Returns the hyperbolic sine of x.

sinh(x) : Number -> Float
Parameters
x Number
any number

Returns: Float — the hyperbolic sine

Examples
Math.sinh(0.0)   # => 0.0
Math.sinh(1.0)   # => 1.1752011936438014

function cosh

Returns the hyperbolic cosine of x.

cosh(x) : Number -> Float
Parameters
x Number
any number

Returns: Float — the hyperbolic cosine

Examples
Math.cosh(0.0)   # => 1.0
Math.cosh(1.0)   # => 1.5430806348152437

function tanh

Returns the hyperbolic tangent of x, always between -1 and 1.

tanh(x) : Number -> Float
Parameters
x Number
any number

Returns: Float — the hyperbolic tangent

Examples
Math.tanh(0.0)   # => 0.0
Math.tanh(1.0)   # => 0.7615941559557649

function log

Returns the natural logarithm of x: its logarithm to base e. With a second argument, returns the logarithm to that base instead.

Raises for x of zero or less, which has no real logarithm.

log(x) : Number -> Float
log(x) : Number -> Number -> Float
Parameters
x Number
a positive number
base Number
the logarithm base; omitted for base e

Returns: Float — the logarithm

Examples
Math.log(Math.E)     # => 1.0
Math.log(8.0, 2.0)   # => 3.0

How many digits a number has

Math.log10(n.to(Float).or(1.0)).floor + 1

function log2

Returns the base-2 logarithm of x. The same as Math.log(x, 2.0), and more direct.

log2(x) : Number -> Float
Parameters
x Number
a positive number

Returns: Float — the base-2 logarithm

Examples
Math.log2(8.0)      # => 3.0
Math.log2(1024.0)   # => 10.0

Bits needed to represent n distinct values

Math.log2(n.to(Float).or(1.0)).ceil

function log10

Returns the base-10 logarithm of x.

log10(x) : Number -> Float
Parameters
x Number
a positive number

Returns: Float — the base-10 logarithm

Examples
Math.log10(1000.0)   # => 3.0
Math.log10(1.0)      # => 0.0

function exp

Returns e raised to the power x: the inverse of Math.log.

Raises on overflow, which for a double happens a little past x of 709.

exp(x) : Number -> Float
Parameters
x Number
the exponent

Returns: Float — e to the power x

Examples
Math.exp(0.0)   # => 1.0
Math.exp(1.0)   # => 2.718281828459045

Exponential decay

let remaining = initial * Math.exp(-rate * elapsed)

function pow

Returns x raised to the power y.

The result is always a Float, even for whole arguments, so round it when you need an integer back.

pow(x, y) : Number -> Number -> Float
Parameters
x Number
the base
y Number
the exponent

Returns: Float — x to the power y

Examples
Math.pow(2.0, 10.0)        # => 1024.0
Math.pow(2.0, 0.5)         # => 1.4142135623730951
Math.pow(2.0, 10.0).round  # => 1024

Compound growth

principal * Math.pow(1.0 + rate, years)

function abs

Returns the magnitude of x, discarding its sign. The type is preserved: an Integer in gives an Integer out.

x.abs is the same thing as a method, and usually reads better.

abs(x) : Number -> Number
Parameters
x Number
any number

Returns: Number — the absolute value

Examples
Math.abs(-5)      # => 5
Math.abs(-2.5)    # => 2.5

function floor

Returns the largest integer that is not greater than x: rounding toward negative infinity.

floor(x) : Number -> Integer
Parameters
x Number
any number

Returns: Integer — the floor

Examples
Math.floor(3.7)    # => 3
Math.floor(-3.2)   # => -4

function ceil

Returns the smallest integer that is not less than x: rounding toward positive infinity.

ceil(x) : Number -> Integer
Parameters
x Number
any number

Returns: Integer — the ceiling

Examples
Math.ceil(3.2)     # => 4
Math.ceil(-3.7)    # => -3

function hypot

Returns the Euclidean distance sqrt(x*x y*y)+, computed so that large values do not overflow on the way.

hypot(x, y) : Number -> Number -> Float
Parameters
x Number
the first leg
y Number
the second leg

Returns: Float — the hypotenuse

Examples
Math.hypot(3.0, 4.0)     # => 5.0
Math.hypot(5.0, 12.0)    # => 13.0

The length of a vector

Math.hypot(velocity.x, velocity.y)