Math module

The Math module gathers the mathematical functions: absolute value, rounding, square root, power, minimum, maximum and average, sign, sine, cosine and tangent, and a 3D rotation of many points at once. It also has the most common constants, such as Math.PI.

use Math

The functions are called with the dot: Math.sqrt(9). They work the same on Windows and on every board.

Functions

Function	What it does	Returns
abs(x)	The absolute value.	An integer with an integer; a decimal with a decimal
ceil(x)	Rounds up.	An integer
floor(x)	Rounds down.	An integer
round(x)	Rounds to the nearest.	An integer with an integer; a decimal with a decimal
sqrt(x)	The square root.	A decimal
pow(base, exponent)	The power.	A decimal
max(...)	The largest of some numbers.	A decimal
min(...)	The smallest of some numbers.	A decimal
average(...)	The average of some numbers.	A decimal
sign(x)	The sign: -1, 0 or 1.	An integer
signCopy(x, y)	The absolute value of x with the sign of y.	A decimal
sin(x), cos(x), tan(x)	Sine, cosine and tangent, in radians.	A decimal
rotateBatch(matrix, points)	Rotates many 3D points with a matrix.	nil

The arguments can be integers or decimals. The errors are thrown, so try catches them:

• with the wrong number of arguments, ERR_INVALID_ARG_NUMBER;
• with something that is not a number, ERR_TYPE_MISMATCH.

A decimal with no decimal part is printed without it: Math.round(3.6) prints 4, but it is a decimal.

abs

abs(x) returns the absolute value of a number: the number without its sign. With an integer it returns an integer, and with a decimal, a decimal.

use Math

println(Math.abs(-5))     // 5
println(Math.abs(-2.5))   // 2.5
println(Math.abs(0))      // 0

ceil

ceil(x) rounds up: it returns the smallest integer that is not smaller than x. It always returns an integer.

use Math

println(Math.ceil(3.14159))    // 4
println(Math.ceil(-3.14159))   // -3

floor

floor(x) rounds down: it returns the largest integer that is not larger than x. It always returns an integer.

use Math

println(Math.floor(4.9))    // 4
println(Math.floor(4.1))    // 4
println(Math.floor(-4.1))   // -5

round

round(x) rounds to the nearest integer; halves go away from zero. With an integer it returns an integer, and with a decimal, a decimal. It takes a single argument: it does not round to a number of decimals.

use Math

println(Math.round(3.14159))   // 3
println(Math.round(3.6))       // 4
println(Math.round(2.5))       // 3
println(Math.round(-2.5))      // -3

If you need it as an integer (for example, for an index), use Math.floor, Math.ceil or int().

sqrt

sqrt(x) returns the square root, as a decimal. With a negative number it throws ERR_INVALID_VALUE.

use Math

println(Math.sqrt(16))     // 4
println(Math.sqrt(2.25))   // 1.5

pow

pow(base, exponent) returns base raised to exponent, as a decimal. The exponent can be a decimal or negative.

use Math

println(Math.pow(2, 10))    // 1024
println(Math.pow(9, 0.5))   // 3
println(Math.pow(2, -1))    // 0.5

max

max(...) returns the largest of the numbers you give it, as a decimal. It takes several numbers or a list. With no arguments, or with an empty list, it returns 0.

use Math

println(Math.max(3, 7, 2))       // 7
println(Math.max([3, 7.5, 2]))   // 7.5

An element that is not a number throws ERR_TYPE_MISMATCH.

min

min(...) returns the smallest of the numbers you give it, as a decimal. It works like max().

use Math

println(Math.min(3, 7, 2))   // 2

average

average(...) returns the average of the numbers you give it, as a decimal. It takes several numbers or a list. With no arguments, or with an empty list, it returns 0.

use Math

var marks = [1, 2, 3, 4, 5]
println(Math.average(marks))          // 3
println(Math.average(1, 2))           // 1.5

sign

sign(x) returns the sign of a number: -1 if it is negative, 1 if it is positive and 0 if it is zero. It always returns an integer.

use Math

println(Math.sign(-7))    // -1
println(Math.sign(0.5))   // 1
println(Math.sign(0))     // 0

signCopy

signCopy(x, y) returns the absolute value of x with the sign of y, as a decimal. If y is negative, the result is negative; if not (also with 0), positive.

use Math

println(Math.signCopy(5, -1))     // -5
println(Math.signCopy(-3.5, 2))   // 3.5

