[role="xpack"]
[[canvas-tinymath-functions]]
=== TinyMath functions

TinyMath provides a set of functions that can be used with the Canvas expression
language to perform complex math calculations. Read on for detailed information about
the functions available in TinyMath, including what parameters each function accepts,
the return value of that function, and examples of how each function behaves.

Most of the functions accept arrays and apply JavaScript Math methods to
each element of that array. For the functions that accept multiple arrays as
parameters, the function generally does the calculation index by index.

Any function can be wrapped by another function as long as the return type
of the inner function matches the acceptable parameter type of the outer function.

[float]
=== abs( a )

Calculates the absolute value of a number. For arrays, the function will be
applied index-wise to each element.

[cols="3*^<"]
|===
|Param |Type |Description

|a
|number \| Array.<number>
|a number or an array of numbers
|===

*Returns*: `number` | `Array.<number>`. The absolute value of `a`. Returns
an array with the absolute values of each element if `a` is an array.

*Example*
[source, js]
------------
abs(-1) // returns 1
abs(2) // returns 2
abs([-1 , -2, 3, -4]) // returns [1, 2, 3, 4]
------------

[float]
=== add( ...args )

Calculates the sum of one or more numbers/arrays passed into the function. If at
least one array of numbers is passed into the function, the function will calculate the sum by index.

[cols="3*^<"]
|===
|Param |Type |Description

|...args
|number \| Array.<number>
|one or more numbers or arrays of numbers
|===

*Returns*: `number` | `Array.<number>`. The sum of all numbers in `args` if `args`
contains only numbers. Returns an array of sums of the elements at each index,
including all scalar numbers in `args` in the calculation at each index if `args`
contains at least one array.

*Throws*: `'Array length mismatch'` if `args` contains arrays of different lengths

*Example*
[source, js]
------------
add(1, 2, 3) // returns 6
add([10, 20, 30, 40], 10, 20, 30) // returns [70, 80, 90, 100]
add([1, 2], 3, [4, 5], 6) // returns [(1 + 3 + 4 + 6), (2 + 3 + 5 + 6)] = [14, 16]
------------

[float]
=== cbrt( a )

Calculates the cube root of a number. For arrays, the function will be applied
index-wise to each element.

[cols="3*^<"]
|===
|Param |Type |Description

|a
|number \| Array.<number>
|a number or an array of numbers
|===

*Returns*: `number` | `Array.<number>`. The cube root of `a`. Returns an array with
the cube roots of each element if `a` is an array.

*Example*
[source, js]
------------
cbrt(-27) // returns -3
cbrt(94) // returns 4.546835943776344
cbrt([27, 64, 125]) // returns [3, 4, 5]
------------

[float]
=== ceil( a )

Calculates the ceiling of a number, i.e., rounds a number towards positive infinity.
For arrays, the function will be applied index-wise to each element.

[cols="3*^<"]
|===
|Param |Type |Description

|a
|number \| Array.<number>
|a number or an array of numbers
|===

*Returns*: `number` | `Array.<number>`. The ceiling of `a`. Returns an array with
the ceilings of each element if `a` is an array.

*Example*
[source, js]
------------
ceil(1.2) // returns 2
ceil(-1.8) // returns -1
ceil([1.1, 2.2, 3.3]) // returns [2, 3, 4]
------------

[float]
=== clamp( ...a, min, max )

Restricts value to a given range and returns closed available value. If only `min`
is provided, values are restricted to only a lower bound.

[cols="3*^<"]
|===
|Param |Type |Description

|...a
|number \| Array.<number>
|one or more numbers or arrays of numbers

|min
|number \| Array.<number>
|(optional) The minimum value this function will return.

|max
|number \| Array.<number>
|(optional) The maximum value this function will return.
|===

*Returns*: `number` | `Array.<number>`. The closest value between `min` (inclusive)
and `max` (inclusive). Returns an array with values greater than or equal to `min`
and less than or equal to `max` (if provided) at each index.

*Throws*:

- `'Array length mismatch'` if a `min` and/or `max` are arrays of different lengths

- `'Min must be less than max'` if `max` is less than `min`

