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.

Functions

string.at(str, pos)

Get character at position pos.


string.len(str)

Returns the length of the string, in Unicode code points.

local size = string.len("안녕하세요")
print(size) -- Prints "5"

See also: byte_count()


string.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()


string.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$"

See also: ltrim(), rtrim()


string.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  $"

See also: trim(), rtrim()


string.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$"

See also: ltrim(), trim()


string.starts_with(str, prefix)

Returns true if str starts with prefix, and false otherwise.

See also: ends_with()


string.ends_with(str, suffix)

Returns true if str ends with suffix, and false otherwise.

See also: starts_with()


string.contains(str, substring)

Returns true if str ends with substring, and false otherwise.


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


string.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()


string.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()


string.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()


string.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()


string.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()


string.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()


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


string.contains(str, substr)

Returns true if str contains substr and false otherwise. If substr is the empty string, the result is true.


string.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()


string.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()


string.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()


string.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()


string.reverse(str)

Returns a new string with all the characters in str in reversed order.

string.insert(str, pos, other)

Returns a copy of str with other inserted at position pos


string.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"

string.left(str, n)

Get the substring corresponding to the n first characters of the string.


string.right(str, n)

Get the substring corresponding to the n last characters of the string.


string.first(str)

Get the first character of the string.


string.last(str)

Get the last character of the string.


string.join(strings, delim)

Returns a new string which is the result of the concatenation of the strings in table strings, separated by delim.


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