sin, cos and tan

sin(x), cos(x) and tan(x) return the sine, the cosine and the tangent of an angle in radians, as a decimal. To go from degrees to radians, multiply by PI and divide by 180.

use Math

println(Math.cos(0))                          // 1
println(Math.sin(Math.PI / 2))                // 1
var degrees = 30
println(Math.sin(degrees * Math.PI / 180))    // 0.49999999999999994

There are no more trigonometric functions: no asin, acos, atan or atan2, and no logarithms or exponential.

rotateBatch

rotateBatch(matrix, points) multiplies many 3D points by a 3 x 3 rotation matrix, all at once and much faster than with a JARU loop. It changes the points in place and returns nil.

Parameter	What it is
matrix	An array with the 9 numbers of the matrix, row by row: var m[3][3], or an array of 9 elements.
points	An array of 3 rows and N columns: var p[3][N]. Row 0 holds the X values, row 1 the Y values and row 2 the Z values. It rotates the N columns.

They have to be arrays, not lists. If matrix has fewer than 9 elements, or points does not have 2 dimensions with at least 3 rows, it throws ERR_INVALID_VALUE. After the rotation, all the points are decimals.

use Math

// A 90-degree rotation around the Z axis
var c = Math.cos(PI / 2)
var s = Math.sin(PI / 2)
var m[3][3]
m[0][0] = c
m[0][1] = 0 - s
m[0][2] = 0
m[1][0] = s
m[1][1] = c
m[1][2] = 0
m[2][0] = 0
m[2][1] = 0
m[2][2] = 1

// Two points: (10, 0, 5) and (0, 20, 0)
var p[3][2]
p[0][0] = 10
p[1][0] = 0
p[2][0] = 5
p[0][1] = 0
p[1][1] = 20
p[2][1] = 0

Math.rotateBatch(m, p)
for (var i = 0; i < 2; i++)
    println(Math.round(p[0][i]), ", ", Math.round(p[1][i]), ", ", Math.round(p[2][i]))
end

What it prints:

0, 10, 5
-20, 0, 0

The VectorBalls example, which comes with JARU IDE, uses it to rotate shapes of 100 balls in every frame.

Constants

Constant	What it is	What println prints
Math.PI	The number π	3.141592653589793
Math.E	The number e	2.718281828459045
Math.LOG2E	The base-2 logarithm of e	1.4426950408889634
Math.LOG10E	The base-10 logarithm of e	0.4342944819032518
Math.SQRT2	The square root of 2	1.4142135623730951
Math.LN2	The natural logarithm of 2	0.6931471805599453
Math.LN10	The natural logarithm of 10	2.302585092994046

PI and SQRT2 are also constants of the language: you can use them without Math. and without use Math, with the same value.

println(PI)      // 3.141592653589793
println(SQRT2)   // 1.4142135623730951

Full example

How far a shot at 20 m/s gets depending on the angle, and with which angle it gets furthest.

use Math

const SPEED = 20   // meters per second
const GRAVITY = 9.8

func range(degrees)
    var angle = degrees * PI / 180   // to radians
    return Math.pow(SPEED, 2) * Math.sin(2 * angle) / GRAVITY
end

var angles = [15, 30, 45, 60, 75]
var best = 0
var bestAngle = 0
foreach (var d in angles)
    var r = range(d)
    println(d, " degrees: ", Math.round(r), " m")
    if (r > best) then
        best = r
        bestAngle = d
    end
end
println("The one that gets furthest: ", bestAngle, " degrees")

What it prints:

15 degrees: 20 m
30 degrees: 35 m
45 degrees: 41 m
60 degrees: 35 m
75 degrees: 20 m
The one that gets furthest: 45 degrees

Pitfalls and known issues

• Angles are in radians, not degrees: degrees * PI / 180.
• max, min, average, sqrt and pow always return a decimal, also with integers. A decimal does not work as a list index (ERR_TYPE_MISMATCH): turn it into an integer with int().
• round() with a decimal returns a decimal, and halves go outwards: Math.round(-2.5) gives -3.
• Decimals are printed with all their digits: Math.sin(30 * PI / 180) prints 0.49999999999999994. To show them, round them.
• rotateBatch asks for arrays, not lists.
• asin, acos, atan, atan2, exp and log are missing.

All the known issues of JARU, together, are in Known issues.