#api/lua
API docs for Space Lua's string module.
note Note Since string values set
stringas their meta table, these APIs can also be called as method calls on strings directly. For instance:someString:startsWith("h")is equivalent tostring.startsWith(someString, "h").
Lua patterns are not regular expressions. Space Lua makes a good effort at translating Lua patterns to regex to run in a Javascript environment, but there are two main differences:
^$()%.[]*+-? must be escaped to represent their character. Standard Lua patterns do not require escaping magic characters when they are not contextually magic (e.g. %d-- is a valid Lua pattern where the second hyphen is not magic). Space Lua may have unexpected results when expecting an un-escaped magic character to behave like a character.?, *, +, and -) will apply to captures in patterns. They do not in standard Lua.Additionally, the patterns for the *n*th captured string (%*n*), balanced match (%b*xy*), and frontier pattern (%f[set]) in Lua will likely not be supported.
As noted below, the operations string.matchRegex and string.matchRegexAll
leverage regex in Javascript--not Space Lua patterns.
Here are some valid Lua patterns with different matches (or outright errors) in Space Lua:
print(string.match("1234", "(%d)+"))
-- prints "4" in Space Lua (last match of the captures)
-- prints "nil" in Lua (repetition magic does not work on captures)
print(string.match("*", "*"))
-- invalid regex in Space Lua ("*" is not escaped)
-- prints "*" in Lua
print(string.match("2024-03-14", "%d+-(%d+)-%d+"))
-- invalid regex in Space Lua (the "-"s are not escaped")
-- prints "03" in Lua
Returns the numeric codes of characters in string s from position i to j. If j is not provided, defaults to i.
Example:
print(string.byte("Hello", 1)) -- prints: 72 (ASCII code for 'H')
Returns a string from given ASCII codes.
Example:
print(string.char(72)) -- prints: H
Looks for the first match of pattern in string s. Returns start and end indices of match.
Example:
local start, end_ = string.find("Hello", "l")
print(start) -- prints: 3 (first 'l' position)
Returns a formatted string using C-style format specifiers.
Example:
print(string.format("Name: %s, Age: %d", "John", 30)) -- prints: Name: John, Age: 30
print(string.format("Pi: %.2f", 3.14159)) -- prints: Pi: 3.14
Returns a copy of s in which all (or the first n) occurrences of pattern have been replaced by repl.
Example:
-- Simple string replacement
local result, count = string.gsub("hello world", "hello", "hi")
print(result, count) -- prints: hi world 1
-- Multiple replacements with limit
result = string.gsub("hello hello hello", "hello", "hi", 2)
print(result) -- prints: hi hi hello
-- Function replacement
result = string.gsub("hello world", "(h)ello", function(h)
return string.upper(h) .. "i"
end)
print(result) -- prints: Hi world
-- Pattern with magic characters
result = string.gsub("hello.world", "%.", "-")
print(result) -- prints: hello-world
Returns the captures from the first match of pattern in string s.
Example:
-- Basic pattern matching
print(string.match("hello", "h")) -- prints: h
-- Multiple captures
local year, month, day = string.match("2024-03-14", "(%d+)%-(%d+)%-(%d+)")
print(year, month, day) -- prints: 2024 03 14
-- With init position
print(string.match("hello world", "(world)", 7)) -- prints: world
-- Pattern characters
print(string.match("123", "%d+")) -- prints: 123
print(string.match("abc123", "%a+")) -- prints: abc
print(string.match(" abc", "%s+")) -- prints: " "
Returns an iterator function that returns successive captures from pattern matches in string s.
Example:
local words = {}
for word in string.gmatch("hello world lua", "%w+") do
table.insert(words, word)
end
print(words[1], words[2], words[3]) -- prints: hello world lua
Returns the length of string s.
Example:
print(string.len("Hello")) -- prints: 5
Returns a copy of s with all characters converted to lowercase.
Example:
print(string.lower("Hello")) -- prints: hello
Returns a copy of s with all characters converted to uppercase.
Example:
print(string.upper("Hello")) -- prints: HELLO
Returns a string that is the concatenation of n copies of string s.
Example:
print(string.rep("Hello", 3)) -- prints: HelloHelloHello
Returns a string with the characters of s in reverse order.
Example:
print(string.reverse("hello")) -- prints: olleh
print(string.reverse("")) -- prints: "" (empty string)
Returns the substring of s from position i to j.
Example:
print(string.sub("Hello", 2, 4)) -- prints: ell
Splits string s using separator sep and returns a table of substrings.
Example:
local parts = string.split("a,b,c", ",")
for i, part in ipairs(parts) do
print(part)
end
-- Output:
-- a
-- b
-- c
Returns true if string s starts with prefix.
Example:
print(string.startsWith("hello world", "hello")) -- prints: true
print(string.startsWith("hello world", "world")) -- prints: false
Returns true if string s ends with suffix.
Example:
print(string.endsWith("hello world", "world")) -- prints: true
print(string.endsWith("hello world", "hello")) -- prints: false
Returns a copy of string s with whitespace removed from both ends.
Example:
print(string.trim(" hello ")) -- prints: hello
Returns a copy of string s with whitespace removed from the beginning.
Example:
print(string.trimStart(" hello ")) -- prints: hello
Returns a copy of string s with whitespace removed from the end.
Example:
print(string.trimEnd(" hello ")) -- prints: hello
Matches string s against a JavaScript regular expression pattern and returns the result. This uses JavaScript's native regex capabilities rather than Lua patterns.
Example:
local match = string.matchRegex("hello123", "([a-z]+)([0-9]+)")
print(match[1], match[2]) -- prints: hello 123
Returns an iterator that finds all matches of a JavaScript regular expression pattern in string s.
Example:
for match in string.matchRegexAll("a1b2c3", "([a-z])([0-9])") do
print(match[0], match[1], match[2]) -- prints each full match and its capture groups
end
-- Output:
-- a1 a 1
-- b2 b 2
-- c3 c 3