Skip to main content
Version: latest - a1.65.x ⚖️

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

ReturnsNameDescription
booleanStartsWithTest whether this string starts with given string
booleanEndsWithTest whether this string ends with given string
stringTrimReturns a new string with removed whitespace characters from the front and end of this string
stringFormatArgsA better string.Format, replace {num} by the corresponding vararg in a string
varargs of integerbyteReturns the internal numeric codes of the characters s[start_pos], s[start_pos + 1], ..., s[end_pos]
stringcharReceives 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, stringfindLooks for the first match of pattern in the string.
stringrepReturns a string that is the concatenation of n copies of the string s separated by the string sep.
stringlowerReturns a copy of this string with all uppercase letters changed to lowercase.
stringupperReturns a copy of this string with all lowercase letters changed to uppercase.
stringdumpReturns a string containing a binary representation (a *binary chunk*) of the given function.
numbermatchLooks for the first match of pattern in the string.
stringreverseReturns a string that is the string s reversed.
stringsubReturns the substring of the string that starts at i and continues until j.
functiongmatchReturns an iterator function that, each time it is called, returns the next captures from pattern over the string s.
numberlenReturns its length.
string, numbergsubReturns 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.
stringformatReturns 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)
TypeParameterDefaultDescription
stringother_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)
TypeParameterDefaultDescription
stringother_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...)
TypeParameterDefaultDescription
varargs of anyargs... 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?)
TypeParameterDefaultDescription
integerstart_pos?1The first character of the string to get the byte of
integerend_pos?start_posThe 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...)
TypeParameterDefaultDescription
varargs of integervalues... 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)
TypeParameterDefaultDescription
stringhaystack Required parameter The string to search in.
stringneedle Required parameter The string to find, can contain patterns if enabled.
numberstartPos Required parameter The position to start the search from, can be negative start position will be relative to the end position.
booleannoPatterns 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)
TypeParameterDefaultDescription
stringstr Required parameter The string to convert.
numberrepetitions Required parameter Timer to repeat, this values gets rounded internally.
stringseparator 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)
TypeParameterDefaultDescription
stringstr 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)
TypeParameterDefaultDescription
stringstr 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)
TypeParameterDefaultDescription
functionfunc Required parameter The function to get the bytecode of
booleanstripDebugInfo 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)
TypeParameterDefaultDescription
stringstring Required parameter String which should be searched in for matches.
stringpattern Required parameter The pattern that defines what should be matched.
numberstartPosition 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)
TypeParameterDefaultDescription
stringstr 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)
TypeParameterDefaultDescription
stringstring Required parameter The string you'll take a sub-string out of.
numberStartPos Required parameter The position of the first character that will be included in the sub-string.
numberEndPos 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)
TypeParameterDefaultDescription
stringdata Required parameter The string to search in
stringpattern Required parameter The pattern to search for

len

Returns its length.

— Returns number.

local ret = my_string:len(str)
TypeParameterDefaultDescription
stringstr 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)
TypeParameterDefaultDescription
stringstring Required parameter String which should be modified.
stringpattern Required parameter The pattern that defines what should be matched and eventually be replaced.
stringreplacement 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.
numbermaxReplaces 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)
TypeParameterDefaultDescription
stringformat Required parameter The string to be formatted
numberformatParameters Required parameter Values to be formatted into the string.