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.

👐Open Source🧑‍💻API Source

---

tip

You can use this library statically as string.method(my_str, ...) or directly as my_str:method(...)!

🎒 Examples

(string.StartsWith) Checks if string starts with text

local str = "awesome text!"
local starts = str:StartsWith("awesome")
-- Outputs "true"

(string.EndsWith) Checks if string ends with text

local str = "awesome text!"
local ends = str:EndsWith("text!")
-- Outputs "true"

(string.Trim) Removes extra spaces

local str = "  Hello world!	"
local new_str = str:Trim()
-- Outputs "Hello world!"

(string.FormatArgs) Replaces {1} and {2} with corresponding texts

local str = "Hello {2} I'm {1}"
local new_str = str:FormatArgs("a noob", "world!")
-- Outputs "Hello world! I'm a noob"

(string.ToTable) Convert string to table of characters

local str = "hello"
local tbl = str:ToTable()
-- Outputs "{'h', 'e', 'l', 'l', 'o'}"

🦠 Functions

	Returns	Name	Description
	boolean	StartsWith	Test whether this string starts with given string
	boolean	EndsWith	Test whether this string ends with given string
	string	Trim	Returns a new string with removed whitespace characters from the front and end of this string
	string	FormatArgs	A better string.Format, replace {num} by the corresponding vararg in a string
	varargs of integer	byte	Returns the internal numeric codes of the characters s[start_pos], s[start_pos + 1], ..., s[end_pos]
	number, number, string	find	Looks for the first match of pattern in the string.
	string	rep	Returns a string that is the concatenation of n copies of the string s separated by the string sep.
	string	lower	Returns a copy of this string with all uppercase letters changed to lowercase.
	string	upper	Returns a copy of this string with all lowercase letters changed to uppercase.
	number	match	Looks for the first match of pattern in the string.
	string	reverse	Returns a string that is the string s reversed.
	string	sub	Returns the substring of the string that starts at i and continues until j.
	function	gmatch	Returns an iterator function that, each time it is called, returns the next captures from pattern over the string s.
	number	len	Returns its length.
	string, number	gsub	Returns a copy of s in which all (or the first n, if given) occurrences of the pattern have been replaced by a replacement string specified by repl.
	string	format	Returns a formatted version of its variable number of arguments following the description given in its first argument.
	table of string	ToTable	Split string into table of single characters

---

StartsWith

Test whether this string starts with given string

local ret = my_string:StartsWith(other_string)

Parameters

Type	Parameter	Default	Description
string	other_string	Required parameter	The given string

Returns

Type	Description
boolean	Whether this string starts with the given string

string.StartsWith Examples

Checks if string starts with text

local str = "awesome text!"
local starts = str:StartsWith("awesome")
-- Outputs "true"

---

EndsWith

Test whether this string ends with given string

local ret = my_string:EndsWith(other_string)

Parameters

Type	Parameter	Default	Description
string	other_string	Required parameter	The given string

Returns

Type	Description
boolean	Whether this string ends with the given string

string.EndsWith Examples

Checks if string ends with text

local str = "awesome text!"
local ends = str:EndsWith("text!")
-- Outputs "true"

---

Trim

Returns a new string with removed whitespace characters from the front and end of this string

local ret = my_string:Trim()

Returns

Type	Description
string	The trimmed string

string.Trim Examples

Removes extra spaces

local str = "  Hello world!	"
local new_str = str:Trim()
-- Outputs "Hello world!"

---

FormatArgs

A better string.Format, replace {num} by the corresponding vararg in a string

local ret = my_string:FormatArgs(args...)

Parameters

Type	Parameter	Default	Description
varargs of any	args...	Required parameter	The args

Returns

Type	Description
string	The formatted string

string.FormatArgs Examples

Replaces {1} and {2} with corresponding texts

local str = "Hello {2} I'm {1}"
local new_str = str:FormatArgs("a noob", "world!")
-- Outputs "Hello world! I'm a noob"

---

byte

Returns the internal numeric codes of the characters s[start_pos], s[start_pos + 1], ..., s[end_pos]

local ret_01, ret_02, ... = my_string:byte(start_pos?, end_pos?)

Parameters

