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

table.count(tbl)

Parameter	Type
tbl	table

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

Returns: number

---

table.deepcount(tbl)

Parameter	Type
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 respects any __pairs metamethods.

Returns: number

---

table.copy(tbl)

Parameter	Type
tbl	table

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

Returns: table

---

table.deepcopy(tbl)

Parameter	Type
tbl	table

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

Returns: table

---

table.reverse(tbl)

Parameter	Type
tbl	table

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

Returns: nil

---

table.reversed(tbl)

Parameter	Type
tbl	table

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

Returns: table

---

table.keys(tbl)

Parameter	Type
tbl	table

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

Returns: table

---

table.values(tbl)

Parameter	Type
tbl	table

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

Returns: table

---

table.randomipair(tbl)

Parameter	Type
tbl	table

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

Returns: number, *

---

table.randompair(tbl)

Parameter	Type
tbl	table

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

Returns: *, *

---

table.sorted(tbl, fn)

Parameter	Type
tbl	table
fn	function

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

Returns: table

---

table.search(tbl, value)

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

Returns: *

---

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

Parameter	Type	Optional
tbl	table
start	number	✔
stop	number	✔
step	number	✔

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.

Returns: table

---

String

string.split(str, delim)

Parameter	Type	Optional
str	string
delim	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.

Returns: table

---

string.trim(str)

Parameter	Type
str	string

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

Returns: string

---

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

Parameter	Type	Optional
str	string
len	number
align	string	✔
pattern	string	✔

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.

Returns: string

---

string.startswith(str, pattern, plain)

Parameter	Type	Optional
str	string
pattern	string
plain	boolean	✔

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

Returns: boolean

---

string.endswith(str, pattern, plain)

Parameter	Type	Optional
str	string
pattern	string
plain	boolean	✔

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

Returns: boolean

---

string.levenshtein(str1, str2)

Parameter	Type
str1	string
str2	string

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

Returns: number

---

string.random(len, min, max)

Parameter	Type	Optional
len	number
min	number	✔
max	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.

Returns: string

---

Math

math.clamp(n, min, max)

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

Returns: number

---

math.round(n, digits)

Parameter	Type	Optional
n	number
digits	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.

Returns: number

---