Functions

There are various supported functions, and we are willing to add more. Let us know if you think something is missing.

The currently supported functions are:

General operations

length(val)

Find the length of the item passed in.

• For strings, it will return the number of unicode graphemes
• For arrays, the number of elements
• For JSON or other objects, it will return the number of properties
• For numbers it will return the length of the string representation

Numeric operations

round(val)

Rounds a number to the nearest whole number.

floor(val)

Rounds down a number to a whole number.

ceil(val)

Rounds up a number to a whole number.

abs(val)

Get the absolute value of a number. If the value is negative, the positive will be returned.

eg abs(-4) and abs(4) both give 4

fromRadix(val)

Converts a string from the specified radix to an int.

eg fromRadix("f", 16) gives 15

toRadix(val)

Converts an int to a string in the specified radix.

eg toRadix(15, 16) gives "f"

toFixed(val, dp)

Convert a number to a fixed precision string, with the specified number of digits after the decimal place.

isNumber(val)

Check if the value is a number.

max(val, val2, [val3, ...])

Finds the largest of the provided values.

min(val, val2, [val3, ...])

Finds the smallest of the provided values.

randomInt(min, max)

Generate a random integer in the specified range (inclusive).

log(v)

Calculate the natural logarithm of a number.

log10(v)

Calculate the base 10 logarithm of a number.

String operations

trim(val)

Trims any whitespace at the beginning and end of the string.

strlen(val)

Find the length of the given string. For Unicode strings this will count the bytes not the graphemes.

substr(val, indexStart, indexEnd)

substr() extracts characters from indexStart up to but not including indexEnd. For Unicode strings, this will count based on the bytes not the graphemes.

• If indexStart >= str.length, an empty string is returned.
• If indexStart < 0, the index is counted from the end of the string. More formally, in this case, the substring starts at max(indexStart + str.length, 0).
• If indexStart is omitted, undefined, or cannot be converted to a number, it's treated as 0.
• If indexEnd is omitted, undefined, or cannot be converted to a number, or if indexEnd >= str.length, substr() extracts to the end of the string.
• If indexEnd < 0, the index is counted from the end of the string.
• If indexEnd <= indexStart after normalizing negative values, an empty string is returned.

tip

If you don't want the behaviour of negative numbers, you can use max(0, index) to limit the value to never be below 0.

split(str, separator)

Split a string based on a separator

join(arr, separator)

Join an array of values into a single string separated by the specified separator

concat(str1, str2)

Combine one or more values into a single string

includes(val, find)

Check if a string contains a specific value

eg includes("Companion is great!", "great") gives true

indexOf(val, find, offset)

Find the index of the first occurrence of a value within the provided string. For Unicode strings, this will count based on the bytes not the graphemes.

Optionally provide an offset to begin the search from, otherwise it starts from position 0 (the beginning).

If the value isn't found, it will return -1, otherwise the index of the first occurrence.

lastIndexOf(val, find, offset)

Find the index of the last occurrence of a value within the provided string, searching from the end. For Unicode strings, this will count based on the bytes not the graphemes.

Optionally provide an offset to begin the search from, searching from the end.

If the value isn't found, it will return -1, otherwise the index of the last occurrence. The beginning is position 0.

toUpperCase(val)

Converts all characters in a string to uppercase

toLowerCase(val)

Converts all characters in a string to lowercase

replaceAll(val, find, replace)

Searches a string for a specific value, and then replaces all instances of that value with a new string

eg replaceAll("This is great!", "This", "Companion") gives Companion is great!

encode(str, enc)

Encode a string to the requested format ('hex','base64'). If enc is missing, latin1 will be used.

eg encode("Companion","hex") gives "436f6d70616e696f6e"

decode(str, enc)

Decode a string from the requested format ('hex','base64'). If enc is missing, latin1 will be used.

eg decode("436f6d70616e696f6e","hex") gives "Companion"

encodeURI(str)

Encodes a string as a valid Uniform Resource Identifier (URI)

eg encodeURI('hello world&1') gives "hello%20world&1"

decodeURI(str)

Gets the unencoded version of an encoded Uniform Resource Identifier (URI)

eg decodeURI('hello%20world&1') gives "hello world&1"

encodeURIComponent(str)

Encodes a string as a valid component of a Uniform Resource Identifier (URI)

eg encodeURIComponent('hello world&1') gives "test%20123%261"

decodeURIComponent(str)

Gets the unencoded version of an encoded component of a Uniform Resource Identifier (URI)

eg decodeURIComponent('test%20123%261') gives "hello world&1"

Variable operations

parseVariables(string, ?undefinedValue)

In some cases you may need nested variable evaluation (for example $(custom:$(custom:b))). The expression parser does not support that nested variable syntax directly. To evaluate nested variables inside an expression, pass the string to parseVariables, which will interpret string-variable and template syntax.

Optionally, you can provide the value to substitute in when a variable is undefined. This should be a string.

