coregex

func (*Regex) Count ¶ added in v0.4.0

func (r *Regex) Count(b []byte, n int) int

Count returns the number of non-overlapping matches of the pattern in b. If n > 0, counts at most n matches. If n <= 0, counts all matches.

This is optimized for counting without building result slices.

Example:

re := coregex.MustCompile(`\d+`)
count := re.Count([]byte("1 2 3 4 5"), -1)
// count == 5

func (*Regex) CountString ¶ added in v0.4.0

func (r *Regex) CountString(s string, n int) int

CountString returns the number of non-overlapping matches of the pattern in s. If n > 0, counts at most n matches. If n <= 0, counts all matches.

Example:

re := coregex.MustCompile(`\d+`)
count := re.CountString("1 2 3 4 5", -1)
// count == 5

func (*Regex) Expand ¶ added in v0.10.7

func (r *Regex) Expand(dst []byte, template []byte, src []byte, match []int) []byte

Expand appends template to dst and returns the result; during the append, Expand replaces variables in the template with corresponding matches drawn from src. The match slice should contain the progressively numbered submatches as returned by FindSubmatchIndex.

In the template, a variable is denoted by a substring of the form $name or ${name}, where name is a non-empty sequence of letters, digits, and underscores. A purely numeric name like $1 refers to the submatch with the corresponding index; other names refer to capturing parentheses named with the (?P<name>...) syntax. A reference to an out of range or unmatched index or a name that is not present in the regular expression is replaced with an empty slice.

In the $name form, name is taken to be as long as possible: $1x is equivalent to ${1x}, not ${1}x, and, $10 is equivalent to ${10}, not ${1}0.

To insert a literal $ in the output, use $$ in the template.

func (*Regex) ExpandString ¶ added in v0.10.7

func (r *Regex) ExpandString(dst []byte, template string, src string, match []int) []byte

ExpandString is like Expand but the template and source are strings. It appends to and returns a byte slice in order to give the caller control over allocation.

func (*Regex) Find ¶

func (r *Regex) Find(b []byte) []byte

Find returns a slice holding the text of the leftmost match in b. Returns nil if no match is found.

Example:

re := coregex.MustCompile(`\d+`)
match := re.Find([]byte("age: 42"))
println(string(match)) // "42"

package main

import (
	"fmt"

	"github.com/coregx/coregex"
)

func main() {
	re := coregex.MustCompile(`\d+`)
	match := re.Find([]byte("age: 42 years"))
	fmt.Println(string(match))
}

Output:

42

func (*Regex) FindAll ¶

func (r *Regex) FindAll(b []byte, n int) [][]byte

FindAll returns a slice of all successive matches of the pattern in b. If n > 0, it returns at most n matches. If n <= 0, it returns all matches.

Example:

re := coregex.MustCompile(`\d+`)
matches := re.FindAll([]byte("1 2 3"), -1)
// matches = [[]byte("1"), []byte("2"), []byte("3")]

package main

import (
	"fmt"

	"github.com/coregx/coregex"
)

func main() {
	re := coregex.MustCompile(`\d`)
	matches := re.FindAll([]byte("a1b2c3"), -1)
	for _, m := range matches {
		fmt.Print(string(m), " ")
	}
	fmt.Println()
}

Output:

1 2 3

func (*Regex) FindAllIndex ¶ added in v0.3.0

func (r *Regex) FindAllIndex(b []byte, n int) [][]int

FindAllIndex returns a slice of all successive matches of the pattern in b, as index pairs [start, end]. If n > 0, it returns at most n matches. If n <= 0, it returns all matches.

Example:

re := coregex.MustCompile(`\d+`)
indices := re.FindAllIndex([]byte("1 2 3"), -1)
// indices = [[0,1], [2,3], [4,5]]

func (*Regex) FindAllIndexCompact ¶ added in v0.10.6

func (r *Regex) FindAllIndexCompact(b []byte, n int, results [][2]int) [][2]int