Type	Parameter	Default	Description
integer	start_pos?	1	The first character of the string to get the byte of
integer	end_pos?	start_pos	The last character of the string to get the byte of

Returns

Type	Description
varargs of integer	the internal numeric code

---

find

Looks for the first match of pattern in the string.

local ret_1, ret_2, ret_3 = my_string:find(needle, start_position, plain)

Parameters

Type	Parameter	Default	Description
string	needle	Required parameter	The string to find, can contain patterns if enabled.
number	start_position	Required parameter	The position to start the search from, can be negative start position will be relative to the end position.
boolean	plain	Required parameter	Disable patterns.

Returns

Type	Description
number	Start index of the match, or nil if not found
number	End index of the match
string	Captured substrings, if the pattern has captures

---

rep

Returns a string that is the concatenation of n copies of the string s separated by the string sep.

local ret = my_string:rep(repetitions, separator)

Parameters

Type	Parameter	Default	Description
number	repetitions	Required parameter	Times to repeat, this values gets rounded internally.
string	separator	Required parameter	String that will separate the repeated piece. Notice that it doesn't add this string to the start or the end of the result, only between the repeated parts.

Returns

Type	Description
string	The repeated string

---

lower

Returns a copy of this string with all uppercase letters changed to lowercase.

local ret = my_string:lower()

Returns

Type	Description
string	The lowercase string

---

upper

Returns a copy of this string with all lowercase letters changed to uppercase.

local ret = my_string:upper()

Returns

Type	Description
string	The uppercase string

---

match

Looks for the first match of pattern in the string.

local ret = my_string:match(pattern, start_position)

Parameters

Type	Parameter	Default	Description
string	pattern	Required parameter	The pattern that defines what should be matched.
number	start_position	Required parameter	The start index to start the matching from, can be negative to start the match from a position relative to the end.

Returns

Type	Description
number	The captures of the first match, or the whole match if there are no captures. Nil if not found

---

reverse

Returns a string that is the string s reversed.

local ret = my_string:reverse()

Returns

Type	Description
string	The reversed string

---

sub

Returns the substring of the string that starts at i and continues until j.

local ret = my_string:sub(start_position, end_position)

Parameters

Type	Parameter	Default	Description
number	start_position	Required parameter	The position of the first character that will be included in the sub-string.
number	end_position	Required parameter	The position of the last character to be included in the sub-string. It can be negative to count from the end.

Returns

Type	Description
string	The substring

---

gmatch

Returns an iterator function that, each time it is called, returns the next captures from pattern over the string s.

local ret = my_string:gmatch(pattern)

Parameters

Type	Parameter	Default	Description
string	pattern	Required parameter	The pattern to search for

Returns

Type	Description
function	An iterator function returning the next match on each call

---

len

Returns its length.

local ret = my_string:len()

Returns

Type	Description
number	The length of the string, in bytes

---

gsub

Returns a copy of s in which all (or the first n, if given) occurrences of the pattern have been replaced by a replacement string specified by repl.

local ret_1, ret_2 = my_string:gsub(pattern, replacement, max_replacements)

Parameters

Type	Parameter	Default	Description
string	pattern	Required parameter	The pattern that defines what should be matched and eventually be replaced.
string	replacement	Required parameter	In case of a string the matched sequence will be replaced with it. In case of a table, the matched sequence will be used as key and the table will be tested for the key, if a value exists it will be used as replacement. In case of a function all matches will be passed as parameters to the function, the return value(s) of the function will then be used as replacement.
number	max_replacements	Required parameter	Maximum number of replacements to be made.

Returns

Type	Description
string	The resulting string
number	The number of replacements made

---

format

Returns a formatted version of its variable number of arguments following the description given in its first argument.

local ret = my_string:format(format_parameters...)

Parameters

Type	Parameter	Default	Description
varargs of any	format_parameters...	Required parameter	Values to be formatted into the string.

Returns

Type	Description
string	The formatted string

---

ToTable

Converts this string into a table where each element is a single-character substring of the original string.

local ret = my_string:ToTable()

Returns

Type	Description
table of string	Table of single-character strings

string.ToTable Examples

Convert string to table of characters

local str = "hello"
local tbl = str:ToTable()
-- Outputs "{'h', 'e', 'l', 'l', 'o'}"