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. |