256 lines
7.1 KiB
Markdown
256 lines
7.1 KiB
Markdown
# String API
|
|
|
|
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 Pattern Matching
|
|
|
|
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:
|
|
|
|
1. Magic characters `^$()%.[]*+-?` 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.
|
|
2. In Space Lua, the repetition magic characters (`?`, `*`, `+`, 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](https://www.lua.org/manual/5.4/manual.html#6.4.1) 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:
|
|
|
|
```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
|
|
```
|
|
|
|
## String Operations
|
|
|
|
### string.byte(s, i?, j?)
|
|
Returns the numeric codes of characters in string `s` from position `i` to `j`. If `j` is not provided, defaults to `i`.
|
|
|
|
Example:
|
|
```lua
|
|
print(string.byte("Hello", 1)) -- prints: 72 (ASCII code for 'H')
|
|
```
|
|
|
|
### string.char(...)
|
|
Returns a string from given ASCII codes.
|
|
|
|
Example:
|
|
```lua
|
|
print(string.char(72)) -- prints: H
|
|
```
|
|
|
|
### string.find(s, pattern, init?, plain?)
|
|
Looks for the first match of `pattern` in string `s`. Returns start and end indices of match.
|
|
|
|
Example:
|
|
```lua
|
|
local start, end_ = string.find("Hello", "l")
|
|
print(start) -- prints: 3 (first 'l' position)
|
|
```
|
|
|
|
### string.format(format, ...)
|
|
Returns a formatted string using C-style format specifiers.
|
|
|
|
Example:
|
|
```lua
|
|
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
|
|
```
|
|
|
|
### string.gsub(s, pattern, repl, n?)
|
|
Returns a copy of `s` in which all (or the first `n`) occurrences of `pattern` have been replaced by `repl`.
|
|
|
|
Example:
|
|
```lua
|
|
-- 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
|
|
```
|
|
|
|
### string.match(s, pattern, init?)
|
|
Returns the captures from the first match of `pattern` in string `s`.
|
|
|
|
Example:
|
|
```lua
|
|
-- 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: " "
|
|
```
|
|
|
|
### string.gmatch(s, pattern)
|
|
Returns an iterator function that returns successive captures from pattern matches in string `s`.
|
|
|
|
Example:
|
|
```lua
|
|
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
|
|
```
|
|
|
|
### string.len(s)
|
|
Returns the length of string `s`.
|
|
|
|
Example:
|
|
```lua
|
|
print(string.len("Hello")) -- prints: 5
|
|
```
|
|
|
|
### string.lower(s)
|
|
Returns a copy of `s` with all characters converted to lowercase.
|
|
|
|
Example:
|
|
```lua
|
|
print(string.lower("Hello")) -- prints: hello
|
|
```
|
|
|
|
### string.upper(s)
|
|
Returns a copy of `s` with all characters converted to uppercase.
|
|
|
|
Example:
|
|
```lua
|
|
print(string.upper("Hello")) -- prints: HELLO
|
|
```
|
|
|
|
### string.rep(s, n, sep?)
|
|
Returns a string that is the concatenation of `n` copies of string `s`.
|
|
|
|
Example:
|
|
```lua
|
|
print(string.rep("Hello", 3)) -- prints: HelloHelloHello
|
|
```
|
|
|
|
### string.reverse(s)
|
|
Returns a string with the characters of `s` in reverse order.
|
|
|
|
Example:
|
|
```lua
|
|
print(string.reverse("hello")) -- prints: olleh
|
|
print(string.reverse("")) -- prints: "" (empty string)
|
|
```
|
|
|
|
### string.sub(s, i, j?)
|
|
Returns the substring of `s` from position `i` to `j`.
|
|
|
|
Example:
|
|
```lua
|
|
print(string.sub("Hello", 2, 4)) -- prints: ell
|
|
```
|
|
|
|
### string.split(s, sep)
|
|
Splits string `s` using separator `sep` and returns a table of substrings.
|
|
|
|
Example:
|
|
```lua
|
|
local parts = string.split("a,b,c", ",")
|
|
for i, part in ipairs(parts) do
|
|
print(part)
|
|
end
|
|
-- Output:
|
|
-- a
|
|
-- b
|
|
-- c
|
|
```
|
|
|
|
# Non-standard Extensions
|
|
### string.startsWith(s, prefix)
|
|
Returns true if string `s` starts with `prefix`.
|
|
|
|
Example:
|
|
```lua
|
|
print(string.startsWith("hello world", "hello")) -- prints: true
|
|
print(string.startsWith("hello world", "world")) -- prints: false
|
|
```
|
|
|
|
### string.endsWith(s, suffix)
|
|
Returns true if string `s` ends with `suffix`.
|
|
|
|
Example:
|
|
```lua
|
|
print(string.endsWith("hello world", "world")) -- prints: true
|
|
print(string.endsWith("hello world", "hello")) -- prints: false
|
|
```
|
|
|
|
### string.trim(s)
|
|
Returns a copy of string `s` with whitespace removed from both ends.
|
|
|
|
Example:
|
|
```lua
|
|
print(string.trim(" hello ")) -- prints: hello
|
|
```
|
|
|
|
### string.trimStart(s)
|
|
Returns a copy of string `s` with whitespace removed from the beginning.
|
|
|
|
Example:
|
|
```lua
|
|
print(string.trimStart(" hello ")) -- prints: hello
|
|
```
|
|
|
|
### string.trimEnd(s)
|
|
Returns a copy of string `s` with whitespace removed from the end.
|
|
|
|
Example:
|
|
```lua
|
|
print(string.trimEnd(" hello ")) -- prints: hello
|
|
```
|
|
|
|
### string.matchRegex(s, pattern)
|
|
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:
|
|
```lua
|
|
local match = string.matchRegex("hello123", "([a-z]+)([0-9]+)")
|
|
print(match[1], match[2]) -- prints: hello 123
|
|
```
|
|
|
|
### string.matchRegexAll(s, pattern)
|
|
Returns an iterator that finds all matches of a JavaScript regular expression pattern in string `s`.
|
|
|
|
Example:
|
|
```lua
|
|
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
|
|
``` |