regexp

Go regexp as RE2: Compile versus MustCompile, submatches, and unsupported Perl syntax such as lookaheads and backreferences.

The regexp package implements regular-expression search. Official documentation says the accepted syntax is the syntax accepted by RE2, described at the RE2 syntax page and in regexp/syntax, and that matching runs in time linear in the input. That guarantee comes from an automaton, not from backtracking.

Because the engine is RE2, constructs that need backtracking are not available: lookaheads, lookbehinds, and backreferences do not compile. Compile returns an error for those patterns. MustCompile is the same parser but panics on a parse error, which is convenient for package-level variables that must be valid. Examples were checked with Go 1.24.0.

Examples were checked against Go 1.24.0. See the official package documentation for the complete API.

Go reference overview →

API index

APISummary
regexp.Compile, regexp.MustCompile, Regexp.FindAllString, Regexp.FindStringSubmatch, Regexp.MatchStringParse a pattern, list matches, and read capturing groups. Compile returns an error; MustCompile panics on the same parse failure.
regexp.CompileRE2 does not compile lookaheads or backreferences. Compile returns a parse error; it does not fall back to a backtracking engine.

Compile, MustCompile, and matches

Compile parses an expression and returns (*Regexp, error). MustCompile returns only *Regexp and panics if parsing fails. Official documentation describes MustCompile as a helper for safe initialization of global variables. FindAllString with n < 0 returns every non-overlapping match. FindStringSubmatch returns the whole match at index 0 and then each capturing group. MatchString reports whether any match exists.

regexp.Compile, regexp.MustCompile, Regexp.FindAllString, Regexp.FindStringSubmatch, Regexp.MatchString

func Compile(expr string) (*Regexp, error)
func MustCompile(str string) *Regexp
func (re *Regexp) FindAllString(s string, n int) []string
func (re *Regexp) FindStringSubmatch(s string) []string
func (re *Regexp) MatchString(s string) bool

Parse a pattern, list matches, and read capturing groups. Compile returns an error; MustCompile panics on the same parse failure.

ParameterDescription
expr / strA RE2 regular expression. Invalid syntax, or Perl features this package does not implement, produce a parse error.
s, nThe string to search. If n >= 0, FindAllString returns at most n matches; if n < 0, it returns all of them.

Returns: Compile returns a *Regexp and a nil error, or a parse error. FindAllString returns a slice of matches, or nil if there is none. FindStringSubmatch returns the full match and submatches, or nil. MatchString returns whether a match exists.

Errors

  • parse error — The measured Compile error for "(" on Go 1.24.0 is "error parsing regexp: missing closing ): `(`". MustCompile panics with a message that includes that parse error.
  • [a-z]+ is case-sensitive, so "AB" does not match and "ab" does. The invalid pattern is passed to Compile, not MustCompile, so the program can print the error without recovering a panic.
go
package main

import (
	"fmt"
	"regexp"
)

func main() {
	re, err := regexp.Compile(`[a-z]+`)
	fmt.Println(err)
	fmt.Println(re.FindAllString("A ab cd!", -1))
	fmt.Println(re.MatchString("ab"), re.MatchString("AB"))
	sub := regexp.MustCompile(`(\d+)-(\d+)`)
	fmt.Println(sub.FindStringSubmatch("id 12-34 x"))
	_, err = regexp.Compile("(")
	fmt.Println(err)
}

Expected output

<nil>
[ab cd]
true false
[12-34 12 34]
error parsing regexp: missing closing ): `(`

Official documentation →

Unsupported Perl syntax

A lookahead such as foo(?=bar) and a backreference such as (a)\1 are accepted by some Perl-style engines and by Python re in default mode. This package rejects them. The measured errors on Go 1.24.0 are "invalid or unsupported Perl syntax" for the lookahead and "invalid escape sequence" for \1. There is no flag that turns backtracking or lookaround on.

regexp.Compile

func Compile(expr string) (*Regexp, error)

RE2 does not compile lookaheads or backreferences. Compile returns a parse error; it does not fall back to a backtracking engine.

ParameterDescription
exprThe pattern to parse. The example uses a positive lookahead and a backreference, both unsupported here.

Returns: A nil *Regexp and a non-nil error for these patterns.

Errors

  • parse error — Measured on Go 1.24.0: "error parsing regexp: invalid or unsupported Perl syntax: `(?=`" and "error parsing regexp: invalid escape sequence: `\1`".
  • The syntax is documented in regexp/syntax and at the RE2 syntax page linked from the package docs. This page does not attempt to list every RE2 feature.
go
package main

import (
	"fmt"
	"regexp"
)

func main() {
	_, err := regexp.Compile(`foo(?=bar)`)
	fmt.Println(err)
	_, err = regexp.Compile(`(a)\1`)
	fmt.Println(err)
}

Expected output

error parsing regexp: invalid or unsupported Perl syntax: `(?=`
error parsing regexp: invalid escape sequence: `\1`

Official documentation →