Lua String Library
string
Lua 5.1's string library, callable as string.fn(s, ...) or s:fn(...). find, match, gmatch and gsub use Lua patterns, not regular expressions.
string.byte
function
string.byte(s [, i [, j]])
Numeric byte codes of characters s[i..j].
Returns the internal numeric codes of the characters s[i], s[i+1], ..., s[j]. The default for i is 1; the default for j is i.
Usage
string.byte(s, i, j)
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
s | string | Yes | Source string. |
i | integer | No | Start index (1-based, negative counts from the end). Default 1. |
j | integer | No | End index. Default i. |
Returns
- one integer per byte in range i..j
Example
print(string.byte('A')) -- 65
print(('ABC'):byte(1, 3)) -- 65 66 67
string.char
function
string.char(...)
Build a string from numeric byte codes.
Receives zero or more integers and returns a string with a character for each code.
Usage
string.char(...)
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
... | integer | No | Byte codes (variadic). |
Returns
- string
Example
print(string.char(65, 66, 67)) -- "ABC"
string.dump
function
string.dump(function)
Serialize a function to a binary chunk.
Returns a function's compiled bytecode as a string, which loadstring can load again. Works only on Lua functions defined in the script.
Usage
string.dump(fn)
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
function | function | Yes | A Lua function with no upvalues other than _ENV/globals. |
Returns
- string (binary chunk)
Example
local function Add(a, b) return a + b end
local Bytes = string.dump(Add)
local Reloaded = loadstring(Bytes)
print(Reloaded(2, 3)) -- 5
string.find
function
string.find(s, pattern [, init [, plain]])
Find the first match of a pattern in a string.
Returns the start and end of the first match of pattern in s from position init, plus any captures, or nil. With plain true, the pattern is a literal string.
Usage
string.find(s, pattern, init, plain)
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
s | string | Yes | Source string. |
pattern | string | Yes | Lua pattern (or literal text when plain=true). |
init | integer | No | 1-based start index (negative counts from the end). Default 1. |
plain | boolean | No | When true, disables pattern matching and does a plain substring search. |
Returns
- start, end [, captures...] on match; nil on no match
Example
local S, E = string.find('hello world', 'wor')
print(S, E) -- 7 9
local S2, E2, Cap = string.find('MRN:12345', '(%d+)')
print(Cap) -- "12345"
string.format
function
string.format(formatstring, ...)
printf-style string formatting.
Returns a formatted version of its variable number of arguments following the description given in formatstring, which follows the rules of the C printf.
Usage
string.format(formatstring, ...)
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
formatstring | string | Yes | printf-style format string (%d, %s, %f, %x, %q, ...). |
... | any | No | Values to format (variadic). |
Returns
- string
Example
print(string.format('%s = %05d', 'count', 42)) -- "count = 00042"
string.gmatch
function
string.gmatch(s, pattern)
Iterator over all pattern matches.
Returns an iterator function that, each time it is called, returns the next captures from pattern over string s. If pattern has no captures, the whole match is returned each time.
Usage
for cap1, cap2 in string.gmatch(s, pattern) do ... end
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
s | string | Yes | Source string. |
pattern | string | Yes | Lua pattern. |
Returns
- iterator function, for use in a generic for loop
Example
for word in string.gmatch('one two three', '%a+') do
print(word)
end
-- one
-- two
-- three
string.gsub
function
string.gsub(s, pattern, repl [, n])
Global substitution by pattern.
Returns a copy of s with every match of pattern (or the first n) replaced by repl, and the number of matches. repl may be a string with %1-%9 captures, a table or a function.
Usage
string.gsub(s, pattern, repl, n)
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
s | string | Yes | Source string. |
pattern | string | Yes | Lua pattern. |
repl | string|table|function | Yes | Replacement string, capture-indexed table, or replacement function. |
n | integer | No | Maximum number of substitutions; default is unlimited. |
Returns
string— the resulting string.count— number of substitutions made.
Example
local Out, N = string.gsub('hello world', 'o', '0')
print(Out, N) -- "hell0 w0rld" 2
local Wire = ('ADT^A01|20260101'):gsub('%^', '-')
print(Wire) -- "ADT-A01|20260101"
local Redacted = string.gsub('SSN: 123-45-6789', '%d', '#')
print(Redacted) -- "SSN: ###-##-####"
string.len
function
string.len(s)
Length of a string (= #s).
Receives a string and returns its length. Equivalent to the # operator on a string.
Usage
string.len(s)
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
s | string | Yes | Source string. |
Returns
- integer
Example
print(string.len('hello')) -- 5
print(#'hello') -- 5
string.lower
function
string.lower(s)
Lowercase copy of a string.
Receives a string and returns a copy of it with all uppercase letters changed to lowercase; other characters are unchanged.
Usage
string.lower(s)
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
s | string | Yes | Source string. |
Returns
- string
Example
print(string.lower('HELLO')) -- "hello"
string.match
function
string.match(s, pattern [, init])
Return the first match's captures (or the whole match).
Looks for the first match of pattern in s, starting at position init, and returns the captures from the pattern, or the whole match if the pattern specifies no captures. Returns nil on no match.
Usage
string.match(s, pattern, init)
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
s | string | Yes | Source string. |
pattern | string | Yes | Lua pattern. |
init | integer | No | 1-based start index (negative counts from the end). Default 1. |
Returns
- captures... (or the whole match); nil on no match
Example
local Mrn = string.match('MRN:12345', 'MRN:(%d+)')
print(Mrn) -- "12345"
string.rep
function
string.rep(s, n [, sep])
Repeat a string n times.
Returns a string that is the concatenation of n copies of s, optionally separated by sep between each pair.
Usage
string.rep(s, n, sep)
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
s | string | Yes | String to repeat. |
n | integer | Yes | Number of copies. |
sep | string | No | Separator inserted between copies. |
Returns
- string
Example
print(string.rep('ab', 3)) -- "ababab"
print(string.rep('ab', 3, '-')) -- "ab-ab-ab"
string.reverse
function
string.reverse(s)
Reverse a string.
Returns a string that is the string s reversed.
Usage
string.reverse(s)
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
s | string | Yes | Source string. |
Returns
- string
Example
print(string.reverse('hello')) -- "olleh"
string.sub
function
string.sub(s, i [, j])
Substring s[i..j].
Returns the substring of s that starts at i and continues until j; i and j can be negative, counting from the end of the string. The default for j is -1 (the end of the string).
Usage
string.sub(s, i, j)
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
s | string | Yes | Source string. |
i | integer | Yes | Start index (1-based, negative counts from the end). |
j | integer | No | End index. Default -1 (end of string). |
Returns
- string
Example
print(string.sub('hello world', 1, 5)) -- "hello"
print(string.sub('hello world', -5)) -- "world"
string.upper
function
string.upper(s)
Uppercase copy of a string.
Receives a string and returns a copy of it with all lowercase letters changed to uppercase; other characters are unchanged.
Usage
string.upper(s)
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
s | string | Yes | Source string. |
Returns
- string
Example
print(string.upper('hello')) -- "HELLO"