FindAllIndexCompact returns all successive matches as a compact [][2]int slice. This is a zero-allocation API (single allocation for the result slice). Unlike FindAllIndex which returns [][]int (N allocations for N matches), this method pre-allocates the entire result in one contiguous block.

Performance: ~2x fewer allocations than FindAllIndex for high match counts.

If n > 0, it returns at most n matches. If n <= 0, it returns all matches. The optional 'results' slice can be provided for reuse (set to nil for fresh allocation).

Example:

re := coregex.MustCompile(`\d+`)
indices := re.FindAllIndexCompact([]byte("a1b2c3"), -1, nil)
// indices = [[1,2], [3,4], [5,6]]

func (*Regex) FindAllString ¶

func (r *Regex) FindAllString(s string, n int) []string

FindAllString returns a slice of all successive matches of the pattern in s. If n > 0, it returns at most n matches. If n <= 0, it returns all matches.

Example:

re := coregex.MustCompile(`\d+`)
matches := re.FindAllString("1 2 3", -1)
// matches = ["1", "2", "3"]

package main

import (
	"fmt"

	"github.com/coregx/coregex"
)

func main() {
	re := coregex.MustCompile(`\w+`)
	words := re.FindAllString("hello world test", -1)
	for _, word := range words {
		fmt.Print(word, " ")
	}
	fmt.Println()
}

Output:

hello world test

func (*Regex) FindAllStringIndex ¶ added in v0.3.0

func (r *Regex) FindAllStringIndex(s string, n int) [][]int

FindAllStringIndex returns a slice of all successive matches of the pattern in s, as index pairs [start, end]. If n > 0, it returns at most n matches. If n <= 0, it returns all matches.

Example:

re := coregex.MustCompile(`\d+`)
indices := re.FindAllStringIndex("1 2 3", -1)
// indices = [[0,1], [2,3], [4,5]]

func (*Regex) FindAllStringIndexCompact ¶ added in v0.10.6

func (r *Regex) FindAllStringIndexCompact(s string, n int, results [][2]int) [][2]int

FindAllStringIndexCompact returns all successive matches as a compact [][2]int slice. This is the string version of FindAllIndexCompact.

func (*Regex) FindAllStringSubmatch ¶ added in v0.4.0

func (r *Regex) FindAllStringSubmatch(s string, n int) [][]string

FindAllStringSubmatch returns a slice of all successive matches of the pattern in s, where each match includes all capture groups as strings. If n > 0, returns at most n matches. If n <= 0, returns all matches.

Example:

re := coregex.MustCompile(`(\w+)@(\w+)\.(\w+)`)
matches := re.FindAllStringSubmatch("[email protected] [email protected]", -1)
// len(matches) == 2
// matches[0][0] = "[email protected]"
// matches[0][1] = "a"

func (*Regex) FindAllStringSubmatchIndex ¶ added in v0.4.0

func (r *Regex) FindAllStringSubmatchIndex(s string, n int) [][]int

FindAllStringSubmatchIndex returns a slice of all successive matches of the pattern in s, where each match includes index pairs for all capture groups. If n > 0, returns at most n matches. If n <= 0, returns all matches.

Example:

re := coregex.MustCompile(`(\w+)@(\w+)\.(\w+)`)
indices := re.FindAllStringSubmatchIndex("[email protected] [email protected]", -1)

func (*Regex) FindAllSubmatch ¶ added in v0.4.0

func (r *Regex) FindAllSubmatch(b []byte, n int) [][][]byte

FindAllSubmatch returns a slice of all successive matches of the pattern in b, where each match includes all capture groups. If n > 0, returns at most n matches. If n <= 0, returns all matches.

Example:

re := coregex.MustCompile(`(\w+)@(\w+)\.(\w+)`)
matches := re.FindAllSubmatch([]byte("[email protected] [email protected]"), -1)
// len(matches) == 2
// matches[0][0] = "[email protected]"
// matches[0][1] = "a"

func (*Regex) FindAllSubmatchIndex ¶ added in v0.4.0

func (r *Regex) FindAllSubmatchIndex(b []byte, n int) [][]int