*Example*
[source, js]
------------
clamp(1, 2, 3) // returns 2
clamp([10, 20, 30, 40], 15, 25) // returns [15, 20, 25, 25]
clamp(10, [15, 2, 4, 20], 25) // returns [15, 10, 10, 20]
clamp(35, 10, [20, 30, 40, 50]) // returns [20, 30, 35, 35]
clamp([1, 9], 3, [4, 5]) // returns [clamp([1, 3, 4]), clamp([9, 3, 5])] = [3, 5]
------------

[float]
=== count( a )

Returns the length of an array. Alias for size.

[cols="3*^<"]
|===
|Param |Type |Description

|a
|Array.<any>
|array of any values
|===

*Returns*: `number`. The length of the array.

*Throws*: `'Must pass an array'` if `a` is not an array.

*Example*
[source, js]
------------
count([]) // returns 0
count([-1, -2, -3, -4]) // returns 4
count(100) // returns 1
------------

[float]
=== cube( a )

Calculates the cube of a number. For arrays, the function will be applied
index-wise to each element.

[cols="3*^<"]
|===
|Param |Type |Description

|a
|number \| Array.<number>
|a number or an array of numbers
|===

*Returns*: `number` | `Array.<number>`. The cube of `a`. Returns an array
with the cubes of each element if `a` is an array.

*Example*
[source, js]
------------
cube(-3) // returns -27
cube([3, 4, 5]) // returns [27, 64, 125]
------------

[float]
=== divide( a, b )

Divides two numbers. If at least one array of numbers is passed into the function,
the function will be applied index-wise to each element.

[cols="3*^<"]
|===
|Param |Type |Description

|a
|number \| Array.<number>
|dividend, a number or an array of numbers

|b
|number \| Array.<number>
|divisor, a number or an array of numbers, b != 0
|===

*Returns*: `number` | `Array.<number>`. Returns the quotient of `a` and `b`
if both are numbers. Returns an array with the quotients applied index-wise to
each element if `a` or `b` is an array.

*Throws*:

- `'Array length mismatch'` if `a` and `b` are arrays with different lengths

- `'Cannot divide by 0'` if `b` equals 0 or contains 0

*Example*
[source, js]
------------
divide(6, 3) // returns 2
divide([10, 20, 30, 40], 10) // returns [1, 2, 3, 4]
divide(10, [1, 2, 5, 10]) // returns [10, 5, 2, 1]
divide([14, 42, 65, 108], [2, 7, 5, 12]) // returns [7, 6, 13, 9]
------------

[float]
=== exp( a )

Calculates _e^x_ where _e_ is Euler's number. For arrays, the function will be applied
index-wise to each element.

[cols="3*^<"]
|===
|Param |Type |Description

|a
|number \| Array.<number>
|a number or an array of numbers
|===

*Returns*: `number` | `Array.<number>`. Returns an array with the values of
`e^x` evaluated where `x` is each element of `a` if `a` is an array.

*Example*
[source, js]
------------
exp(2) // returns e^2 = 7.3890560989306495
exp([1, 2, 3]) // returns [e^1, e^2, e^3] = [2.718281828459045, 7.3890560989306495, 20.085536923187668]
------------

[float]
=== first( a )

Returns the first element of an array. If anything other than an array is passed
in, the input is returned.

[cols="3*^<"]
|===
|Param |Type |Description

|a
|Array.<any>
|array of any values
|===

*Returns*: `*`. The first element of `a`. Returns `a` if `a` is not an array.

*Example*
[source, js]
------------
first(2) // returns 2
first([1, 2, 3]) // returns 1
------------

[float]
=== fix( a )

Calculates the fix of a number, i.e., rounds a number towards 0. For arrays, the
function will be applied index-wise to each element.

[cols="3*^<"]
|===
|Param |Type |Description

|a
|number \| Array.<number>
|a number or an array of numbers
|===

*Returns*: `number` | `Array.<number>`. The fix of `a`. Returns an array with
the fixes for each element if `a` is an array.

*Example*
[source, js]
------------
fix(1.2) // returns 1
fix(-1.8) // returns -1
fix([1.8, 2.9, -3.7, -4.6]) // returns [1, 2, -3, -4]
------------

[float]
=== floor( a )

Calculates the floor of a number, i.e., rounds a number towards negative infinity.
For arrays, the function will be applied index-wise to each element.

[cols="3*^<"]
|===
|Param |Type |Description

