Extensions

Discordia has some built-in Lua standard library extensions. These provide complementary or supplementary, commonly used functions that the Lua standard library does not provide.

Extensions can be used directly...

local str = "  abc  "
print(discordia.extensions.string.trim(str)) -- "abc"

... or they can be loaded into the global tables:

local str = "  abc  "
discordia.extensions.string()
print(string.trim(str)) -- "abc"

Note that calling the whole extensions module will load all sub-modules:

discordia.extensions()

Table

number table.count(tbl)

• tbl: table

Returns the total number of elements in a table. This uses the global pairs function and by default respects any __pairs metamethods.

number table.deepcount(tbl)

• tbl: table

Returns the total number of elements in a table, recursively. If a table is encountered, it is recursively counted instead of being directly added to the total count. This uses the global pairs function and by default respects any __pairs metamethods.

table table.copy(tbl)

• tbl: table

Returns a copy of the original table, one layer deep.

table table.deepcopy(tbl)

• tbl: table

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

table.reverse(tbl)

• tbl: table

Reverses the elements of an array-like table in place.

table table.reversed(tbl)

• tbl: table

Returns a copy of an array-like table with its elements in reverse order. The original table remains unchanged.

table table.keys(tbl)

• tbl: table

Returns a new array-like table where all of its values are the keys of the original table.

table table.values(tbl)

• tbl: table

Returns a new array-like table where all of its values are the values of the original table.

number, * table.randomipair(tbl)

• tbl: table

Returns a random (index, value) pair from an array-like table.

*, * table.randompair(tbl)

• tbl: table

Returns a random (key, value) pair from a dictionary-like table.

table table.sorted(tbl, fn)

• tbl: table
• fn: function

Returns a copy of an array-like table sorted using Lua's table.sort.

* table.search(tbl, value)

• tbl: table
• 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 table.slice(tbl[, start, stop, step])

• tbl: table

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

String

table string.split(str[, delim])

• str: string

Splits a string into a table of specifically delimited sub-strings. If the delimiter is omitted or empty, the string is split into a table of characters.

string string.trim(str)

• str: string

Returns a new string with all whitespace removed from the left and right sides of the original string.

string string.pad(str, len[, align, pattern])

• str: string
• len: number

Returns a new string that is padded up to the desired length. The alignment, either left, right, or center with left being the default, defines the placement of the original string. The default pattern is a single space.

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

• str: string
• pattern: string

Returns whether a string starts swith a specified sub-string or pattern. The plain parameter is the same as that used in Lua's string.find.

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

• str: string
• pattern: string

Returns whether a string ends swith a specified sub-string or pattern. The plain parameter is the same as that used in Lua's string.find.

number string.levenshtein(str1, str2)

• str1: string
• str2: string

Returns the Levenshtein distance between two strings. A higher number indicates a greter distance.

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

• len: number

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

Math

number math.clamp(n, min, max)

• n: number
• min: number
• max: number

Returns a number that is at least as small as the minimum value and at most as large as the maximum value, inclusively. If the original number is already with the bounds, the same number is returned.

number math.round(n[, digits])

• n: number

Returns a number that is rounded to the nearest defined digit. The nearest integer is returned if the digit is omitted. Negative values can be used for higher order places.