API docs for Space Lua's string module.
Note: since string values set string as their meta table, these APIs can also be called as method calls on strings directly. For instance: someString:startsWith("h") is equivalent to string.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