|a
|number \| Array.<number>
|a number or an array of numbers
|===

*Returns*: `number` | `Array.<number>`. The floor of `a`. Returns an array
with the floor of each element if `a` is an array.

*Example*
[source, js]
------------
floor(1.8) // returns 1
floor(-1.2) // returns -2
floor([1.7, 2.8, 3.9]) // returns [1, 2, 3]
------------

[float]
=== last( a )

Returns the last element of an array. If anything other than an array is passed
in, the input is returned.

[cols="3*^<"]
|===
|Param |Type |Description

|a
|Array.<any>
|array of any values
|===

*Returns*: `*`. The last element of `a`. Returns `a` if `a` is not an array.

*Example*
[source, js]
------------
last(2) // returns 2
last([1, 2, 3]) // returns 3
------------

[float]
=== log( a, b )

Calculates the logarithm of a number. For arrays, the function will be applied
index-wise to each element.

[cols="3*^<"]
|===
|Param |Type |Description

|a
|number \| Array.<number>
|a number or an array of numbers, `a` must be greater than 0

|b
|Object
|(optional) base for the logarithm. If not provided a value, the default base is e, and the natural log is calculated.
|===

*Returns*: `number` | `Array.<number>`.  The logarithm of `a`. Returns an array
with the the logarithms of each element if `a` is an array.

*Throws*:

- `'Base out of range'` if `b` <= 0

- `'Must be greater than 0'` if `a` > 0

*Example*
[source, js]
------------
log(1) // returns 0
log(64, 8) // returns 2
log(42, 5) // returns 2.322344707681546
log([2, 4, 8, 16, 32], 2) // returns [1, 2, 3, 4, 5]
------------

[float]
=== log10( a )

Calculates the logarithm base 10 of a number. For arrays, the function will be
applied index-wise to each element.

[cols="3*^<"]
|===
|Param |Type |Description

|a
|number \| Array.<number>
|a number or an array of numbers, `a` must be greater than 0
|===

*Returns*: `number` | `Array.<number>`. The logarithm of `a`. Returns an array
with the the logarithms base 10 of each element if `a` is an array.

*Throws*: `'Must be greater than 0'` if `a` < 0

*Example*
[source, js]
------------
log(10) // returns 1
log(100) // returns 2
log(80) // returns 1.9030899869919433
log([10, 100, 1000, 10000, 100000]) // returns [1, 2, 3, 4, 5]
------------

[float]
=== max( ...args )

Finds the maximum value of one of more numbers/arrays of numbers passed into the function.
If at least one array of numbers is passed into the function, the function will
find the maximum by index.

[cols="3*^<"]
|===
|Param |Type |Description

|...args
|number \| Array.<number>
|one or more numbers or arrays of numbers
|===

*Returns*: `number` | `Array.<number>`. The maximum value of all numbers if
`args` contains only numbers. Returns an array with the the maximum values at each
index, including all scalar numbers in `args` in the calculation at each index if
`args` contains at least one array.

*Throws*: `'Array length mismatch'` if `args` contains arrays of different lengths

*Example*
[source, js]
------------
max(1, 2, 3) // returns 3
max([10, 20, 30, 40], 15) // returns [15, 20, 30, 40]
max([1, 9], 4, [3, 5]) // returns [max([1, 4, 3]), max([9, 4, 5])] = [4, 9]
------------

[float]
=== mean( ...args )

Finds the mean value of one of more numbers/arrays of numbers passed into the function.
If at least one array of numbers is passed into the function, the function will
find the mean by index.

[cols="3*^<"]
|===
|Param |Type |Description

|...args
|number \| Array.<number>
|one or more numbers or arrays of numbers
|===

*Returns*: `number` | `Array.<number>`. The mean value of all numbers if `args`
contains only numbers. Returns an array with the the mean values of each index,
including all scalar numbers in `args` in the calculation at each index if `args`
contains at least one array.

*Example*
[source, js]
------------
mean(1, 2, 3) // returns 2
mean([10, 20, 30, 40], 20) // returns [15, 20, 25, 30]
mean([1, 9], 5, [3, 4]) // returns [mean([1, 5, 3]), mean([9, 5, 4])] = [3, 6]
------------

[float]
=== median( ...args )

