Lua String Reference
Published September 9, 2026Preface
People tend to love or hate Lua. It's a language with lots of quirks, and one of those is how it handles strings. The Lua standard library is miniscule, and the string module lacks methods for splitting strings, trimming whitespace, and many other expected features. It doesn't even have a regular expression engine.
A typical implementation of POSIX regexp takes more than 4,000 lines of code. This is bigger than all Lua standard libraries together. In comparison, the implementation of pattern matching in Lua has less than 500 lines. Lua docs 20.1
... which maybe says more about Lua's standard library than anything else.
Instead, Lua implements its own pattern-matching system, with a format very similar to, but not quite the same as regex. This system is very powerful, and allows you to implement most useful string handling functions yourself - a common practice in Lua, for better or for worse.
Unfortunately, documentation for Lua's pattern matching system, and its associated functions, can be difficult to pin down. The official docs spread it out over several pages of lengthy examples, which aren't easy to search. luadocs.com is more granular, but hides the pattern matching syntax on the page for a single function.
I would like to mention Lua Pattern Tester as well- a great online tool similar to RegExr for testing Lua patterns, with its own cheat sheet.
So, I wanted to make a post outlining the basics of Lua's pattern matching and string functions, as a reference for anyone - but mostly myself. This will be less of a comprehensive guide and more of a cheat sheet.
(This post assumes you're familiar with regex and basic pattern-matching concepts.)
Pattern syntax
Unlike Regex, Lua patterns are plain strings, which are then processed by the functions which take them. There is no pre-compilation step involved.
Patterns match most characters literally, with the exception of special character classes.
| Symbol | Character Set |
|---|---|
| . | Any Character |
| %a | Letters |
| %c | Control Characters |
| %d | Digits (0-9) |
| %l | Lowercase Letters |
| %p | Punctuation Characters |
| %u | Uppercase letters |
| %w | Alphanumeric Characters |
| %x | Hexidecimal Digits |
| %z | The NUL character (e.g. ASCII value 0) |
Any of these can be capitalized to represent the inverse of their character set. (e.g. %D represents all non-digits)
Lua patterns use % as their escape character, unlike regex which typically uses \. Therefore, as you might expect, to escape a percent sign, you use %%.
(Notably, because Lua patterns are just regular strings, you still need to use \ to escape characters like " or ')
Beyond character classes, there are a series of magic characters which perform additional matching functions, many of which will be familiar to anyone coming from regex.
| Character(s) | Function |
|---|---|
| ( ) | Creates a capture group. More on these later. |
| [ ] | Defines a custom character class, matching anything between the brackets. Within these, - can be used to specify a character range. e.g. [0-9] is functionally identical to %d. Beginning a set with ^ will cause it to match anything except its contents. |
| + | Match 1 or more repititions of the previous character |
| * | Match 0 or more repititions of the previous character |
| ? | Optional - match 0 or 1 occurances of the previous character |
| - | Match as few repititions of the previous character as possible |
| ^ | Anchors pattern to the beginning of the target string |
| $ | Anchors pattern to the end of the target string |
| %bxy | Matches a balanced string, beginning with x and ending with y. This can be used to, say, match text within parenthases, with %b(). These characters do not need to be escaped. |
| %n | Matches the contents of a capture group, where n is the index of said group (starting at 1). Note that this pattern cannot be used in conjunction with optional/repitition characters such as * or +. |
- and * are functionally very similar, except that - will match as few characters as possible, while * while match as many as possible. Any of these magic characters can be escaped with % (e.g. %* or %[).
String Pattern Functions
All string functions can be called in two ways- either through the string module itself, e.g. string.method(x), or called directly on the string itself using colon syntax, e.g. x:method(). Note that, for string literals, they need to be wrapped in parenthases in order to be properly recognized ("Hello, world!"):method(). For consistency, examples will be given in the former syntax.
string.find
string.find(str, pattern, init, plain)
str(string) - The string to searchpattern(string) - The pattern to search for- this can be a plain string or Lua pattern.init(number) - The starting position for the search. Defaults to 1 (as everything in Lua, strings are 1-indexed). Negative values count from the end of the string.plain(boolean) - If true, disables pattern matching and treatspatternas a plain string.
Return Value
- Start and end indices of the first occurance of the pattern, and captures, if relevant
- If no match is found, returns
nil.
string.match
string.match(str, pattern, init)
str(string) - The string to searchpattern(string) - The pattern to search for. This is always treated as a pattern-matching string.init(number) - The starting position for the search. Defaults to 1.
Return Value
Returns the first match found as a string. If no match is found, returns nil. If capture groups are used, returns each group found in order.
Functionally, match is nearly identical to find, only requiring the use of patterns and not returning the index.
string.gmatch
string.gmatch(str, pattern)
str(string) - The string to searchpattern(string) - The pattern to search for. This is always treated as a pattern-matching string.
Return Value
Returns an interator function which can be used to loop over all substrings matching the specified pattern. If a pattern contains capture groups, it returns each captured string in a multiple return each time it is called.
string.gsub
string.gsub(str, pattern, replacement, n)
str(string) - The string to searchpattern(string) - The pattern to search for. This is always treated as a pattern-matching string.replacement(string/function/table) - The replacement for matched substrings. Can be:- A string to substitute for each match.
- A function, which is called with the match as it's only parameter. The return value is used as the substitution.
- A table, where the match is used as a key to look up a substitution.
n(number (optional)) - The maximum number of replacements to perform. Defaults to performing as many replacements as possible.
Return Value
Returns the modified string, and the number of replacements made.
Note: This function is not related to string.sub. 'sub' is short for 'substring' in that function, whereas it's short for 'substitute' in this one.
Acknowledgements & Resources
Information taken from the official Lua docs, and luadocs.com. The latter features more in-depth documentation and examples for each of the string functions, as well as documentation on non-pattern matching functions.