Utility Functions

A library of general Lua utility functions.

Functions

copy_table

utility_functions.copy_table(t)

View source

If a table is passed, returns a copy, otherwise returns the passed value.

Input Type Description
t mixed
Return type Description
mixed

table_remove_first

utility_functions.table_remove_first(t, value)

View source

Removes the first occurrence of a value from an array table.

Input Type Description
t table
value mixed

iterate_keys

utility_functions.iterate_keys(t)

View source

Returns an unordered iterator for the keys in a table.

Input Type Description
t table
Return type Description
function

round

utility_functions.round(num, places)

View source

Rounds a number to the nearest integer or the specified number of decimal places.

Input Type Description
num number
places (optional) number If specified, the number of decimal places to round to. If omitted or 0, will round to the nearest integer.
Return type Description
number

to_integer_if_whole

utility_functions.to_integer_if_whole(value)

View source

Takes a number and if it is an integer or whole float (eg 12 or 12.0), returns an integer. All other floats will be returned as passed.

Input Type Description
value number
Return type Description
number

calc_roman_numeral

utility_functions.calc_roman_numeral(num)

View source

Calculates the roman numeral for the input number. Adapted from https://exercism.org/tracks/lua/exercises/roman-numerals/solutions/Nia11 on 2022-08-13

Input Type Description
num number
Return type Description
string

calc_ordinal

utility_functions.calc_ordinal(num)

View source

Calculates the ordinal for the input number (e.g. 1st, 2nd, 3rd).

Input Type Description
num number
Return type Description
string

calc_alphabet

utility_functions.calc_alphabet(num)

View source

This returns one of the ways that Finale handles numbering things alphabetically, such as rehearsal marks or measure numbers.

This function was written to emulate the way Finale numbers saves when Autonumber is set to A, B, C… When the end of the alphabet is reached it goes to A1, B1, C1, then presumably to A2, B2, C2.

Input Type Description
num number
Return type Description
string

clamp

utility_functions.clamp(num, minimum, maximum)

View source

Clamps a number between two values.

Input Type Description
num number The number to clamp.
minimum number The minimum value.
maximum number The maximum value.
Return type Description
number

ltrim

utility_functions.ltrim(str)

View source

Removes whitespace from the start of a string.

Input Type Description
str string
Return type Description
string

rtrim

utility_functions.rtrim(str)

View source

Removes whitespace from the end of a string.

Input Type Description
str string
Return type Description
string

trim

utility_functions.trim(str)

View source

Removes whitespace from the start and end of a string.

Input Type Description
str string
Return type Description
string

call_and_rethrow

utility_functions.call_and_rethrow(levels, tryfunczzz)

View source

Calls a function and returns any returned values. If any errors are thrown at the level this function is called, they will be rethrown at the specified level with new level information. If the error message contains the rethrow placeholder enclosed in single quotes (see utils.rethrow_placeholder), it will be replaced with the correct function name for the new level.

The first argument must have the same name as the rethrow_placeholder, chosen for uniqueness.

@ … (any) Any arguments to be passed to the function.

Input Type Description
levels number Number of levels to rethrow.
tryfunczzz function The function to call.
Return type Description
any If no error is caught, returns the returned values from tryfunczzz

rethrow_placeholder

utility_functions.rethrow_placeholder()

View source

Returns the function name placeholder (enclosed in single quotes, the same as in Lua’s internal errors) used in call_and_rethrow.

Use this in error messages where the function name is variable or unknown (eg because the error is thrown up multiple levels) and needs to be replaced with the correct one at runtime by call_and_rethrow.

Return type Description
string

require_embedded

utility_functions.require_embedded()

View source

Bypasses the deployment rewrite of require to allow for requiring of libraries embedded in RGP Lua.

Return type Description
string The name of the embedded library to require.