FindAllSubmatchIndex returns a slice of all successive matches of the pattern in b, where each match includes index pairs for all capture groups. If n > 0, returns at most n matches. If n <= 0, returns all matches.

Example:

re := coregex.MustCompile(`(\w+)@(\w+)\.(\w+)`)
indices := re.FindAllSubmatchIndex([]byte("[email protected] [email protected]"), -1)
// len(indices) == 2
// indices[0] contains start/end pairs for each group

func (*Regex) FindIndex ¶

func (r *Regex) FindIndex(b []byte) []int

FindIndex returns a two-element slice of integers defining the location of the leftmost match in b. The match is at b[loc[0]:loc[1]]. Returns nil if no match is found.

Example:

re := coregex.MustCompile(`\d+`)
loc := re.FindIndex([]byte("age: 42"))
println(loc[0], loc[1]) // 5, 7

package main

import (
	"fmt"

	"github.com/coregx/coregex"
)

func main() {
	re := coregex.MustCompile(`\d+`)
	loc := re.FindIndex([]byte("age: 42"))
	fmt.Printf("Match at [%d:%d]\n", loc[0], loc[1])
}

Output:

Match at [5:7]

func (*Regex) FindReaderIndex ¶ added in v0.10.7

func (r *Regex) FindReaderIndex(reader io.RuneReader) []int

FindReaderIndex returns a two-element slice of integers defining the location of the leftmost match of the regular expression in text read from the RuneReader. The match text was found in the input stream at byte offset loc[0] through loc[1]-1. A return value of nil indicates no match.

func (*Regex) FindReaderSubmatchIndex ¶ added in v0.10.7

func (r *Regex) FindReaderSubmatchIndex(reader io.RuneReader) []int

FindReaderSubmatchIndex returns a slice holding the index pairs identifying the leftmost match of the regular expression of text read by the RuneReader, and the matches, if any, of its subexpressions, as defined by the 'Submatch' and 'Index' descriptions in the package comment. A return value of nil indicates no match.

func (*Regex) FindString ¶

func (r *Regex) FindString(s string) string

FindString returns a string holding the text of the leftmost match in s. Returns empty string if no match is found.

Example:

re := coregex.MustCompile(`\d+`)
match := re.FindString("age: 42")
println(match) // "42"

package main

import (
	"fmt"

	"github.com/coregx/coregex"
)

func main() {
	re := coregex.MustCompile(`\w+@\w+\.\w+`)
	email := re.FindString("Contact: [email protected]")
	fmt.Println(email)
}

Output:

[email protected]

func (*Regex) FindStringIndex ¶

func (r *Regex) FindStringIndex(s string) []int

FindStringIndex returns a two-element slice of integers defining the location of the leftmost match in s. The match is at s[loc[0]:loc[1]]. Returns nil if no match is found.

Example:

re := coregex.MustCompile(`\d+`)
loc := re.FindStringIndex("age: 42")
println(loc[0], loc[1]) // 5, 7

func (*Regex) FindStringSubmatch ¶ added in v0.2.0

func (r *Regex) FindStringSubmatch(s string) []string

FindStringSubmatch returns a slice of strings holding the text of the leftmost match and the matches of all capture groups.

Example:

re := coregex.MustCompile(`(\w+)@(\w+)\.(\w+)`)
match := re.FindStringSubmatch("[email protected]")
// match[0] = "[email protected]"
// match[1] = "user"

package main

import (
	"fmt"

	"github.com/coregx/coregex"
)

func main() {
	re := coregex.MustCompile(`(\d{4})-(\d{2})-(\d{2})`)
	match := re.FindStringSubmatch("Date: 2024-12-25")
	if match != nil {
		fmt.Printf("Year: %s, Month: %s, Day: %s\n", match[1], match[2], match[3])
	}
}

Output:

Year: 2024, Month: 12, Day: 25

func (*Regex) FindStringSubmatchIndex ¶ added in v0.2.0

func (r *Regex) FindStringSubmatchIndex(s string) []int

FindStringSubmatchIndex returns the index pairs for the leftmost match and capture groups. Same as FindSubmatchIndex but for strings.