Finds the median value(s) of one of more numbers/arrays of numbers passed into the function.
If at least one array of numbers is passed into the function, the function will
find the median by index.

[cols="3*^<"]
|===
|Param |Type |Description

|...args
|number \| Array.<number>
|one or more numbers or arrays of numbers
|===

*Returns*: `number` | `Array.<number>`. The median value of all numbers if `args`
contains only numbers. Returns an array with the the median values of each index,
including all scalar numbers in `args` in the calculation at each index if `args`
contains at least one array.

*Example*
[source, js]
------------
median(1, 1, 2, 3) // returns 1.5
median(1, 1, 2, 2, 3) // returns 2
median([10, 20, 30, 40], 10, 20, 30) // returns [15, 20, 25, 25]
median([1, 9], 2, 4, [3, 5]) // returns [median([1, 2, 4, 3]), median([9, 2, 4, 5])] = [2.5, 4.5]
------------

[float]
=== min( ...args )

Finds the minimum value of one of more numbers/arrays of numbers passed into the function.
If at least one array of numbers is passed into the function, the function will
find the minimum by index.

[cols="3*^<"]
|===
|Param |Type |Description

|...args
|number \| Array.<number>
|one or more numbers or arrays of numbers
|===

*Returns*: `number` | `Array.<number>`. The minimum value of all numbers if
`args` contains only numbers. Returns an array with the the minimum values of each
index, including all scalar numbers in `args` in the calculation at each index if `a`
is an array.

*Throws*: `'Array length mismatch'` if `args` contains arrays of different lengths.

*Example*
[source, js]
------------
min(1, 2, 3) // returns 1
min([10, 20, 30, 40], 25) // returns [10, 20, 25, 25]
min([1, 9], 4, [3, 5]) // returns [min([1, 4, 3]), min([9, 4, 5])] = [1, 4]
------------

[float]
=== mod( a, b )

Remainder after dividing two numbers. If at least one array of numbers is passed
into the function, the function will be applied index-wise to each element.

[cols="3*^<"]
|===
|Param |Type |Description

|a
|number \| Array.<number>
|dividend, a number or an array of numbers

|b
|number \| Array.<number>
|divisor, a number or an array of numbers, b != 0
|===

*Returns*: `number` | `Array.<number>`. The remainder of `a` divided by `b` if
both are numbers. Returns an array with the the remainders applied index-wise to
each element if `a` or `b` is an array.

*Throws*:

- `'Array length mismatch'` if `a` and `b` are arrays with different lengths

- `'Cannot divide by 0'` if `b` equals 0 or contains 0

*Example*
[source, js]
------------
mod(10, 7) // returns 3
mod([11, 22, 33, 44], 10) // returns [1, 2, 3, 4]
mod(100, [3, 7, 11, 23]) // returns [1, 2, 1, 8]
mod([14, 42, 65, 108], [5, 4, 14, 2]) // returns [5, 2, 9, 0]
------------

[float]
=== mode( ...args )

Finds the mode value(s) of one of more numbers/arrays of numbers passed into the function.
If at least one array of numbers is passed into the function, the function will
find the mode by index.

[cols="3*^<"]
|===
|Param |Type |Description

|...args
|number \| Array.<number>
|one or more numbers or arrays of numbers
|===

*Returns*: `number` | `Array.<Array.<number>>`. An array of mode value(s) of all
numbers if `args` contains only numbers. Returns an array of arrays with mode value(s)
of each index, including all scalar numbers in `args` in the calculation at each index
if `args` contains at least one array.

*Example*
[source, js]
------------
mode(1, 1, 2, 3) // returns [1]
mode(1, 1, 2, 2, 3) // returns [1,2]
mode([10, 20, 30, 40], 10, 20, 30) // returns [[10], [20], [30], [10, 20, 30, 40]]
mode([1, 9], 1, 4, [3, 5]) // returns [mode([1, 1, 4, 3]), mode([9, 1, 4, 5])] = [[1], [4, 5, 9]]
------------

[float]
=== multiply( a, b )

Multiplies two numbers. If at least one array of numbers is passed into the function,
the function will be applied index-wise to each element.

[cols="3*^<"]
|===
|Param |Type |Description

|a
|number \| Array.<number>
|a number or an array of numbers

|b
|number \| Array.<number>
|a number or an array of numbers
|===

