kex docs Standard Library

Math

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).

PI constant

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

Examples
Math.PI   # => 3.141592653589793

Degrees to radians

let radians(deg: Float) -> Float = deg * Math.PI / 180.0

E constant

The base of the natural logarithm.

Examples
Math.E             # => 2.718281828459045
Math.log(Math.E)   # => 1.0

sqrt

sqrt(x: Number) -> Float

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

Parameters
x
a non-negative number

Returns 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))

cbrt

cbrt(x: Number) -> Float

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

Parameters
x
any number

Returns the cube root

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

sin

sin(x: Number) -> Float

Returns the sine of x, given in radians.

Parameters
x
the angle in radians

Returns 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)

cos

cos(x: Number) -> Float

Returns the cosine of x, given in radians.

Parameters
x
the angle in radians

Returns the cosine

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

tan

tan(x: Number) -> Float

Returns the tangent of x, given in radians.

Parameters
x
the angle in radians

Returns the tangent

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

asin

asin(x: Number) -> Float

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

Parameters
x
a value in -1..1

Returns the angle in radians

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

acos

acos(x: Number) -> Float

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

Parameters
x
a value in -1..1

Returns the angle in radians

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

atan

atan(x: Number) -> Float

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.

Parameters
x
any number

Returns the angle in radians

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

atan2

atan2(y: Number, x: Number) -> Float

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.

Parameters
y
the vertical component
x
the horizontal component

Returns 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

sinh

sinh(x: Number) -> Float

Returns the hyperbolic sine of x.

Parameters
x
any number

Returns the hyperbolic sine

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

cosh

cosh(x: Number) -> Float

Returns the hyperbolic cosine of x.

Parameters
x
any number

Returns the hyperbolic cosine

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

tanh

tanh(x: Number) -> Float

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

Parameters
x
any number

Returns the hyperbolic tangent

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

log

log(x: Number) -> Float
log(x: Number, base: Number) -> Float

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.

Parameters
x
a positive number
base
the logarithm base; omitted for base e

Returns 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

log2

log2(x: Number) -> Float

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

Parameters
x
a positive number

Returns 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

log10

log10(x: Number) -> Float

Returns the base-10 logarithm of x.

Parameters
x
a positive number

Returns the base-10 logarithm

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

exp

exp(x: Number) -> Float

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.

Parameters
x
the exponent

Returns 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)

pow

pow(x: Number, y: Number) -> Float

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.

Parameters
x
the base
y
the exponent

Returns 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)

abs

abs(x: Number) -> Number

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.

Parameters
x
any number

Returns the absolute value

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

floor

floor(x: Number) -> Integer

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

Parameters
x
any number

Returns the floor

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

ceil

ceil(x: Number) -> Integer

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

Parameters
x
any number

Returns the ceiling

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

hypot

hypot(x: Number, y: Number) -> Float

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

Parameters
x
the first leg
y
the second leg

Returns 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)