7.4. Standard functions

MScript comes with a small library of functions that are available in any situation:

7.4.1. Type checks

bool is_num(any value)

Returns 1 (true) if the given value is a number, or none (false) otherwise.

For example, is_num(4.5) returns 1.

bool is_str(any value)

Returns 1 (true) if the given value is a string, or none (false) otherwise.

For example, is_str('hello') returns 1.

bool is_array(any value)

Returns 1 (true) if the given value is an array, or none (false) otherwise.

For example, is_array([1, 2, 3]) returns 1.

bool is_obj(any value)

Returns 1 (true) if the given value is an object, or none (false) otherwise.

For example, is_obj({name: 'A'}) returns 1.

bool is_func(any value)

Returns 1 (true) if the given value is a function, or none (false) otherwise.

For example, is_func(is_func) returns 1.

string typeof(any value)

Returns the name of the type of the given value.

This function will return the following type names:

function call return value
typeof(none)'none'
typeof(12)'number'
typeof('hello')'string'
typeof([3, 'four'])'array'
typeof({a: 5, b: 6})'object'
typeof(() => 0)'function'

7.4.2. Type conversion

number|none num(any value)

Converts the given value to a number. Returns none if the given value cannot be converted - only numbers and strings that can be parsed as numbers can be converted.

For example, num('4.5') returns 4.5.

string str(any value)

Converts the given value to a string by taking its string representation.

For example, str([4, 5]) returns '4 5'.

array array(any value)

Converts the given value to an array. Returns an array of 1-character strings if the value is a string. Returns the given value if it is already an array. Returns an empty array if the value is none. Returns an array that contains the given value otherwise.

For example, array('abc') returns ['a', 'b', 'c'], array(none) returns [] and array(7) returns [7].

7.4.3. Mathematics

number min(number value1, number value2)

Returns the lowest of the given numbers.

For example, min(4, 5) returns 4.

number max(number value1, number value2)

Returns the greatest of the given numbers.

For example, max(4, 5) returns 5.

number clamp(number value, number min, number max)

Clamps the given number to the given range. The returned number won't be lower than min or higher than max.

For example, clamp(5, 10, 20) returns 10.

number abs(number value)

Returns the absolute value of the given number.

For example, abs(-4.5) returns 4.5.

number round(number value)

Rounds the given number to the nearest integer value. Midpoint values are rounded to the nearest even number.

For example, round(1.2) returns 1.

number floor(number value)

Rounds the given number to the nearest integer that is lower than or equal to the given number.

For example, floor(1.8) returns 1.

number ceil(number value)

Rounds the given number to the nearest integer that is higher than or equal to the given number.

For example, ceil(1.2) returns 2.

number trunc(number value)

Truncates the given number by chopping off the decimal part.

For example, trunc(1.23) returns 1, and trunc(-2.3) returns -2.

number pow(number value, number power)

Raises the given number to the given power.

For example, pow(2, 4) returns 16.

number sqrt(number value)

Returns the square root of the given number.

For example, sqrt(9) returns 3.

7.4.4. Trigonometry

number sin(number radians)

Returns the sine of the given angle.

number cos(number radians)

Returns the cosine of the given angle.

number tan(number radians)

Returns the tangent of the given angle.

number asin(number sine)

Returns the angle (in radians) that corresponds to the given sine.

number acos(number cosine)

Returns the angle (in radians) that corresponds to the given cosine.

number atan(number tangent)

Returns the angle (in radians) that corresponds to the given tangent.

number atan2(number y, number x)

Returns the angle (in radians) between the positive x-axis and a line from the origin towards the point (x, y).

number deg2rad(number degrees)

Converts an angle in degrees to radians.

For example, deg2rad(360) returns 6.283..., which is 2 * PI.

number rad2deg(number radians)

Converts an angle in radians to degrees.

For example, rad2deg(PI) returns 180.

7.4.5. Text

number ord(string str)
number ord(string str, number index)

