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"

🦠 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.

---

StartsWith

Test whether this string starts with given string

— Returns boolean.

local ret = my_string:StartsWith(other_string)

Type	Parameter	Default	Description
string	other_string	Required parameter	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

— Returns boolean.

local ret = my_string:EndsWith(other_string)

Type	Parameter	Default	Description
string	other_string	Required parameter	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

— Returns string.

local ret = my_string:Trim()

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

— Returns string.

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

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

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]

— Returns varargs of integer (the internal numeric code).

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

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

---

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

— Returns string (the string).

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

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

---

find

Looks for the first match of pattern in the string.

— Returns number, number, string (, , ).

local ret_01, ret_02, ret_03 = my_string:find(haystack, needle, startPos, noPatterns)

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.

---

rep

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

— Returns string.

local ret = my_string:rep(str, repetitions, separator)

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.

---

lower

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

— Returns string.

local ret = my_string:lower(str)

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

---

upper

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

— Returns string.

local ret = my_string:upper(str)

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

---

dump

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

— Returns string.

local ret = my_string:dump(func, stripDebugInfo)

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

---

match

Looks for the first match of pattern in the string.

— Returns number.

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

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.

---

reverse

Returns a string that is the string s reversed.

— Returns string.

local ret = my_string:reverse(str)

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

---

sub

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

— Returns string.

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

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.

---

gmatch

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

— Returns function.

local ret = my_string:gmatch(data, pattern)

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

---

len

Returns its length.

— Returns number.

local ret = my_string:len(str)

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

---

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.

— Returns string, number (, ).

local ret_01, ret_02 = my_string:gsub(string, pattern, replacement, maxReplaces)

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.

---

format

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

— Returns string.

local ret = my_string:format(format, formatParameters)

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