Skip to content
Tutorials Center
My learning

Topics

Go Reference ยท bytes, unicode and text

Go regexp.Regexp methods

Reference for the methods of Go regexp.Regexp: MatchString, FindString, FindAll, Submatch, Index variants, ReplaceAllString, ReplaceAllStringFunc, Expand and Split.

A compiled *regexp.Regexp has a large family of methods, but they follow a naming scheme that makes them easy to remember. Start with the operation (Match, Find, Replace, Split), add String if you work with strings instead of []byte, add All for every match instead of the first, add Submatch to also get the capture groups, and add Index to receive positions instead of text.

For example, FindAllStringSubmatchIndex finds all matches in a string and returns the byte offsets of the whole match and of each group.

Go
re := regexp.MustCompile(`(\w+)=(\w+)`)
fmt.Println(re.FindStringSubmatch("key=value")) // [key=value key value]

Try it

Go The Find family

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Go Replace and Split

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Syntax

Go
func (re *Regexp) MatchString(s string) bool
func (re *Regexp) FindString(s string) string
func (re *Regexp) FindStringIndex(s string) (loc []int)
func (re *Regexp) FindStringSubmatch(s string) []string
func (re *Regexp) FindStringSubmatchIndex(s string) []int
func (re *Regexp) FindAllString(s string, n int) []string
func (re *Regexp) FindAllStringSubmatch(s string, n int) [][]string
func (re *Regexp) ReplaceAllString(src, repl string) string
func (re *Regexp) ReplaceAllLiteralString(src, repl string) string
func (re *Regexp) ReplaceAllStringFunc(src string, repl func(string) string) string
func (re *Regexp) Split(s string, n int) []string
func (re *Regexp) ExpandString(dst []byte, template string, src string, match []int) []byte
func (re *Regexp) SubexpNames() []string
func (re *Regexp) SubexpIndex(name string) int
func (re *Regexp) NumSubexp() int
func (re *Regexp) Longest()
func (re *Regexp) String() string

Each String method has a []byte twin without String in the name (Find, FindAll, ReplaceAll, ...), and the Reader variants (MatchReader, FindReaderIndex, FindReaderSubmatchIndex) accept an io.RuneReader.

Parameter Description
s, src The text to search.
n Maximum number of results for the All and Split methods. A negative n means no limit. For Split, 0 returns nil and 1 returns the whole string.
repl Replacement text, where $1 or ${name} expand to groups and $$ is a literal dollar sign.
match A slice of index pairs as returned by a SubmatchIndex method.

Returns:

  • Find... returns the leftmost match, or the empty string / nil when nothing matches. Because an empty match is also possible, use the Index form or MatchString to tell the two apart.
  • ...Submatch returns a slice where element 0 is the whole match and element i is group i. A group that did not take part is "" in the string form and -1, -1 in the index form.
  • Index forms return byte offsets [start, end) pairs, ready for slicing.

Usage notes

  • Replacement syntax pitfall: $1_user is read as the group named 1_user, which does not exist, so it expands to nothing. Write ${1}_user. Use ReplaceAllLiteralString when the replacement may contain dollar signs.
  • ReplaceAllStringFunc receives only the matched text, not the groups. To work with groups in code, loop over FindAllStringSubmatchIndex and build the result yourself, or call ExpandString.
  • Empty matches are allowed: a* matches the empty string between characters, so replacing it inserts text at several positions. An empty match directly after a previous match is ignored.
  • Allocation: MatchString allocates nothing; the Find methods allocate result slices. Prefer FindStringIndex and slicing when performance matters.
  • Group names: SubexpNames()[i] is the name of group i (empty for unnamed groups; index 0 is always empty). SubexpIndex returns -1 for an unknown name.
  • n for All methods limits results: FindAllString(s, 2) returns at most two matches.
  • Safe for concurrent use, except for calling Longest while other goroutines use the same value.