Skip to content

string⚓︎

This library provides generic functions for string manipulation, such as finding and extracting substrings, and pattern matching. When indexing a string in Lua, the first character is at position 1 (not at 0, as in C). Indices are allowed to be negative and are interpreted as indexing backwards, from the end of the string. Thus, the last character is at position -1, and so on. Several functions in this library (e.g., find, gfind, gsub), make use of Lua patterns.

Functions⚓︎

string.endswith⚓︎

Returns true if a string ends with a given substring. This function does not use pattern matching.

local result = string.endswith(s, pattern)

Parameters:

  • s (string)
  • pattern (string)

Returns:

  • result (boolean)

string.format⚓︎

This function creates a string, given various values. The first parameter follows the printf format, with the additional option of %q to automatically quote a string.

Specifier Output Example
%d Signed decimal integer. -392
%i Same as %d. -392
%u Unsigned decimal integer. 7235
%o Unsigned octal. 610
%x Unsigned hexadecimal integer. 7fa
%X As %x, but uppercase. 7FA
%f Decimal floating point, lowercase. 392.65
%F Decimal floating point, uppercase. 392.65
%e Scientific notation (mantissa/exponent), lowercase. 3.9265e+2
%E Scientific notation (mantissa/exponent), uppercase. 3.9265E+2
%g Use the shortest representation: %e or %f. 392.65
%G Use the shortest representation: %E or %F. 392.65
%a Hexadecimal floating point, lowercase. -0xc.90fep-2
%A Hexadecimal floating point, uppercase. -0XC.90FEP-2
%c Character. a
%s String of characters. sample
%q Quoted string of characters. "sample"
%p Pointer address. b8000000
%% The literal % character. % 
local result = string.format(format, ...)

Parameters:

  • format (string): The format string to use for the output.
  • ... (any): Optional. Values to format into the specified string.

Returns:

  • result (string)

string.insert⚓︎

Returns a string where one string has been inserted into another, after a specified position.

For example, string.insert("12345678", "abcdefgh", 5) will return "12345abcdefgh678".

local result = string.insert(s1, s2, position)

Parameters:

  • s1 (string): The string to insert into.
  • s2 (string): The string to insert.
  • position (integer): An index of s1. The s2 string will be inserted after this index.

Returns:

  • result (string): A copy of s1, with s2 inserted into it after the specified position.

string.multifind⚓︎

Performs the logic of string.find on a string s, using a table of patterns.

If any of the patterns are found in s, then the matching pattern will be returned, followed by the normal results of string.find.

The patterns are checked in the order they are passed. i.e., this function will first try to match patterns[1], then patterns[2], and so on.

local pattern, startindex, endindex = string.multifind(s, patterns, index, plain)

Parameters:

  • s (string): The string to find patterns in.
  • patterns (table): An array-style table that contains the patterns to match.
  • index (integer): Default: 1. Start index of the find. (Same meaning as in string.find.)
  • plain (boolean): Default: false. If true, then a normal search will be performed instead of a pattern search. (Same meaning as in string.find.)

Returns:

  • pattern (string): Optional. If a pattern was matched, then this will be the first pattern that was matched. If no patterns matched, this will be nil.
  • startindex (integer): Optional. If a pattern was matched, this is the index of s where the matching pattern begins.
  • endindex (integer): Optional. If a pattern was matched, this is the index of s where the matching pattern ends.

string.split⚓︎

Returns an array-style table with a string split by a specified separator. The seperator is not part of the results. By default the sep == "%s", which will result in str getting split by whitespace characters (e.g. spaces and tabs).

Warning

if sep is more than one character, then str will get split at each occurrence of any of the individual characters in sep. For example, string.split("1a2b3c4abc5", "abc") will return {"1", "2", "3", "4", "5"} instead of {"1a2b3c4", "5"}.

local split = string.split(str, sep)

Parameters:

  • str (string): The string to split.
  • sep (string): Default: "%s". The token to split the string by.

Returns:

  • split (string[])

string.startswith⚓︎

Returns true if a string begins with a given substring. This function does not use pattern matching.

local result = string.startswith(s, substring)

Parameters:

  • s (string)
  • substring (string)

Returns:

  • result (boolean)

string.trim⚓︎

Returns a copy of the string, with whitespace characters (e.g. spaces and tabs) removed from the start and end.

local trimmed = string.trim(s)

Parameters:

  • s (string)

Returns:

  • trimmed (string)