string

The complete string library. Patterns in find/match/gmatch/gsub use Lua patterns, not regex.

Inspection

string.len(s)

Byte length (not character count — see utf8.len for that).

print(string.len("portal"))  --> 6
print(string.len("pozo"))    --> 4 (each ö is 2 bytes)

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

Numeric codes of bytes i..j (defaults: first byte only).

print(string.byte("A"))        --> 65
print(string.byte("ABCD", 2))  --> 66
print(string.byte("ABCD", 1, 3))  --> 65  66  67

string.char(...)

Builds a string from byte codes.

print(string.char(112, 111))  --> po

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

Returns start index, end index, plus captures. Pass plain=true for literal searches.

print(string.find("hello portal", "portal"))      --> 7  12
print(string.find("a+b", "+", 1, true))           --> 2  2  (literal)
local s, e, cap = string.find("hp=100", "(%d+)")
print(s, e, cap)                                  --> 4  6  100

string.match(s, pattern, init?)

Returns the captures (or the whole match if there are none).

print(string.match("Portal 1 v400", "(%d+)"))        --> 1
print(string.match("hp=100", "(%w+)=(%d+)"))         --> hp  100

string.gmatch(s, pattern)

Iterator over all matches.

for word in string.gmatch("the cake is a lie", "%a+") do
    print(word)
end
--> the / cake / is / a / lie

Transformation

string.sub(s, i, j?)

Substring; negative indices count from the end, j defaults -1.

print(string.sub("portal", 1, 3))   --> por
print(string.sub("portal", -3))     --> tal

string.rep(s, n, sep?)

Repetition, optionally joined by sep.

print(string.rep("na", 4))       --> nananana
print(string.rep("x", 3, "-"))   --> x-x-x

string.reverse(s)

print(string.reverse("portal"))  --> latrop

string.lower(s), string.upper(s)

ASCII case conversion.

print(string.upper("portal"))  --> PORTAL
print(string.lower("GLaDOS"))  --> glados

string.format(f, ...)

Printf-style formatting: %s %d %f %.2f %x %X %o %c %q %%, with width and precision (%5.2f).

print(string.format("%s has %d hp", "cube", 100))  --> cube has 100 hp
print(string.format("%.2f%%", 99.456))             --> 99.46%
print(string.format("%5d|", 42))                   -->    42|
print(string.format("%x", 255))                    --> ff
print(string.format("%q", 'a"b'))                  --> "a\"b"

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

Global substitution; repl may be a string (with %1 captures), a table, or a function. Returns the new string and the count.

print(string.gsub("portal", "o", "0"))            --> p0rtal  1
print(string.gsub("hp=100", "(%d+)", "<%1>"))     --> hp=<100>  1
print(string.gsub("a b c", "%a+", {a="x", b="y"}))  --> x y c  3
print(string.gsub("one two", "%a+", function(w)
    return w:upper()
end))                                            --> ONE TWO  2

string.split(s, sep?) (Luau)

Splits into a table of substrings. sep defaults to ","; empty fields are preserved positionally.

local parts = string.split("id,name,version", ",")
print(parts[2])            --> name
print(#parts)              --> 3
print(string.split("a,,c")[2])  --> ""  (empty, but present)

Binary packing (Luau)

string.packsize(fmt)

Size in bytes a pack with this format will produce.

print(string.packsize("I4"))  --> 4
print(string.packsize("I2I4")) --> 6

string.pack(fmt, ...)

Packs values into a binary string. Formats: b/B (i8/u8), h/H (i16/ u16), i/I[n] (integers), f (f32), d (f64), s (NUL-terminated), </> (endianness, default little).

local blob = string.pack("<I4 f", 400, 0.5)
print(#blob)  --> 8

string.unpack(fmt, s, pos?)

Unpacks values from a binary string; returns values followed by the next read position.

local blob = string.pack("<I2 s1", 7, "po")
local n, str = string.unpack("<I2 s1", blob)
print(n, str)  --> 7  po