eg parseVariables('$(custom:$(custom:b))')

getVariable(string) or getVariable(string, string)

Dynamically fetch a variable value.

Note: when possible, prefer using the $(internal:time_hms) syntax, as it allows for Companion to statically detect the usage and auto-rename the reference when needed.

eg getVariable('internal:time_hms') or getVariable('internal', 'time_hms')

blink(number, ?number)

Generate a pulsing 0/1 value that alternates between on/off.
The provided number specifies the duration of each cycle.
The second parameter is an optional value between 0 - 1 which specifies the portion of the time to spend in the on state.

eg blink(1000) to flash once a second, on for 500ms then off for 500ms. blink(1000, 0.25) flashes once a second, on for 250ms off for 750ms

TIPS

• The 0/1 returned from this function can be treated as a boolean, you do not need to explicitly do this yourself
• If you prefer specifying the number of flashes per second, use 1000/n for the first parameter. For example, to flash three times per second write blink(1000/3).

Bool operations

bool(val)

Convert a value into a boolean.

Any of the following will be interpreted as true:

• any non-zero int
• "true"

Everything else will be false.

Object/Array operations

jsonpath(obj, path)

Perform a jsonpath lookup on an object or array.

The input can either be an object or an stringified object. The output will match the input format

You can see examples of how to use this at: https://jsonpath.com/

jsonparse(str)

Parse a string of json into an object.

If this encounters invalid input, it will return null instead of throwing an error.

eg: jsonparse('{"a":1}') will be an object { a: 1 }

jsonstringify(obj)

Convert an object into a json string.

If this encounters invalid input, it will return null instead of throwing an error.

eg: jsonstringify({ a: 1 }) will be a string containing {"a":1}

arrayIncludes(arr, val)

Check if an array includes a value

If this encounters invalid input, it will return false

arrayIndexOf(arr, val)

Find the index of the first occurrence of a value within the provided array.

Optionally provide an offset to begin the search from, otherwise it starts from position 0 (the beginning).

If the value isn't found, it will return -1, otherwise the index of the first occurrence.

arrayLastIndexOf(arr, val, offset)

Find the index of the last occurrence of a value within the provided array, searching from the end.

Optionally provide an offset to begin the search from, searching from the end.

If the value isn't found, it will return -1, otherwise the index of the last occurrence. The beginning is position 0.

Time operations

unixNow()

Get the current unix time in milliseconds.

timestampToSeconds(timestamp)

Convert a timestamp of format 'HH:MM:SS' into the number of seconds it represents.

eg 00:10:15 gives 615

You can do the reverse of this with secondsToTimestamp(str)

secondsToTimestamp(seconds, format) / msToTimestamp(milliseconds, format)

Convert a number of seconds or milliseconds into a formatted timestamp string. The default format is 'n:HH:mm:ss' for seconds and 'n:HH:mm:ss.SSS' for milliseconds.

By supplying the format parameter, you can choose which components will be included in the output string.

The following components are allowed:

• n - minus sign
• dd - days
• HH / hh - 12 hour / 24 hours
• mm - minutes
• ss - seconds
• S / SS / SSS - milliseconds (only for msToTimestamp), in varying levels of accuracy (1/100 seconds, 1/10 seconds, or milliseconds)
• a - AM/PM decorator

Using multiple characters to control padding length (e.g., HHH for 3-digit hours, ssss for 4-digit seconds). Milliseconds (S) support 1-3 digits.

By default, time components show modulo values (e.g., hours modulo 24, minutes modulo 60). To show the total value instead, wrap the unit in brackets [unit]. For example, [HH]:mm:ss will display total hours instead of hours modulo 24, and [mm]:ss will display total minutes instead of minutes modulo 60. Only one unit can be marked as largest per format string, and only H, h, m, or s can be used as the largest unit.

timeOffset(timestamp, offset, 12hour)

Offset a provided timestamp (supporting hours:minutes or hours:minutes:seconds) by a given number of hours, minutes, or seconds, and optionally return in 12 hour format.

eg timeOffset($(internal:time_hms), -5) will return the hours, minutes, and seconds, of 5 hours prior to the current time.

The offset also supports a timestamp, so timeOffset($(internal:time_hms), "01:30:00", true) will add 1 hour and 30 minutes to the current time, and return a 12 hour clock adjusted to that time.

timeDiff(fromTime, toTime)

Return the number of seconds between 2 timestamps. Timestamps support hours:minutes, hours:minutes:seconds, and YYYY-MM-DDTHH:mm:ss.sssZ.

eg timeDiff($(internal:time_hms), "18:00:00") will return the seconds until 18:00:00 on the same day, and after that time will return a negative value. An example using a Date Time String could be timeDiff($(internal:time_hms), "2024-07-04T20:00-04:00") which would return the number of seconds from the current Companion time until 4th July 2024, 8pm, in the UTC-4 Timezone.

The returned seconds can also be used within secondsToTimestamp to format the result as needed.