450 lines
7.6 KiB
Markdown
450 lines
7.6 KiB
Markdown
---
|
|
tags: api/lua
|
|
references:
|
|
- client/space_lua/stdlib/string.ts
|
|
- client/space_lua/stdlib/string_pack.ts
|
|
---
|
|
|
|
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 *n*th captured string (`%n`), balanced match (`%bxy`), and frontier pattern (`%f[set]`) forms from the [Lua 5.4 pattern manual](https://www.lua.org/manual/5.4/manual.html#6.4.1) may not be supported.
|
|
|
|
The `string.matchRegex` and `string.matchRegexAll` extensions use JavaScript regular expressions instead of Lua patterns.
|
|
|
|
Examples of patterns that differ:
|
|
|
|
```lua
|
|
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".
|
|
```
|
|
|
|
<!--#lua spacelua.renderApiDocumentation("string") -->
|
|
## 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:**
|
|
|
|
```lua
|
|
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:**
|
|
|
|
```lua
|
|
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:**
|
|
|
|
```lua
|
|
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:**
|
|
|
|
```lua
|
|
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:**
|
|
|
|
```lua
|
|
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:**
|
|
|
|
```lua
|
|
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:**
|
|
|
|
```lua
|
|
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`
|
|
<!--/lua-->
|
|
|