Extensions

Discordia comes with some general purpose functions. These are added to the Lua standard library when the discordia module is required.

Globals

printf(...)

Serves the same purpose that it does in other languages that feature the same function. In lua, it is a shortcut for print(string.format(...))

Table

table.count(tbl)

Returns the number of elements in a table, one layer deep. This is an alternative to the #, which should be used for sequentially-indexed tables.

table.deepcount(tbl)

Returns the number of elements in a table, recursively. If a table is encountered, it is recursively counted instead of being added to the total count.

table.find(tbl, value)

Iterates through a table until it finds a value that is equal to value according to the == operator. The key is returned if a match is found.

table.reverse(tbl)

Reverses the elements of a sequentially-indexed table, in place.

table.reversed(tbl)

Returns a copy of a sequentially-indexed table with its elements in reverse order. The original table remains unchanged.

table.copy(tbl)

Returns a copy of a table, one layer deep.

table.deepcopy(tbl)

Returns a copy of a table, recursively. If a table is encountered, it is recursively deep copied. Metatables are not copied.

table.keys(tbl)

Returns a new, sequentially-indexed table, where all of its values are the keys of the original table.

table.values(tbl)

Returns a new, sequentially-indexed table, where all of its values are the values of the original table.

table.hash(tbl, key)

Given a sequentially-indexed table of associatively-indexed sub-tables (objects), this will convert the original table into one where the objects become indexed by a specified key (property).

table.randomipair(tbl)

Given a sequentially-indexed table, this will return a random index, value pair from the table.

table.randompair(tbl)

Given an associatively-indexed table, this will return a random key, value pair from the table.

table.sorted(tbl[, fn])

Returns a copy of a sequentially-indexed table, sorted using Lua's table.sort.

table.transposed(tbl)

Given a two-dimensional, sequentially index table, this will return a new table with the rows and columns swapped.

table.slice(tbl[, start, stop, step])

Returns a new table that is a slice of the original, defined by the start and stop bounds and the step size. The default start, stop, and step are 1, #tbl, and 1, respectively.

String

string.split(str[, delim])

Splits a string into sub-strings delimited by the specified delim. If the delimiter is omitted or empty, each character of the string will be split. The sub-strings are returned in a sequentially-indexed table.

string.split2(str[, delim])

Splits a string similarly to string.split, though this version supports delimiting by patterns and does not return individual characters if the delimiter is omitted.

string.trim(str)

Returns a string where the whitespace is removed from the far left and far right side of the original string.

string.padleft(str, len[, pattern])

Adds spaces to the left side of the original string so that the new string is at least as long as the provided length.

string.padright(str, len[, pattern])

Adds spaces to the right side of the original string so that the new string is at least as long as the provided length.

string.padcenter(str, len[, pattern])

Adds spaces to the left and right side of the original string equally so that the new string is at least as long as the provided length. Priority is given to the right side for odd lengths.

string.startswith(str, pattern[, plain])

Indicates whether a string starts with the provided pattern. The plain parameter is the same as that used in Lua's string.find.

string.endswith(str, pattern[, plain])

Indicates whether a string ends with the provided pattern. The plain parameter is the same as that used in Lua's string.find.

string.levenshtein(str1, str2)

Returns the Levenshtein distance between two strings. Higher numbers indicate a greater difference.

string.random(len[, min, max])

Returns a string of random characters of the specified length. If provided, the min and max bounds cannot be outside 0 to 255. Use 32 to 126 for printable characters.

Math

math.clamp(n, min, max)

Returns a number that is at least as small as the minimum value and at most as large as the maximum value, inclusively. If it is already within the bounds, the number is returned unchanged.

math.round(n[, i])

Returns a number that is rounded to the nearest defined digit. The nearest integer is returned if the digit definition is omitted.