当函数名中有 All 的时候,它会继续查找非重叠的后续并返回 slice

当函数名中有 String 的时候,参数及返回值都是 string，否则为 []byte

IsMatch/IsMatchString

• 说明： IsMatch()方法可以测试字符串，判断是否匹配正则表达式的模式。如果发现一次匹配，该方法返回true，否则返回false。

• 格式：

  IsMatch(pattern string, src []byte) bool
  IsMatchString(pattern string, src string) bool

• Tip: regexp已经在底层处理并缓存了Regex对象，以极大地提高执行效率，无需每次显式重新创建，下同。

• 示例：

  func ExampleIsMatch() {
  	patternStr := `\d+`
  	g.Dump(gregex.IsMatch(patternStr, []byte("hello 2022! hello gf!")))
  	g.Dump(gregex.IsMatch(patternStr, nil))
  	g.Dump(gregex.IsMatch(patternStr, []byte("hello gf!")))
  
  	// Output:
  	// true
  	// false
  	// false
  }

Match/MatchString

• 说明：用来匹配子字符串，Match只返回第一个匹配的结果。区别于原生的正则方法，gregex是对 FindSubmatch 进行封装，直接返回第一个包括子模式结果的 slice。

• 格式

  Match(pattern string, src []byte) ([][]byte, error)
  MatchString(pattern string, src string) ([]string, error)

• 示例：匹配 url 中的参数。

  func ExampleMatch() {
  	patternStr := `(\w+)=(\w+)`
  	matchStr := "https://goframe.org/pages/viewpage.action?pageId=1114219&searchId=8QC5D1D2E!"
  	// This method looks for the first match index
  	result, err := gregex.Match(patternStr, []byte(matchStr))
  	g.Dump(result)
  	g.Dump(err)
  
  	// Output:
  	// [
  	//     "pageId=1114219",
  	//     "pageId",
  	//     "1114219",
  	// ]
  	// <nil>
  }

MatchAll/MatchAllString

• 说明：用来匹配子字符串，MatchAll返回全部的结果。区别于原生的正则方法，gregex 的 MatchAll 是对FindAllSubmatch方法进行封装，返回所有结果集的 slice，包括结果集中的子模式的结果。

• 格式：

  MatchAllString(pattern string, src string) ([][]string, error)
  MatchAll(pattern string, src []byte) ([][][]byte, error)

• 示例：下面这个例子是匹配 url 中的参数。

  func ExampleMatchString() {
  	patternStr := `(\w+)=(\w+)`
  	matchStr := "https://goframe.org/pages/viewpage.action?pageId=1114219&searchId=8QC5D1D2E!"
  	// This method looks for the first match index
  	result, err := gregex.MatchString(patternStr, matchStr)
  	g.Dump(result)
  	g.Dump(err)
  
  	// Output:
  	// [
  	//     "pageId=1114219",
  	//     "pageId",
  	//     "1114219",
  	// ]
  	// <nil>
  }

Quote

• 说明：将指定正则表达式中的特定符号进行转义。

• 格式：

  Quote(s string) string

• 示例：

  func ExampleQuote() {
  	result := gregex.Quote(`[1-9]\d+`)
  	g.Dump(result)
  
  	// Output:
  	// "\[1-9\]\\d\+"
  }

Replace/ReplaceString

• 说明：用来替换所有匹配的字符串并返回一个源字符串的拷贝。

• 格式:

  Replace(pattern string, replace, src []byte) ([]byte, error)
  ReplaceString(pattern, replace, src string) (string, error)

• 示例

  func ExampleReplace() {
  	var (
  		patternStr  = `\d+`
  		str         = "hello gf 2020!"
  		repStr      = "2021"
  		result, err = gregex.Replace(patternStr, []byte(repStr), []byte(str))
  	)
  	g.Dump(err)
  	g.Dump(result)
  
  	// Output:
  	// <nil>
  	// "hello gf 2021!"
  }

ReplaceFunc/ReplaceStringFunc

• 说明：用来替换所有匹配的字符串，返回一个源字符串的拷贝。与Replace 方法的区别在于，该方法可以在闭包中对查询进行二次判断或处理，而非简单的替换。

• 格式：

  ReplaceFuncMatch(pattern string, src []byte, replaceFunc func(match [][]byte) []byte) ([]byte, error)
  ReplaceStringFunc(pattern string, src string, replaceFunc func(s string) string) (string, error)

• 示例：

  func ExampleReplaceFuncMatch() {
  	var (
  		patternStr = `(\d+)~(\d+)`
  		str        = "hello gf 2018~2020!"
  	)
  	// In contrast to [ExampleReplaceFunc]
  	// the result contains the `pattern' of all subpatterns that use the matching function
  	result, err := gregex.ReplaceFuncMatch(patternStr, []byte(str), func(match [][]byte) []byte {
  		g.Dump(match)
  		match[2] = []byte("2021")
  		return bytes.Join(match[1:], []byte("-"))
  	})
  	g.Dump(result)
  	g.Dump(err)
  
  	// Output:
  	// [
  	//     "2018~2020",
  	//     "2018",
  	//     "2020",
  	// ]
  	// "hello gf 2018-2021!"
  	// <nil>
  }

ReplaceFuncMatch/ReplaceStringFuncMatch

ReplaceFuncMatch返回src的拷贝，其中regexp的所有匹配都被应用于匹配字节切片的函数的返回值替换。 返回的替换直接替换。

• 说明：用来替换所有匹配的字符串，返回一个源字符串的拷贝。该方法的强大之处在于可以在闭包中对查询进行二次判断或处理，且 MatchString 函数包含了所有子模式的查询结果，而非简单的替换。

• 格式：

  ReplaceFuncMatch(pattern string, src []byte, replaceFunc func(match [][]byte) []byte) ([]byte, error)
  ReplaceStringFuncMatch(pattern string, src string, replaceFunc func(match []string) string) (string, error)

• 示例：

  func ExampleReplaceStringFuncMatch() {
  	var (
  		patternStr = `([A-Z])\w+`
  		str        = "hello Golang 2018~2021!"
  	)
  	// In contrast to [ExampleReplaceFunc]
  	// the result contains the `pattern' of all subpatterns that use the matching function
  	result, err := gregex.ReplaceStringFuncMatch(patternStr, str, func(match []string) string {
  		g.Dump(match)
  		match[0] = "Gf"
  		return match[0]
  	})
  	g.Dump(result)
  	g.Dump(err)
  
  	// Output:
  	// [
  	//     "Golang",
  	//     "G",
  	// ]
  	// "hello Gf 2018~2021!"
  	// <nil>
  }

Split

• 说明：将文本内容由指定的正则表达式进行切割。不包含元字符，相当于strings.SplitN。

• 格式：

  Split(pattern string, src string) []string

• 示例：

  func ExampleSplit() {
  	patternStr := `\d+`
  	str := "hello2020gf"
  	result := gregex.Split(patternStr, str)
  	g.Dump(result)
  
  	// Output:
  	// [
  	//     "hello",
  	//     "gf",
  	// ]
  }

Validate

• 说明：基于原生方法 compile 封装，检查给定的正则表达式是否有效

• 格式：

  Validate(pattern string) error

• 示例：

  func ExampleValidate() {
  	// Valid match statement
  	g.Dump(gregex.Validate(`\d+`))
  	// Mismatched statement
  	g.Dump(gregex.Validate(`[a-9]\d+`))
  
  	// Output:
  	// <nil>
  	// {
  	//     Code: "invalid character class range",
  	//     Expr: "a-9",
  	// }
  }