Returns the numeric Unicode value of a specific character in the given string. The first character is chosen if no index is provided. Returns none if the index is out of range or if the given string is none.

For example, ord('a') returns 97, and ord('4') returns 52.

string chr(number value)

Returns a single-character string for the given Unicode value.

For example, chr(97) returns a, and chr(52) returns 4.

7.4.6. Arrays

The following functions are used with arrays:

array range(number stop)
array range(number start, number stop)
array range(number start, number stop, number step)

Creates an array that contains a range of numbers, starting from start (inclusive) up until stop (exclusive). By default, it will start at 0 and use a step size of 1. A higher step size will skip numbers, while a negative step size will create a range of decreasing numbers.

For example, range(5) returns [0, 1, 2, 3, 4], and range(6, 0, -2) returns [6, 4, 2].

array repeat(any value, number count)

Creates an array that contains a specific number of copies of the given value.

For example, repeat('a', 4) returns ['a', 'a', 'a', 'a'].

7.4.7. Objects

The following functions are used with objects:

object obj_add(object obj, string field_name, any value)

Returns a copy of the object, but with an extra field added to it. Trying to add an existing field will overwrite its value. Returns a new object with a single field if the given object is none.

For example, obj_add({name: 'John'}, 'age', 25) returns {name: 'John', age: 25}.

object obj_remove(object obj, string field_name)
object obj_remove(object obj, array field_names)

Returns a copy of the object, but without the specified field (or fields). Trying to remove a non-existing field won't have any effect. Returns none if the given object is none.

For example, obj_remove({name: 'John', age: 25}, 'name') returns {age: 25}.

object obj_merge(object obj1, object obj2)

Returns an object that contains all the fields from both given objects. If the objects contain fields with the same name, then the value from obj2 is used. Returns the other object if one of the objects is none. Returns none if both objects are none.

For example, obj_merge({name: 'red', color: '#FF0000'}, {name: 'John', age: 25}) returns {name: 'John', color: '#FF0000', age: 25}.

bool obj_has(object obj, string name)

Returns 1 (true) if the given object has a field with the given name, or none (false) otherwise. Returns none if the given object is none.

For example, obj_has({name: 'John', age: 25}, 'name') returns 1.

any obj_value(object obj, string name)

Returns the value of the specified field in the given object, or none if the given object does not contain a field with that name, or if the object is none.

For example, obj_value({name: 'John', age: 25}, 'age') returns 25.

array obj_fields(object obj)

Returns an array that contains the names of all the fields in the given object. Returns an empty array if the given object is none.

For example, obj_fields({name: 'John', age: 25}) returns ['name', 'age'].

7.4.8. Functions

string func_name(function func)

Returns the name of the given function, or none if the given function is none.

For example, func_name(max) returns 'max'.

array func_args(function func)

Returns an array that contains the parameter names of the given function, or none if the given function is none.

For example, func_args(pow) returns ['value', 'power'].

object func_arg(function func, string name)

Returns an object with information about the specified function parameter, or none if the given function is none or if the parameter does not exist.

For example, func_arg(range, 'step') returns {name: 'step', type: 'number', optional: 1, default_value: none}.

object func_apply(function func, array arguments)

Calls the given function with the given arguments and returns the result. Returns none if the given function is none.

For example, func_apply(min, [3, 4]) returns 3.

7.4.9. Colors

array color(array color)

Returns an array of 3 values (red, green and blue) if the given array contains 3 values or less. Returns an array of 4 values (red, green, blue and brightness) if the given array contains 4 values or more. The first 3 values are clamped to the 0-255 range (inclusive), and all values are rounded to the nearest integer value. If a value can't be converted or is missing, 0 is used instead. This function can be used to 'sanitize' colors.

For example, color(['100', 300, 150.4]) returns [100, 255, 150].

7.4.10. Debugging

bool assert(bool condition)
bool assert(bool condition, string message)

This function aborts processing if the given condition is none (false). If a message is provided then it is included in the error message that is logged. Returns 1 (true) if the condition is true.