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

See also: ltrim, rtrim

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

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

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.