string

The string module contains Lua string operations and Space Lua extensions.

note Note Since string values use string as their metatable, these APIs can also be called as methods. For example, someString:startsWith("h") is equivalent to string.startsWith(someString, "h").

Lua pattern matching

Lua patterns are not regular expressions. Space Lua translates Lua patterns to JavaScript regular expressions and has a few compatibility differences:

1. Magic characters ^$()%.[]*+-? must be escaped to represent literal characters. Standard Lua does not require escaping a magic character when it is not contextually magic, so patterns such as %d-- can behave differently in Space Lua.
2. Space Lua allows repetition characters (?, *, +, and -) to apply to captures; standard Lua does not.
3. The nth captured string (%n), balanced match (%bxy), and frontier pattern (%f[set]) forms from the Lua 5.4 pattern manual may not be supported.

The string.matchRegex and string.matchRegexAll extensions use JavaScript regular expressions instead of Lua patterns.

Examples of patterns that differ:

print(string.match("1234", "(%d)+"))
-- Space Lua prints "4" because repetition applies to the capture.
-- Standard Lua returns nil.
 
print(string.match("*", "*"))
-- Space Lua reports an invalid regular expression.
-- Standard Lua prints "*".
 
print(string.match("2024-03-14", "%d+-(%d+)-%d+"))
-- Space Lua reports an invalid regular expression because the hyphens are not escaped.
-- Standard Lua prints "03".

string.byte

string.byte(s, i?, j?)

Returns the numeric character codes in the inclusive range from i to j.

Parameters:

• s (string)
• i? (integer)
• j? (integer)

Returns:

• integer — One result per character.

string.char

string.char(...): string

Creates a string from numeric character codes.

Returns:

• string

string.endsWith

string.endsWith(s, suffix)

Returns whether a string ends with a literal suffix.

Parameters:

• s (string)
• suffix (string)

Returns:

• boolean

string.find

string.find(s, pattern, init?, plain?)

Finds the first Lua-pattern match and returns its bounds followed by captures.

Parameters:

• s (string)
• pattern (string)
• init? (integer)
• plain? (boolean)

Returns:

• integer|nil — Start index or nil.
• integer — End index.

string.format

string.format(format, ...): string

Formats values according to a C-style format string.

Parameters:

• format (string)
• ... — Values consumed by conversion specifiers.

Returns:

• string

Example:

print(string.format("Name: %s, score: %.1f", "Ada", 9.5))

string.gmatch

string.gmatch(s, pattern, init?)

Returns an iterator over successive Lua-pattern matches and captures.

Parameters:

• s (string)
• pattern (string)
• init? (integer)

Returns:

• function — Match iterator.

Example:

for word in string.gmatch("hello world", "%w+") do
  print(word)
end

string.gsub

string.gsub(s, pattern, replacement, n?)

Replaces Lua-pattern matches using a string, table, or function replacement.

Parameters:

• s (string)
• pattern (string)
• replacement (string|table|function)
• n? (integer)

Returns:

• string — Result string.
• integer — Number of replacements.

Example:

local result, count = string.gsub("hello hello", "hello", "hi", 1)
print(result, count) -- hi hello  1

string.len

string.len(s)

Returns the length of a string.

Parameters:

• s (string)

Returns:

• integer

string.lower

string.lower(s)

Returns a copy of a string converted to lowercase.

Parameters:

• s (string)

Returns:

• string

string.match

string.match(s, pattern, init?)

Returns captures from the first Lua-pattern match, or nil when none is found.

Parameters:

• s (string)
• pattern (string)
• init? (integer)

Returns:

• Value — Pattern captures, whole match, or nil.

Example:

local year, month = string.match("2024-03", "(%d+)%-(%d+)")

string.matchRegex

string.matchRegex(s, pattern)

Matches a string with a JavaScript regular expression and returns the match array.

Parameters:

• s (string)
• pattern (string)

Returns:

• table|nil

Example:

local match = string.matchRegex("hello123", "([a-z]+)([0-9]+)")
print(match[1], match[2], match[3])

string.matchRegexAll

string.matchRegexAll(s, pattern)

Returns an iterator over all JavaScript regular-expression matches.

Parameters:

• s (string)
• pattern (string)

Returns:

• function — Iterator yielding match arrays.

Example:

for match in string.matchRegexAll("a1b2", "([a-z])([0-9])") do
  print(match[1], match[2], match[3])
end

string.pack

string.pack(format, ...): string

Packs values into a binary string according to a Lua 5.4 format string.

Parameters:

• format (string) — Binary packing format.
• ... — Values consumed by the format options.

Returns:

• string — Packed binary string.

string.packsize

string.packsize(format)

Returns the byte size of a fixed-length Lua 5.4 packing format.

Parameters:

• format (string) — Fixed-length binary packing format.

Returns:

• integer — Packed byte count.

string.rep

string.rep(s, n, sep?)

Returns n copies of a string joined by an optional separator.

Parameters:

• s (string)
• n (integer)
• sep? (string)

Returns:

• string

string.reverse

string.reverse(s)

Returns a string with its characters in reverse order.

Parameters:

• s (string)

Returns:

• string

string.split

string.split(s, sep)

Splits a string on a literal separator and returns the substrings.

Parameters:

• s (string)
• sep (string)

Returns:

• table

Example:

for part in each(string.split("a,b,c", ",")) do
  print(part)
end

string.startsWith

string.startsWith(s, prefix)

Returns whether a string starts with a literal prefix.

Parameters:

• s (string)
• prefix (string)

Returns:

• boolean

string.sub

string.sub(s, i, j?)

Returns the substring from inclusive index i through j, supporting negative indices.

Parameters:

• s (string)
• i (integer)
• j? (integer)

Returns:

• string

string.trim

string.trim(s)

Removes whitespace from both ends of a string.

Parameters:

• s (string)

Returns:

• string

string.trimEnd

string.trimEnd(s)

Removes whitespace from the end of a string.

Parameters:

• s (string)

Returns:

• string

string.trimStart

string.trimStart(s)

Removes whitespace from the beginning of a string.

Parameters:

• s (string)

Returns:

• string

string.unpack

string.unpack(format, data, init?)

Unpacks values from a binary string according to a Lua 5.4 format string.

Parameters:

• format (string) — Binary unpacking format.
• data (string) — Packed binary string.
• init? (integer) — One-based starting position.

Returns:

• Value — Unpacked values followed by the next unread position.

string.upper

string.upper(s)

Returns a copy of a string converted to uppercase.

Parameters:

• s (string)

Returns:

• string