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

This library implementation is Open Sourced on GitHub!

🧑‍💻API Source

This page is auto-generated! The Functions, Properties and Events described here are defined in our GitHub's API Repository! Feel free to commit suggestions and changes to the source .json API files!

---

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]
	string	char	Receives zero or more integers. Returns a string with length equal to the number of arguments, in which each character has the internal numeric code equal to its corresponding argument
	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.
	string	dump	Returns a string containing a binary representation (a *binary chunk*) of the given function.
	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	No description provided

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	No description provided

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	No description provided

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	No description provided

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

---

char

Receives zero or more integers. Returns a string with length equal to the number of arguments, in which each character has the internal numeric code equal to its corresponding argument

local ret = my_string:char(values...)

Parameters

Type	Parameter	Default	Description
varargs of integer	values...	Required parameter	No description provided

Returns

Type	Description
string	the string

---

find

Looks for the first match of pattern in the string.

local ret_1, ret_2, ret_3 = my_string:find(haystack, needle, startPos, noPatterns)

Parameters

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

Returns

Type	Description
number	No description provided
number	No description provided
string	No description provided

---

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(str, repetitions, separator)

Parameters

Type	Parameter	Default	Description
string	str	Required parameter	The string to convert.
number	repetitions	Required parameter	Timer 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	No description provided

---

lower

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

local ret = my_string:lower(str)

Parameters

Type	Parameter	Default	Description
string	str	Required parameter	The string to convert.

Returns

Type	Description
string	No description provided

---

upper

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

local ret = my_string:upper(str)

Parameters

Type	Parameter	Default	Description
string	str	Required parameter	The string to convert.

Returns

Type	Description
string	No description provided

---

dump

Returns a string containing a binary representation (a *binary chunk*) of the given function.

local ret = my_string:dump(func, stripDebugInfo)

Parameters

Type	Parameter	Default	Description
function	func	Required parameter	The function to get the bytecode of
boolean	stripDebugInfo	Required parameter	True to strip the debug data, false to keep it

Returns

Type	Description
string	No description provided

---

match

Looks for the first match of pattern in the string.

local ret = my_string:match(string, pattern, startPosition)

Parameters

Type	Parameter	Default	Description
string	string	Required parameter	String which should be searched in for matches.
string	pattern	Required parameter	The pattern that defines what should be matched.
number	startPosition	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	No description provided

---

reverse

Returns a string that is the string s reversed.

local ret = my_string:reverse(str)

Parameters

Type	Parameter	Default	Description
string	str	Required parameter	The string to be reversed.

Returns

Type	Description
string	No description provided

---

sub

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

local ret = my_string:sub(string, StartPos, EndPos)

Parameters

Type	Parameter	Default	Description
string	string	Required parameter	The string you'll take a sub-string out of.
number	StartPos	Required parameter	The position of the first character that will be included in the sub-string.
number	EndPos	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	No description provided

---

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(data, pattern)

Parameters

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

Returns

Type	Description
function	No description provided

---

len

Returns its length.

local ret = my_string:len(str)

Parameters

Type	Parameter	Default	Description
string	str	Required parameter	The string to find the length of.

Returns

Type	Description
number	No description provided

---

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(string, pattern, replacement, maxReplaces)

Parameters

Type	Parameter	Default	Description
string	string	Required parameter	String which should be modified.
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 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	maxReplaces	Required parameter	Maximum number of replacements to be made.

Returns

Type	Description
string	No description provided
number	No description provided

---

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, formatParameters)

Parameters

Type	Parameter	Default	Description
string	format	Required parameter	The string to be formatted
number	formatParameters	Required parameter	Values to be formatted into the string.

Returns

Type	Description
string	No description provided

---

ToTable

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

local ret = my_string:ToTable(str)

Parameters

Type	Parameter	Default	Description
string	str	Required parameter	The string to convert into a table

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'}"