= Go regexp =

The '''`regexp`''' package provides regular expression functions.

<<TableOfContents>>

----



== Example ==

{{{
package main

import (
    "fmt"
    "regexp"
)

var (
    Pattern = regexp.MustCompile(`^Chapter ([0-9]+)$`)
)

func main() {
    content := "Chapter 13 and Chapter 14"

    match := Pattern.FindString(content) // "Chapter 13"

    loc := Pattern.FindStringIndex(content) // [0 10]
    match = content[loc[0]:loc[1]]          // "Chapter 13"

    matches := Pattern.FindStringSubmatch(content)
    match = matches[0]   // "Chapter 13"
    number := matches[1] // "13"

    loc = Pattern.FindStringSubmatchIndex(content) // [0 10 8 10]
    match = content[loc[0]:loc[1]]                  // "Chapter 13"
    number = content[loc[2]:loc[3]]                 // "13

    if Pattern.MatchString(content) {
        fmt.Println("yes!")
    }

    matches = Pattern.FindAllString(content, -1) // ["Chapter 13" "Chapter 14"]

    locs := Pattern.FindAllStringIndex(content, -1) // [[0 10] [15 25]]
    match1 := content[locs[0][0]:locs[0][1]]        // "Chapter 13"
    match2 := content[locs[1][0]:locs[1][1]]        // "Chapter 14"

    all_matches := Pattern.FindAllStringSubmatch(content, -1)
    match1 = all_matches[0][0]   // "Chapter 13"
    number1 := all_matches[0][1] // "13"
    match2 = all_matches[1][0]   // "Chapter 14"
    number2 := all_matches[1][1] // "14"

    locs = Pattern.FindAllStringSubmatchIndex(content, -1) // [[0 10 8 10] [15 25 23 25]]
    match1 = content[locs[0][0]:locs[0][1]]                // "Chapter 13"
    number1 = content[locs[0][2]:locs[0][3]]               // "13"
    match2 = content[locs[1][0]:locs[1][1]]                // "Chapter 14"
    number2 = content[locs[1][2]:locs[1][3]]               // "14"
}
}}}

----



== Functions ==

These functions test if some content matches a compiled regular expression.

||'''Name'''   ||'''Signature'''                                   ||
||`Match`      ||`(*regexp.Regexp) Match([]byte) bool`             ||
||`MatchString`||`(*regexp.Regexp) MatchString(string) bool`       ||
||`MatchReader`||`(*regexp.Regexp) MatchReader(io.RuneReader) bool`||

These functions return the subcontent that represent the left-most match to a compiled regular expression. If the function name includes `Index`, then the returned values are start and end indices.

||'''Name'''       ||'''Signature'''                                 ||'''Returned if no match'''||
||`Find`           ||`(*Regexp) Find([]byte) []byte`                 ||nil                       ||
||`FindString`     ||`(*Regexp) FindString(string) string`           ||""                        ||
||`FindIndex`      ||`(*Regexp) FindIndex([]byte) []int`             ||nil                       ||
||`FindStringIndex`||`(*Regexp) FindStringIndex(string) []int`       ||nil                       ||
||`FindReaderIndex`||`(*Regexp) FindReaderIndex(io.RuneReader) []int`||nil                       ||

These functions return the array of subcontents that represents all matches to a compiled regular expression. The second argument limits how many matches to find; -1 causes all matches to be found.

||'''Name'''          ||'''Signature'''                                      ||'''Returned if no match'''||
||`FindAll`           ||`(*Regexp) FindAll([]byte, int) [][]byte`            ||nil                       ||
||`FindAllString`     ||`(*Regexp) FindAllString(string, int) []string`      ||nil                       ||
||`FindAllIndex`      ||`(*Regexp) FindAllIndex([]byte, int) [][]int`        ||nil                       ||
||`FindAllStringIndex`||`(*Regexp) FindAllStringIndex([]byte, int) [][]int`  ||nil                       ||

These functions return the array of subcontents that represents
 1. the left-most match to a compiled regular expression
 2. all matches to capture groups in the expression

If the function name includes `Index`, then the returned values are paired start and end indices. For example, if there is one capture group, then the values are:
 1. start of match
 2. end of match
 3. start of capture group
 4. end of capture group.

If the function name includes `All`, then the returned values are arrays of arrays; the first level of depth represents each match, and the second level of depth represents the match and capture groups.

||'''Name'''                  ||'''Signature'''                                            ||'''Returned if no match'''||
||`FindSubmatch`              ||`(*Regexp) FindSubmatch([]byte) [][]byte`                  ||nil                       ||
||`FindStringSubmatch`        ||`(*Regexp) FindStringSubmatch(string) []string`            ||nil                       ||
||`FindSubmatchIndex`         ||`(*Regexp) FindSubmatchIndex([]byte) []int`                ||nil                       ||
||`FindStringSubmatchIndex`   ||`(*Regexp) FindStringSubmatchIndex(string) []int`          ||nil                       ||
||`FindReaderSubmatchIndex`   ||`(*Regexp) FindReaderSubmatchIndex(r io.RuneReader) []int` ||nil                       ||
||`FindAllSubmatch`           ||`(*Regexp) FindAllSubmatch([]byte, int) [][][]byte`        ||nil                       ||
||`FindAllStringSubmatch`     ||`(*Regexp) FindAllStringSubmatch(string, int) [][]string`  ||nil                       ||
||`FindAllSubmatchIndex`      ||`(*Regexp) FindAllSubmatchIndex([]byte, int) [][]int`      ||nil                       ||
||`FindAllStringSubmatchIndex`||`(*Regexp) FindAllStringSubmatchIndex(string, int) [][]int`||nil                       ||

There are also three shortcut functions where the first argument is an un-compiled regular expression:

||'''Name'''   ||'''Signature'''                                   ||
||`Match`      ||`Match(string, []byte) (bool, error)`             ||
||`MatchString`||`MatchString(string, string) (bool, error)`       ||
||`MatchReader`||`MatchReader(string, io.RuneReader) (bool, error)`||

Lastly, there are alternative functions for compiling regular expressions.

 * `Compile` and `CompilePOSIX` which return both the compilation and an error
 * `MustCompile` and `MustCompilePOSIX` which both panic if compilation fails

The functions with `POSIX` in the name conform to `egrep(1)` syntax.



----
CategoryRicottone