func (*Regex) FindSubmatch ¶ added in v0.2.0

func (r *Regex) FindSubmatch(b []byte) [][]byte

FindSubmatch returns a slice holding the text of the leftmost match and the matches of all capture groups.

A return value of nil indicates no match. Result[0] is the entire match, result[i] is the ith capture group. Unmatched groups will be nil.

Example:

re := coregex.MustCompile(`(\w+)@(\w+)\.(\w+)`)
match := re.FindSubmatch([]byte("[email protected]"))
// match[0] = "[email protected]"
// match[1] = "user"
// match[2] = "example"
// match[3] = "com"

package main

import (
	"fmt"

	"github.com/coregx/coregex"
)

func main() {
	re := coregex.MustCompile(`(\w+)@(\w+)\.(\w+)`)
	match := re.FindSubmatch([]byte("Contact: [email protected]"))
	if match != nil {
		fmt.Println("Full match:", string(match[0]))
		fmt.Println("User:", string(match[1]))
		fmt.Println("Domain:", string(match[2]))
		fmt.Println("TLD:", string(match[3]))
	}
}

Output:

Full match: [email protected]
User: user
Domain: example
TLD: com

func (*Regex) FindSubmatchIndex ¶ added in v0.2.0

func (r *Regex) FindSubmatchIndex(b []byte) []int

FindSubmatchIndex returns a slice holding the index pairs for the leftmost match and the matches of all capture groups.

A return value of nil indicates no match. Result[2*i:2*i+2] is the indices for the ith group. Unmatched groups have -1 indices.

Example:

re := coregex.MustCompile(`(\w+)@(\w+)\.(\w+)`)
idx := re.FindSubmatchIndex([]byte("[email protected]"))
// idx[0:2] = indices for entire match
// idx[2:4] = indices for first capture group

func (*Regex) LiteralPrefix ¶ added in v0.10.7

func (r *Regex) LiteralPrefix() (prefix string, complete bool)

LiteralPrefix returns a literal string that must begin any match of the regular expression re. It returns the boolean true if the literal string comprises the entire regular expression.

Example:

re := coregex.MustCompile(`Hello, \w+`)
prefix, complete := re.LiteralPrefix()
// prefix = "Hello, ", complete = false

re2 := coregex.MustCompile(`Hello`)
prefix2, complete2 := re2.LiteralPrefix()
// prefix2 = "Hello", complete2 = true

func (*Regex) Longest ¶ added in v0.8.2

func (r *Regex) Longest()

Longest makes future searches prefer the leftmost-longest match.

By default, coregex uses leftmost-first (Perl) semantics where the first alternative in an alternation wins. After calling Longest(), coregex uses leftmost-longest (POSIX) semantics where the longest match wins.

Example:

re := coregex.MustCompile(`(a|ab)`)
re.FindString("ab")    // returns "a" (leftmost-first: first branch wins)

re.Longest()
re.FindString("ab")    // returns "ab" (leftmost-longest: longest wins)

Note: Unlike stdlib, calling Longest() modifies the regex state and should not be called concurrently with search methods.

func (*Regex) MarshalText ¶ added in v0.10.7

func (r *Regex) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler. The output is the result of r.String().

func (*Regex) Match ¶

func (r *Regex) Match(b []byte) bool

Match reports whether the byte slice b contains any match of the pattern.

Example:

re := coregex.MustCompile(`\d+`)
if re.Match([]byte("hello 123")) {
    println("contains digits")
}

func (*Regex) MatchReader ¶ added in v0.10.7

func (r *Regex) MatchReader(reader io.RuneReader) bool

MatchReader reports whether the text returned by the RuneReader contains any match of the regular expression re.

func (*Regex) MatchString ¶

func (r *Regex) MatchString(s string) bool