*Returns*: `number` | `Array.<number>`. The product of `a` and `b` if both are
numbers. Returns an array with the the products applied index-wise to each element
if `a` or `b` is an array.

*Throws*: `'Array length mismatch'` if `a` and `b` are arrays with different lengths

*Example*
[source, js]
------------
multiply(6, 3) // returns 18
multiply([10, 20, 30, 40], 10) // returns [100, 200, 300, 400]
multiply(10, [1, 2, 5, 10]) // returns [10, 20, 50, 100]
multiply([1, 2, 3, 4], [2, 7, 5, 12]) // returns [2, 14, 15, 48]
------------

[float]
=== pow( a, b )

Calculates the cube root of a number. For arrays, the function will be applied
index-wise to each element.

[cols="3*^<"]
|===
|Param |Type |Description

|a
|number \| Array.<number>
|a number or an array of numbers

|b
|number
|the power that `a` is raised to
|===

*Returns*: `number` | `Array.<number>`. `a` raised to the power of `b`. Returns
an array with the each element raised to the power of `b` if `a` is an array.

*Throws*: `'Missing exponent'` if `b` is not provided

*Example*
[source, js]
------------
pow(2,3) // returns 8
pow([1, 2, 3], 4) // returns [1, 16, 81]
------------

[float]
=== random( a, b )

Generates a random number within the given range where the lower bound is inclusive
and the upper bound is exclusive. If no numbers are passed in, it will return a
number between 0 and 1. If only one number is passed in, it will return a number
between 0 and the number passed in.

[cols="3*^<"]
|===
|Param |Type |Description

|a
|number
|(optional) must be greater than 0 if `b` is not provided

|b
|number
|(optional) must be greater than `a`
|===

*Returns*: `number`. A random number between 0 and 1 if no numbers are passed in.
Returns a random number between 0 and `a` if only one number is passed in. Returns
a random number between `a` and `b` if two numbers are passed in.

*Throws*: `'Min must be greater than max'` if `a` < 0 when only `a` is passed in
or if `a` > `b` when both `a` and `b` are passed in

*Example*
[source, js]
------------
random() // returns a random number between 0 (inclusive) and 1 (exclusive)
random(10) // returns a random number between 0 (inclusive) and 10 (exclusive)
random(-10,10) // returns a random number between -10 (inclusive) and 10 (exclusive)
------------

[float]
=== range( ...args )

Finds the range of one of more numbers/arrays of numbers passed into the function. If at
least one array of numbers is passed into the function, the function will find
the range by index.

[cols="3*^<"]
|===
|Param |Type |Description

|...args
|number \| Array.<number>
|one or more numbers or arrays of numbers
|===

*Returns*: `number` | `Array.<number>`. The range value of all numbers if `args`
contains only numbers. Returns an array with the range values at each index,
including all scalar numbers in `args` in the calculation at each index if `args`
contains at least one array.

*Example*
[source, js]
------------
range(1, 2, 3) // returns 2
range([10, 20, 30, 40], 15) // returns [5, 5, 15, 25]
range([1, 9], 4, [3, 5]) // returns [range([1, 4, 3]), range([9, 4, 5])] = [3, 5]
------------

[float]
=== range( ...args )

Finds the range of one of more numbers/arrays of numbers into the function. If at
least one array of numbers is passed into the function, the function will find
the range by index.

[cols="3*^<"]
|===
|Param |Type |Description

|...args
|number \| Array.<number>
|one or more numbers or arrays of numbers
|===

*Returns*: `number` | `Array.<number>`. The range value of all numbers if `args`
contains only numbers. Returns an array with the the range values at each index,
including all scalar numbers in `args` in the calculation at each index if `args`
contains at least one array.

*Example*
[source, js]
------------
range(1, 2, 3) // returns 2
range([10, 20, 30, 40], 15) // returns [5, 5, 15, 25]
range([1, 9], 4, [3, 5]) // returns [range([1, 4, 3]), range([9, 4, 5])] = [3, 5]
------------

[float]
=== round( a, b )

Rounds a number towards the nearest integer by default, or decimal place (if passed in as `b`).
For arrays, the function will be applied index-wise to each element.

[cols="3*^<"]
|===
|Param |Type |Description

|a
|number \| Array.<number>
|a number or an array of numbers

