String manipulation
This page documents the string
module.
General concepts
A string
is a sequence of characters enclosed between double quotes, such as "this"
. Strings in Lua are immutable, which means that you cannot
modify them directly. All functions which "modify" a string actually return a new (modified) copy of the string but leave the original string unchanged.
All string functions assume that strings are encoded according to the UTF-8 Unicode standard. A good tutorial about UTF-8 can be found at the following address: http://www.zehnet.de/2005/02/12/unicode-utf-8-tutorial. In the remainder of this document, the word character is used to mean code point, unless otherwise noted.
Application Programming Interface
at(str, pos)
Get character at position pos
.
len(str)
Returns the length of the string, in Unicode code points.
local size = string.len("안녕하세요")
print(size) -- Prints "5"
See also: byte_count
byte_count(str)
Returns the length of the string, in bytes (or Unicode code units). For strings encoded in ASCII (mostly, strings of English text with no "special" character),
each code unit is represented with 1 byte, such that bytecount
and len
return the same result. For most other languages, however, the number of bytes and the
number of code points will be different.
local english = "hello"
local korean = "안녕하세요"
print(string.len(english)) -- prints "5"
print(string.len(korean)) -- prints "5"
print(string.byte_count(english)) -- prints "5"
print(string.byte_count(korean)) -- prints "15"
See also: len
trim(str)
Returns a copy of the string with whitespace characters removed at both ends of the string.
local s = "\t hello \n"
s = string.trim(s)
print("$" .. s .. "$") -- prints "$hello$"
ltrim(str)
Returns a copy of the string with whitespace characters removed at the left end of the string.
local s = " hello "
s = string.ltrim(s)
print("$" .. s .. "$") -- prints "$hello $"
rtrim(str)
Returns a copy of the string with whitespace characters removed at the right end of the string.
local s = " hello "
s = string.rtrim(s)
print("$" .. s .. "$") -- prints "$ hello$"
starts_with(str, prefix)
Returns true if str
starts with prefix
, and false
otherwise.
See also: ends_with
ends_with(str, suffix)
Returns true if str
ends with suffix
, and false
otherwise.
See also: starts_with
contains(str, substring)
Returns true if str
ends with substring
, and false
otherwise.
count(str, substring)
Returns the number of times substring
appears in str
.
local s = "cacococococa"
local count = string.count(s, "coco")
print(count) -- prints "2"
Note: matches don't overlap.
to_upper(str)
Returns a copy of str
where each code point has been converted to upper case.
local s1 = "c'était ça"
local s2 = string.to_upper(s1)
print(s2) -- prints "C'ÉTAIT ÇA"
See also: to_lower
to_lower(str)
Returns a copy of str
where each code point has been converted to lower case.
local s1 = "C'ÉTAIT ÇA"
local s2 = string.to_lower(s1)
print(s2) -- prints "c'était ça"
See also: to_upper
replace(str, old, new)
Returns a copy of str
where all (non-overlapping) instances of the substring old
have been replaced by new
.
See also: replace_at, replace_first, replace_last
replace_at(str, at, count, new)
Returns a copy of str
where count
code points, starting at position at
, have been replaced by new
.
See also: replace, replace_first, replace_last
replace_first(str, old, new)
Returns a copy of str
where the first instance of the substring old
has been replaced by new
.
See also: replace_at, replace, replace_last
replace_last(str, old, new)
Returns a copy of str
where the last instance of the substring old
has been replaced by new
.
See also: replace_at, replace, replace_first
concat(str1, str2)
Create a new string which is the concatenation of str1
and str2
. In general, you should use Lua's built-in concatenation
operator ..
instead of this function.
contains(str, substr)
Returns true if str
contains substr
and false otherwise. If substr
is the empty string, the result is true.
remove(str, substr)
Returns a copy of str
where all (non-overlapping) instances of the substring substr
have been removed.
See also: remove_at, remove_first, remove_last
remove_at(str, at, count)
Returns a copy of str
where count
code points, starting at position at
, have been removed.
See also: remove, remove_first, remove_last
remove_first(str, substr)
Returns a copy of str
where the first instance of substr
has been removed.
See also: remove_at, remove, remove_last
remove_last(str, substr)
Returns a copy of str
where the last instance of substr
has been removed.
See also: remove_at, remove, remove_first
reverse(str)
Returns a new string with all the characters in str
in reversed order.
insert(str, pos, other)
Returns a copy of str
with other
inserted at position pos
substr(str, from, to)
Returns the substring of str
starting at index from
and ending at index to
(inclusive). If to
equals -1
, returns
the substring from from
until the end of the string.
local s = "c'était ça"
print(string.substr(s, 3, 7)) -- "était"
print(string.substr(s, 3,-1)) -- "était ça"
left(str, n)
Get the substring corresponding to the n
first characters of the string.
right(str, n)
Get the substring corresponding to the n
last characters of the string.
first(str)
Get the first character of the string.
last(str)
Get the last character of the string.
join(strings, delim)
Returns a new string which is the result of the concatenation of the strings in table strings
, separated by delim
.
split(str, delim)
Returns a table of strings which have been split at each occurrence of the substring delim
. If delim
is the empty
string, it returns a list of the characters in the string.