MatchString reports whether the string s contains any match of the pattern. This is a zero-allocation operation (like Rust's is_match).

Example:

re := coregex.MustCompile(`hello`)
if re.MatchString("hello world") {
    println("matched!")
}

func (*Regex) NumSubexp ¶ added in v0.2.0

func (r *Regex) NumSubexp() int

NumSubexp returns the number of parenthesized subexpressions in this Regex. This does NOT include group 0 (the entire match), matching stdlib regexp behavior.

Example:

re := coregex.MustCompile(`(\w+)@(\w+)\.(\w+)`)
println(re.NumSubexp()) // 3 (just the capture groups)

package main

import (
	"fmt"

	"github.com/coregx/coregex"
)

func main() {
	re := coregex.MustCompile(`(\w+)@(\w+)\.(\w+)`)
	fmt.Println("Number of groups:", re.NumSubexp())
}

Output:

Number of groups: 3

func (*Regex) ReplaceAll ¶ added in v0.3.0

func (r *Regex) ReplaceAll(src, repl []byte) []byte

ReplaceAll returns a copy of src, replacing matches of the pattern with the replacement bytes repl. Inside repl, $ signs are interpreted as in Regexp.Expand: $0 is the entire match, $1 is the first capture group, etc.

Example:

re := coregex.MustCompile(`(\w+)@(\w+)\.(\w+)`)
result := re.ReplaceAll([]byte("[email protected]"), []byte("$1 at $2 dot $3"))
// result = []byte("user at example dot com")

func (*Regex) ReplaceAllFunc ¶ added in v0.3.0

func (r *Regex) ReplaceAllFunc(src []byte, repl func([]byte) []byte) []byte

ReplaceAllFunc returns a copy of src in which all matches of the pattern have been replaced by the return value of function repl applied to the matched byte slice. The replacement returned by repl is substituted directly, without using Expand.

Example:

re := coregex.MustCompile(`\d+`)
result := re.ReplaceAllFunc([]byte("1 2 3"), func(s []byte) []byte {
    n, _ := strconv.Atoi(string(s))
    return []byte(strconv.Itoa(n * 2))
})
// result = []byte("2 4 6")

func (*Regex) ReplaceAllLiteral ¶ added in v0.3.0

func (r *Regex) ReplaceAllLiteral(src, repl []byte) []byte

ReplaceAllLiteral returns a copy of src, replacing matches of the pattern with the replacement bytes repl. The replacement is substituted directly, without expanding $ variables.

Example:

re := coregex.MustCompile(`\d+`)
result := re.ReplaceAllLiteral([]byte("age: 42"), []byte("XX"))
// result = []byte("age: XX")

func (*Regex) ReplaceAllLiteralString ¶ added in v0.3.0

func (r *Regex) ReplaceAllLiteralString(src, repl string) string

ReplaceAllLiteralString returns a copy of src, replacing matches of the pattern with the replacement string repl. The replacement is substituted directly, without expanding $ variables.

Example:

re := coregex.MustCompile(`\d+`)
result := re.ReplaceAllLiteralString("age: 42", "XX")
// result = "age: XX"

func (*Regex) ReplaceAllString ¶ added in v0.3.0

func (r *Regex) ReplaceAllString(src, repl string) string

ReplaceAllString returns a copy of src, replacing matches of the pattern with the replacement string repl. Inside repl, $ signs are interpreted as in Regexp.Expand: $0 is the entire match, $1 is the first capture group, etc.

Example:

re := coregex.MustCompile(`(\w+)@(\w+)\.(\w+)`)
result := re.ReplaceAllString("[email protected]", "$1 at $2 dot $3")
// result = "user at example dot com"

func (*Regex) ReplaceAllStringFunc ¶ added in v0.3.0

func (r *Regex) ReplaceAllStringFunc(src string, repl func(string) string) string

ReplaceAllStringFunc returns a copy of src in which all matches of the pattern have been replaced by the return value of function repl applied to the matched string. The replacement returned by repl is substituted directly, without using Expand.

Example:

re := coregex.MustCompile(`\d+`)
result := re.ReplaceAllStringFunc("1 2 3", func(s string) string {
    n, _ := strconv.Atoi(s)
    return strconv.Itoa(n * 2)
})
// result = "2 4 6"

func (*Regex) Split ¶ added in v0.3.0

func (r *Regex) Split(s string, n int) []string

Split slices s into substrings separated by the expression and returns a slice of the substrings between those expression matches.

The slice returned by this method consists of all the substrings of s not contained in the slice returned by FindAllString. When called on an expression that contains no metacharacters, it is equivalent to strings.SplitN.

The count determines the number of substrings to return:

n > 0: at most n substrings; the last substring will be the unsplit remainder.
n == 0: the result is nil (zero substrings)
n < 0: all substrings

Example:

re := coregex.MustCompile(`,`)
parts := re.Split("a,b,c", -1)
// parts = ["a", "b", "c"]

parts = re.Split("a,b,c", 2)
// parts = ["a", "b,c"]

func (*Regex) String ¶

func (r *Regex) String() string

String returns the source text used to compile the regular expression.

Example:

re := coregex.MustCompile(`\d+`)
println(re.String()) // `\d+`

func (*Regex) SubexpIndex ¶ added in v0.10.7

func (r *Regex) SubexpIndex(name string) int

SubexpIndex returns the index of the first subexpression with the given name, or -1 if there is no subexpression with that name.

Note that multiple subexpressions can be written using the same name, as in (?P<bob>a+)(?P<bob>b+), which declares two subexpressions named "bob". In this case, SubexpIndex returns the index of the leftmost such subexpression in the regular expression.

Example:

re := coregex.MustCompile(`(?P<year>\d+)-(?P<month>\d+)`)
re.SubexpIndex("year")  // returns 1
re.SubexpIndex("month") // returns 2
re.SubexpIndex("day")   // returns -1

func (*Regex) SubexpNames ¶ added in v0.5.0

func (r *Regex) SubexpNames() []string

SubexpNames returns the names of the parenthesized subexpressions in this Regex. The name for the first sub-expression is names[1], so that if m is a match slice, the name for m[i] is SubexpNames()[i]. Since the Regexp as a whole cannot be named, names[0] is always the empty string. The slice returned is shared and must not be modified.

Example:

re := coregex.MustCompile(`(?P<year>\d+)-(?P<month>\d+)`)
names := re.SubexpNames()
// names[0] = ""
// names[1] = "year"
// names[2] = "month"

package main

import (
	"fmt"

	"github.com/coregx/coregex"
)

func main() {
	// Pattern with named and unnamed captures
	re := coregex.MustCompile(`(?P<year>\d{4})-(?P<month>\d{2})-(\d{2})`)

	// Get capture group names
	// Note: SubexpNames includes group 0 (empty string for full match)
	// but NumSubexp only counts parenthesized subexpressions (groups 1-3)
	names := re.SubexpNames()
	fmt.Printf("Capture groups: %d\n", re.NumSubexp())
	fmt.Printf("Group 0 (full match): %q\n", names[0])
	fmt.Printf("Group 1 (year): %q\n", names[1])
	fmt.Printf("Group 2 (month): %q\n", names[2])
	fmt.Printf("Group 3 (day, unnamed): %q\n", names[3])

}

Output:

Capture groups: 3
Group 0 (full match): ""
Group 1 (year): "year"
Group 2 (month): "month"
Group 3 (day, unnamed): ""

package main

import (
	"fmt"

	"github.com/coregx/coregex"
)

func main() {
	// Compile pattern with named captures
	re := coregex.MustCompile(`(?P<protocol>https?)://(?P<domain>\w+)`)

	// Find match and get submatch values
	match := re.FindStringSubmatch("Visit https://example for more")
	names := re.SubexpNames()

	// Print matches with their names
	for i, name := range names {
		if i < len(match) && match[i] != "" {
			if name != "" {
				fmt.Printf("%s: %s\n", name, match[i])
			} else if i == 0 {
				fmt.Printf("Full match: %s\n", match[i])
			}
		}
	}

}

Output:

Full match: https://example
protocol: https
domain: example

func (*Regex) UnmarshalText ¶ added in v0.10.7

func (r *Regex) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler by calling Compile on the encoded value.