|b
|number
|(optional) number of decimal places, default value: 0
|===

*Returns*: `number` | `Array.<number>`. The rounded value of `a`. Returns an
array with the the rounded values of each element if `a` is an array.

*Example*
[source, js]
------------
round(1.2) // returns 2
round(-10.51) // returns -11
round(-10.1, 2) // returns -10.1
round(10.93745987, 4) // returns 10.9375
round([2.9234, 5.1234, 3.5234, 4.49234324], 2) // returns [2.92, 5.12, 3.52, 4.49]
------------

[float]
=== size( a )

Returns the length of an array. Alias for count.

[cols="3*^<"]
|===
|Param |Type |Description

|a
|Array.<any>
|array of any values
|===

*Returns*: `number`. The length of the array.

*Throws*: `'Must pass an array'` if `a` is not an array

*Example*
[source, js]
------------
size([]) // returns 0
size([-1, -2, -3, -4]) // returns 4
size(100) // returns 1
------------

[float]
=== sqrt( a )

Calculates the square root of a number. For arrays, the function will be applied
index-wise to each element.

[cols="3*^<"]
|===
|Param |Type |Description

|a
|number \| Array.<number>
|a number or an array of numbers
|===

*Returns*: `number` | `Array.<number>`. The square root of `a`. Returns an array
with the the square roots of each element if `a` is an array.

*Throws*: `'Unable find the square root of a negative number'` if `a` < 0

*Example*
[source, js]
------------
sqrt(9) // returns 3
sqrt(30) //5.477225575051661
sqrt([9, 16, 25]) // returns [3, 4, 5]
------------

[float]
=== square( a )

Calculates the square of a number. For arrays, the function will be applied
index-wise to each element.

[cols="3*^<"]
|===
|Param |Type |Description

|a
|number \| Array.<number>
|a number or an array of numbers
|===

*Returns*: `number` | `Array.<number>`. The square of `a`. Returns an array
with the the squares of each element if `a` is an array.

*Example*
[source, js]
------------
square(-3) // returns 9
square([3, 4, 5]) // returns [9, 16, 25]
------------

[float]
=== subtract( a, b )

Subtracts two numbers. If at least one array of numbers is passed into the function,
the function will be applied index-wise to each element.

[cols="3*^<"]
|===
|Param |Type |Description

|a
|number \| Array.<number>
|a number or an array of numbers

|b
|number \| Array.<number>
|a number or an array of numbers
|===

*Returns*: `number` | `Array.<number>`. The difference of `a` and `b` if both are
numbers, or an array of differences applied index-wise to each element.

*Throws*: `'Array length mismatch'` if `a` and `b` are arrays with different lengths

*Example*
[source, js]
------------
subtract(6, 3) // returns 3
subtract([10, 20, 30, 40], 10) // returns [0, 10, 20, 30]
subtract(10, [1, 2, 5, 10]) // returns [9, 8, 5, 0]
subtract([14, 42, 65, 108], [2, 7, 5, 12]) // returns [12, 35, 52, 96]
------------

[float]
=== sum( ...args )

Calculates the sum of one or more numbers/arrays passed into the function. If at
least one array is passed, the function will sum up one or more numbers/arrays of
numbers and distinct values of an array. Sum accepts arrays of different lengths.

*Returns*: `number`. The sum of one or more numbers/arrays of numbers including
distinct values in arrays

*Example*
[source, js]
------------
sum(1, 2, 3) // returns 6
sum([10, 20, 30, 40], 10, 20, 30) // returns 160
sum([1, 2], 3, [4, 5], 6) // returns sum(1, 2, 3, 4, 5, 6) = 21
sum([10, 20, 30, 40], 10, [1, 2, 3], 22) // returns sum(10, 20, 30, 40, 10, 1, 2, 3, 22) = 138
------------

[float]
=== unique( a )

Counts the number of unique values in an array.

*Returns*: `number`. The number of unique values in the array. Returns 1 if `a`
is not an array.

*Example*
[source, js]
------------
unique(100) // returns 1
unique([]) // returns 0
unique([1, 2, 3, 4]) // returns 4
unique([1, 2, 3, 4, 2, 2, 2, 3, 4, 2, 4, 5, 2, 1, 4, 2]) // returns 5
------------