/regexp/regexp.go

  1// Use of this source code is governed by a BSD-style
  2// license that can be found in the LICENSE file.
  3
  4// Package regexp implements a simple regular expression library.
  5//
  6// The syntax of the regular expressions accepted is the same
  7// general syntax used by Perl, Python, and other languages.
  8// More precisely, it is the syntax accepted by RE2 and described at
  9// http://code.google.com/p/re2/wiki/Syntax, except for \C.
 10//
 11// All characters are UTF-8-encoded code points.
 12//
 13// There are 16 methods of Regexp that match a regular expression and identify
 14// the matched text.  Their names are matched by this regular expression:
 15//
 16//	Find(All)?(String)?(Submatch)?(Index)?
 17//
 18// If 'All' is present, the routine matches successive non-overlapping
 19// matches of the entire expression.  Empty matches abutting a preceding
 20// match are ignored.  The return value is a slice containing the successive
 21// return values of the corresponding non-'All' routine.  These routines take
 22// an extra integer argument, n; if n >= 0, the function returns at most n
 23// matches/submatches.
 24//
 25// If 'String' is present, the argument is a string; otherwise it is a slice
 26// of bytes; return values are adjusted as appropriate.
 27//
 28// If 'Submatch' is present, the return value is a slice identifying the
 29// successive submatches of the expression.  Submatches are matches of
 30// parenthesized subexpressions within the regular expression, numbered from
 31// left to right in order of opening parenthesis.  Submatch 0 is the match of
 32// the entire expression, submatch 1 the match of the first parenthesized
 33// subexpression, and so on.
 34//
 35// If 'Index' is present, matches and submatches are identified by byte index
 36// pairs within the input string: result[2*n:2*n+1] identifies the indexes of
 37// the nth submatch.  The pair for n==0 identifies the match of the entire
 38// expression.  If 'Index' is not present, the match is identified by the
 39// text of the match/submatch.  If an index is negative, it means that
 40// subexpression did not match any string in the input.
 41//
 42// There is also a subset of the methods that can be applied to text read
 43// from a RuneReader:
 44//
 45//	MatchReader, FindReaderIndex, FindReaderSubmatchIndex
 46//
 47// This set may grow.  Note that regular expression matches may need to
 48// examine text beyond the text returned by a match, so the methods that
 49// match text from a RuneReader may read arbitrarily far into the input
 50// before returning.
 51//
 52// (There are a few other methods that do not match this pattern.)
 53//
 54package regexp
 55
 56import (
 57	"bytes"
 58	"io"
 59	"os"
 60	"appengine-go-backports/regexp/syntax"
 61	"strconv"
 62	"strings"
 63	"sync"
 64	"utf8"
 65)
 66
 67var debug = false
 68
 69// Error is the local type for a parsing error.
 70type Error string
 71
 72func (e Error) String() string {
 73	return string(e)
 74}
 75
 76// Regexp is the representation of a compiled regular expression.
 77// The public interface is entirely through methods.
 78// A Regexp is safe for concurrent use by multiple goroutines.
 79type Regexp struct {
 80	// read-only after Compile
 81	expr           string         // as passed to Compile
 82	prog           *syntax.Prog   // compiled program
 83	prefix         string         // required prefix in unanchored matches
 84	prefixBytes    []byte         // prefix, as a []byte
 85	prefixComplete bool           // prefix is the entire regexp
 86	prefixRune     int            // first rune in prefix
 87	cond           syntax.EmptyOp // empty-width conditions required at start of match
 88	numSubexp      int
 89	longest        bool
 90
 91	// cache of machines for running regexp
 92	mu      sync.Mutex
 93	machine []*machine
 94}
 95
 96// String returns the source text used to compile the regular expression.
 97func (re *Regexp) String() string {
 98	return re.expr
 99}
100
101// Compile parses a regular expression and returns, if successful,
102// a Regexp object that can be used to match against text.
103//
104// When matching against text, the regexp returns a match that
105// begins as early as possible in the input (leftmost), and among those
106// it chooses the one that a backtracking search would have found first.
107// This so-called leftmost-first matching is the same semantics
108// that Perl, Python, and other implementations use, although this
109// package implements it without the expense of backtracking.
110// For POSIX leftmost-longest matching, see CompilePOSIX.
111func Compile(expr string) (*Regexp, os.Error) {
112	return compile(expr, syntax.Perl, false)
113}
114
115// CompilePOSIX is like Compile but restricts the regular expression
116// to POSIX ERE (egrep) syntax and changes the match semantics to
117// leftmost-longest.
118//
119// That is, when matching against text, the regexp returns a match that
120// begins as early as possible in the input (leftmost), and among those
121// it chooses a match that is as long as possible.
122// This so-called leftmost-longest matching is the same semantics
123// that early regular expression implementations used and that POSIX
124// specifies.
125//
126// However, there can be multiple leftmost-longest matches, with different
127// submatch choices, and here this package diverges from POSIX.
128// Among the possible leftmost-longest matches, this package chooses
129// the one that a backtracking search would have found first, while POSIX
130// specifies that the match be chosen to maximize the length of the first
131// subexpression, then the second, and so on from left to right.
132// The POSIX rule is computationally prohibitive and not even well-defined.
133// See http://swtch.com/~rsc/regexp/regexp2.html#posix for details.
134func CompilePOSIX(expr string) (*Regexp, os.Error) {
135	return compile(expr, syntax.POSIX, true)
136}
137
138func compile(expr string, mode syntax.Flags, longest bool) (*Regexp, os.Error) {
139	re, err := syntax.Parse(expr, mode)
140	if err != nil {
141		return nil, err
142	}
143	maxCap := re.MaxCap()
144	re = re.Simplify()
145	prog, err := syntax.Compile(re)
146	if err != nil {
147		return nil, err
148	}
149	regexp := &Regexp{
150		expr:      expr,
151		prog:      prog,
152		numSubexp: maxCap,
153		cond:      prog.StartCond(),
154		longest:   longest,
155	}
156	regexp.prefix, regexp.prefixComplete = prog.Prefix()
157	if regexp.prefix != "" {
158		// TODO(rsc): Remove this allocation by adding
159		// IndexString to package bytes.
160		regexp.prefixBytes = []byte(regexp.prefix)
161		regexp.prefixRune, _ = utf8.DecodeRuneInString(regexp.prefix)
162	}
163	return regexp, nil
164}
165
166// get returns a machine to use for matching re.
167// It uses the re's machine cache if possible, to avoid
168// unnecessary allocation.
169func (re *Regexp) get() *machine {
170	re.mu.Lock()
171	if n := len(re.machine); n > 0 {
172		z := re.machine[n-1]
173		re.machine = re.machine[:n-1]
174		re.mu.Unlock()
175		return z
176	}
177	re.mu.Unlock()
178	z := progMachine(re.prog)
179	z.re = re
180	return z
181}
182
183// put returns a machine to the re's machine cache.
184// There is no attempt to limit the size of the cache, so it will
185// grow to the maximum number of simultaneous matches
186// run using re.  (The cache empties when re gets garbage collected.)
187func (re *Regexp) put(z *machine) {
188	re.mu.Lock()
189	re.machine = append(re.machine, z)
190	re.mu.Unlock()
191}
192
193// MustCompile is like Compile but panics if the expression cannot be parsed.
194// It simplifies safe initialization of global variables holding compiled regular
195// expressions.
196func MustCompile(str string) *Regexp {
197	regexp, error := Compile(str)
198	if error != nil {
199		panic(`regexp: Compile(` + quote(str) + `): ` + error.String())
200	}
201	return regexp
202}
203
204// MustCompilePOSIX is like CompilePOSIX but panics if the expression cannot be parsed.
205// It simplifies safe initialization of global variables holding compiled regular
206// expressions.
207func MustCompilePOSIX(str string) *Regexp {
208	regexp, error := CompilePOSIX(str)
209	if error != nil {
210		panic(`regexp: CompilePOSIX(` + quote(str) + `): ` + error.String())
211	}
212	return regexp
213}
214
215func quote(s string) string {
216	if strconv.CanBackquote(s) {
217		return "`" + s + "`"
218	}
219	return strconv.Quote(s)
220}
221
222// NumSubexp returns the number of parenthesized subexpressions in this Regexp.
223func (re *Regexp) NumSubexp() int {
224	return re.numSubexp
225}
226
227const endOfText = -1
228
229// input abstracts different representations of the input text. It provides
230// one-character lookahead.
231type input interface {
232	step(pos int) (rune int, width int) // advance one rune
233	canCheckPrefix() bool               // can we look ahead without losing info?
234	hasPrefix(re *Regexp) bool
235	index(re *Regexp, pos int) int
236	context(pos int) syntax.EmptyOp
237}
238
239// inputString scans a string.
240type inputString struct {
241	str string
242}
243
244func newInputString(str string) *inputString {
245	return &inputString{str: str}
246}
247
248func (i *inputString) step(pos int) (int, int) {
249	if pos < len(i.str) {
250		c := i.str[pos]
251		if c < utf8.RuneSelf {
252			return int(c), 1
253		}
254		return utf8.DecodeRuneInString(i.str[pos:])
255	}
256	return endOfText, 0
257}
258
259func (i *inputString) canCheckPrefix() bool {
260	return true
261}
262
263func (i *inputString) hasPrefix(re *Regexp) bool {
264	return strings.HasPrefix(i.str, re.prefix)
265}
266
267func (i *inputString) index(re *Regexp, pos int) int {
268	return strings.Index(i.str[pos:], re.prefix)
269}
270
271func (i *inputString) context(pos int) syntax.EmptyOp {
272	r1, r2 := -1, -1
273	if pos > 0 && pos <= len(i.str) {
274		r1, _ = utf8.DecodeLastRuneInString(i.str[:pos])
275	}
276	if pos < len(i.str) {
277		r2, _ = utf8.DecodeRuneInString(i.str[pos:])
278	}
279	return syntax.EmptyOpContext(r1, r2)
280}
281
282// inputBytes scans a byte slice.
283type inputBytes struct {
284	str []byte
285}
286
287func newInputBytes(str []byte) *inputBytes {
288	return &inputBytes{str: str}
289}
290
291func (i *inputBytes) step(pos int) (int, int) {
292	if pos < len(i.str) {
293		c := i.str[pos]
294		if c < utf8.RuneSelf {
295			return int(c), 1
296		}
297		return utf8.DecodeRune(i.str[pos:])
298	}
299	return endOfText, 0
300}
301
302func (i *inputBytes) canCheckPrefix() bool {
303	return true
304}
305
306func (i *inputBytes) hasPrefix(re *Regexp) bool {
307	return bytes.HasPrefix(i.str, re.prefixBytes)
308}
309
310func (i *inputBytes) index(re *Regexp, pos int) int {
311	return bytes.Index(i.str[pos:], re.prefixBytes)
312}
313
314func (i *inputBytes) context(pos int) syntax.EmptyOp {
315	r1, r2 := -1, -1
316	if pos > 0 && pos <= len(i.str) {
317		r1, _ = utf8.DecodeLastRune(i.str[:pos])
318	}
319	if pos < len(i.str) {
320		r2, _ = utf8.DecodeRune(i.str[pos:])
321	}
322	return syntax.EmptyOpContext(r1, r2)
323}
324
325// inputReader scans a RuneReader.
326type inputReader struct {
327	r     io.RuneReader
328	atEOT bool
329	pos   int
330}
331
332func newInputReader(r io.RuneReader) *inputReader {
333	return &inputReader{r: r}
334}
335
336func (i *inputReader) step(pos int) (int, int) {
337	if !i.atEOT && pos != i.pos {
338		return endOfText, 0
339
340	}
341	r, w, err := i.r.ReadRune()
342	if err != nil {
343		i.atEOT = true
344		return endOfText, 0
345	}
346	i.pos += w
347	return r, w
348}
349
350func (i *inputReader) canCheckPrefix() bool {
351	return false
352}
353
354func (i *inputReader) hasPrefix(re *Regexp) bool {
355	return false
356}
357
358func (i *inputReader) index(re *Regexp, pos int) int {
359	return -1
360}
361
362func (i *inputReader) context(pos int) syntax.EmptyOp {
363	return 0
364}
365
366// LiteralPrefix returns a literal string that must begin any match
367// of the regular expression re.  It returns the boolean true if the
368// literal string comprises the entire regular expression.
369func (re *Regexp) LiteralPrefix() (prefix string, complete bool) {
370	return re.prefix, re.prefixComplete
371}
372
373// MatchReader returns whether the Regexp matches the text read by the
374// RuneReader.  The return value is a boolean: true for match, false for no
375// match.
376func (re *Regexp) MatchReader(r io.RuneReader) bool {
377	return re.doExecute(newInputReader(r), 0, 0) != nil
378}
379
380// MatchString returns whether the Regexp matches the string s.
381// The return value is a boolean: true for match, false for no match.
382func (re *Regexp) MatchString(s string) bool {
383	return re.doExecute(newInputString(s), 0, 0) != nil
384}
385
386// Match returns whether the Regexp matches the byte slice b.
387// The return value is a boolean: true for match, false for no match.
388func (re *Regexp) Match(b []byte) bool {
389	return re.doExecute(newInputBytes(b), 0, 0) != nil
390}
391
392// MatchReader checks whether a textual regular expression matches the text
393// read by the RuneReader.  More complicated queries need to use Compile and
394// the full Regexp interface.
395func MatchReader(pattern string, r io.RuneReader) (matched bool, error os.Error) {
396	re, err := Compile(pattern)
397	if err != nil {
398		return false, err
399	}
400	return re.MatchReader(r), nil
401}
402
403// MatchString checks whether a textual regular expression
404// matches a string.  More complicated queries need
405// to use Compile and the full Regexp interface.
406func MatchString(pattern string, s string) (matched bool, error os.Error) {
407	re, err := Compile(pattern)
408	if err != nil {
409		return false, err
410	}
411	return re.MatchString(s), nil
412}
413
414// Match checks whether a textual regular expression
415// matches a byte slice.  More complicated queries need
416// to use Compile and the full Regexp interface.
417func Match(pattern string, b []byte) (matched bool, error os.Error) {
418	re, err := Compile(pattern)
419	if err != nil {
420		return false, err
421	}
422	return re.Match(b), nil
423}
424
425// ReplaceAllString returns a copy of src in which all matches for the Regexp
426// have been replaced by repl.  No support is provided for expressions
427// (e.g. \1 or $1) in the replacement string.
428func (re *Regexp) ReplaceAllString(src, repl string) string {
429	return re.ReplaceAllStringFunc(src, func(string) string { return repl })
430}
431
432// ReplaceAllStringFunc returns a copy of src in which all matches for the
433// Regexp have been replaced by the return value of of function repl (whose
434// first argument is the matched string).  No support is provided for
435// expressions (e.g. \1 or $1) in the replacement string.
436func (re *Regexp) ReplaceAllStringFunc(src string, repl func(string) string) string {
437	lastMatchEnd := 0 // end position of the most recent match
438	searchPos := 0    // position where we next look for a match
439	buf := new(bytes.Buffer)
440	for searchPos <= len(src) {
441		a := re.doExecute(newInputString(src), searchPos, 2)
442		if len(a) == 0 {
443			break // no more matches
444		}
445
446		// Copy the unmatched characters before this match.
447		io.WriteString(buf, src[lastMatchEnd:a[0]])
448
449		// Now insert a copy of the replacement string, but not for a
450		// match of the empty string immediately after another match.
451		// (Otherwise, we get double replacement for patterns that
452		// match both empty and nonempty strings.)
453		if a[1] > lastMatchEnd || a[0] == 0 {
454			io.WriteString(buf, repl(src[a[0]:a[1]]))
455		}
456		lastMatchEnd = a[1]
457
458		// Advance past this match; always advance at least one character.
459		_, width := utf8.DecodeRuneInString(src[searchPos:])
460		if searchPos+width > a[1] {
461			searchPos += width
462		} else if searchPos+1 > a[1] {
463			// This clause is only needed at the end of the input
464			// string.  In that case, DecodeRuneInString returns width=0.
465			searchPos++
466		} else {
467			searchPos = a[1]
468		}
469	}
470
471	// Copy the unmatched characters after the last match.
472	io.WriteString(buf, src[lastMatchEnd:])
473
474	return buf.String()
475}
476
477// ReplaceAll returns a copy of src in which all matches for the Regexp
478// have been replaced by repl.  No support is provided for expressions
479// (e.g. \1 or $1) in the replacement text.
480func (re *Regexp) ReplaceAll(src, repl []byte) []byte {
481	return re.ReplaceAllFunc(src, func([]byte) []byte { return repl })
482}
483
484// ReplaceAllFunc returns a copy of src in which all matches for the
485// Regexp have been replaced by the return value of of function repl (whose
486// first argument is the matched []byte).  No support is provided for
487// expressions (e.g. \1 or $1) in the replacement string.
488func (re *Regexp) ReplaceAllFunc(src []byte, repl func([]byte) []byte) []byte {
489	lastMatchEnd := 0 // end position of the most recent match
490	searchPos := 0    // position where we next look for a match
491	buf := new(bytes.Buffer)
492	for searchPos <= len(src) {
493		a := re.doExecute(newInputBytes(src), searchPos, 2)
494		if len(a) == 0 {
495			break // no more matches
496		}
497
498		// Copy the unmatched characters before this match.
499		buf.Write(src[lastMatchEnd:a[0]])
500
501		// Now insert a copy of the replacement string, but not for a
502		// match of the empty string immediately after another match.
503		// (Otherwise, we get double replacement for patterns that
504		// match both empty and nonempty strings.)
505		if a[1] > lastMatchEnd || a[0] == 0 {
506			buf.Write(repl(src[a[0]:a[1]]))
507		}
508		lastMatchEnd = a[1]
509
510		// Advance past this match; always advance at least one character.
511		_, width := utf8.DecodeRune(src[searchPos:])
512		if searchPos+width > a[1] {
513			searchPos += width
514		} else if searchPos+1 > a[1] {
515			// This clause is only needed at the end of the input
516			// string.  In that case, DecodeRuneInString returns width=0.
517			searchPos++
518		} else {
519			searchPos = a[1]
520		}
521	}
522
523	// Copy the unmatched characters after the last match.
524	buf.Write(src[lastMatchEnd:])
525
526	return buf.Bytes()
527}
528
529var specialBytes = []byte(`\.+*?()|[]{}^$`)
530
531func special(b byte) bool {
532	return bytes.IndexByte(specialBytes, b) >= 0
533}
534
535// QuoteMeta returns a string that quotes all regular expression metacharacters
536// inside the argument text; the returned string is a regular expression matching
537// the literal text.  For example, QuoteMeta(`[foo]`) returns `\[foo\]`.
538func QuoteMeta(s string) string {
539	b := make([]byte, 2*len(s))
540
541	// A byte loop is correct because all metacharacters are ASCII.
542	j := 0
543	for i := 0; i < len(s); i++ {
544		if special(s[i]) {
545			b[j] = '\\'
546			j++
547		}
548		b[j] = s[i]
549		j++
550	}
551	return string(b[0:j])
552}
553
554// The number of capture values in the program may correspond
555// to fewer capturing expressions than are in the regexp.
556// For example, "(a){0}" turns into an empty program, so the
557// maximum capture in the program is 0 but we need to return
558// an expression for \1.  Pad appends -1s to the slice a as needed.
559func (re *Regexp) pad(a []int) []int {
560	if a == nil {
561		// No match.
562		return nil
563	}
564	n := (1 + re.numSubexp) * 2
565	for len(a) < n {
566		a = append(a, -1)
567	}
568	return a
569}
570
571// Find matches in slice b if b is non-nil, otherwise find matches in string s.
572func (re *Regexp) allMatches(s string, b []byte, n int, deliver func([]int)) {
573	var end int
574	if b == nil {
575		end = len(s)
576	} else {
577		end = len(b)
578	}
579
580	for pos, i, prevMatchEnd := 0, 0, -1; i < n && pos <= end; {
581		var in input
582		if b == nil {
583			in = newInputString(s)
584		} else {
585			in = newInputBytes(b)
586		}
587		matches := re.doExecute(in, pos, re.prog.NumCap)
588		if len(matches) == 0 {
589			break
590		}
591
592		accept := true
593		if matches[1] == pos {
594			// We've found an empty match.
595			if matches[0] == prevMatchEnd {
596				// We don't allow an empty match right
597				// after a previous match, so ignore it.
598				accept = false
599			}
600			var width int
601			// TODO: use step()
602			if b == nil {
603				_, width = utf8.DecodeRuneInString(s[pos:end])
604			} else {
605				_, width = utf8.DecodeRune(b[pos:end])
606			}
607			if width > 0 {
608				pos += width
609			} else {
610				pos = end + 1
611			}
612		} else {
613			pos = matches[1]
614		}
615		prevMatchEnd = matches[1]
616
617		if accept {
618			deliver(re.pad(matches))
619			i++
620		}
621	}
622}
623
624// Find returns a slice holding the text of the leftmost match in b of the regular expression.
625// A return value of nil indicates no match.
626func (re *Regexp) Find(b []byte) []byte {
627	a := re.doExecute(newInputBytes(b), 0, 2)
628	if a == nil {
629		return nil
630	}
631	return b[a[0]:a[1]]
632}
633
634// FindIndex returns a two-element slice of integers defining the location of
635// the leftmost match in b of the regular expression.  The match itself is at
636// b[loc[0]:loc[1]].
637// A return value of nil indicates no match.
638func (re *Regexp) FindIndex(b []byte) (loc []int) {
639	a := re.doExecute(newInputBytes(b), 0, 2)
640	if a == nil {
641		return nil
642	}
643	return a[0:2]
644}
645
646// FindString returns a string holding the text of the leftmost match in s of the regular
647// expression.  If there is no match, the return value is an empty string,
648// but it will also be empty if the regular expression successfully matches
649// an empty string.  Use FindStringIndex or FindStringSubmatch if it is
650// necessary to distinguish these cases.
651func (re *Regexp) FindString(s string) string {
652	a := re.doExecute(newInputString(s), 0, 2)
653	if a == nil {
654		return ""
655	}
656	return s[a[0]:a[1]]
657}
658
659// FindStringIndex returns a two-element slice of integers defining the
660// location of the leftmost match in s of the regular expression.  The match
661// itself is at s[loc[0]:loc[1]].
662// A return value of nil indicates no match.
663func (re *Regexp) FindStringIndex(s string) []int {
664	a := re.doExecute(newInputString(s), 0, 2)
665	if a == nil {
666		return nil
667	}
668	return a[0:2]
669}
670
671// FindReaderIndex returns a two-element slice of integers defining the
672// location of the leftmost match of the regular expression in text read from
673// the RuneReader.  The match itself is at s[loc[0]:loc[1]].  A return
674// value of nil indicates no match.
675func (re *Regexp) FindReaderIndex(r io.RuneReader) []int {
676	a := re.doExecute(newInputReader(r), 0, 2)
677	if a == nil {
678		return nil
679	}
680	return a[0:2]
681}
682
683// FindSubmatch returns a slice of slices holding the text of the leftmost
684// match of the regular expression in b and the matches, if any, of its
685// subexpressions, as defined by the 'Submatch' descriptions in the package
686// comment.
687// A return value of nil indicates no match.
688func (re *Regexp) FindSubmatch(b []byte) [][]byte {
689	a := re.doExecute(newInputBytes(b), 0, re.prog.NumCap)
690	if a == nil {
691		return nil
692	}
693	ret := make([][]byte, 1+re.numSubexp)
694	for i := range ret {
695		if 2*i < len(a) && a[2*i] >= 0 {
696			ret[i] = b[a[2*i]:a[2*i+1]]
697		}
698	}
699	return ret
700}
701
702// FindSubmatchIndex returns a slice holding the index pairs identifying the
703// leftmost match of the regular expression in b and the matches, if any, of
704// its subexpressions, as defined by the 'Submatch' and 'Index' descriptions
705// in the package comment.
706// A return value of nil indicates no match.
707func (re *Regexp) FindSubmatchIndex(b []byte) []int {
708	return re.pad(re.doExecute(newInputBytes(b), 0, re.prog.NumCap))
709}
710
711// FindStringSubmatch returns a slice of strings holding the text of the
712// leftmost match of the regular expression in s and the matches, if any, of
713// its subexpressions, as defined by the 'Submatch' description in the
714// package comment.
715// A return value of nil indicates no match.
716func (re *Regexp) FindStringSubmatch(s string) []string {
717	a := re.doExecute(newInputString(s), 0, re.prog.NumCap)
718	if a == nil {
719		return nil
720	}
721	ret := make([]string, 1+re.numSubexp)
722	for i := range ret {
723		if 2*i < len(a) && a[2*i] >= 0 {
724			ret[i] = s[a[2*i]:a[2*i+1]]
725		}
726	}
727	return ret
728}
729
730// FindStringSubmatchIndex returns a slice holding the index pairs
731// identifying the leftmost match of the regular expression in s and the
732// matches, if any, of its subexpressions, as defined by the 'Submatch' and
733// 'Index' descriptions in the package comment.
734// A return value of nil indicates no match.
735func (re *Regexp) FindStringSubmatchIndex(s string) []int {
736	return re.pad(re.doExecute(newInputString(s), 0, re.prog.NumCap))
737}
738
739// FindReaderSubmatchIndex returns a slice holding the index pairs
740// identifying the leftmost match of the regular expression of text read by
741// the RuneReader, and the matches, if any, of its subexpressions, as defined
742// by the 'Submatch' and 'Index' descriptions in the package comment.  A
743// return value of nil indicates no match.
744func (re *Regexp) FindReaderSubmatchIndex(r io.RuneReader) []int {
745	return re.pad(re.doExecute(newInputReader(r), 0, re.prog.NumCap))
746}
747
748const startSize = 10 // The size at which to start a slice in the 'All' routines.
749
750// FindAll is the 'All' version of Find; it returns a slice of all successive
751// matches of the expression, as defined by the 'All' description in the
752// package comment.
753// A return value of nil indicates no match.
754func (re *Regexp) FindAll(b []byte, n int) [][]byte {
755	if n < 0 {
756		n = len(b) + 1
757	}
758	result := make([][]byte, 0, startSize)
759	re.allMatches("", b, n, func(match []int) {
760		result = append(result, b[match[0]:match[1]])
761	})
762	if len(result) == 0 {
763		return nil
764	}
765	return result
766}
767
768// FindAllIndex is the 'All' version of FindIndex; it returns a slice of all
769// successive matches of the expression, as defined by the 'All' description
770// in the package comment.
771// A return value of nil indicates no match.
772func (re *Regexp) FindAllIndex(b []byte, n int) [][]int {
773	if n < 0 {
774		n = len(b) + 1
775	}
776	result := make([][]int, 0, startSize)
777	re.allMatches("", b, n, func(match []int) {
778		result = append(result, match[0:2])
779	})
780	if len(result) == 0 {
781		return nil
782	}
783	return result
784}
785
786// FindAllString is the 'All' version of FindString; it returns a slice of all
787// successive matches of the expression, as defined by the 'All' description
788// in the package comment.
789// A return value of nil indicates no match.
790func (re *Regexp) FindAllString(s string, n int) []string {
791	if n < 0 {
792		n = len(s) + 1
793	}
794	result := make([]string, 0, startSize)
795	re.allMatches(s, nil, n, func(match []int) {
796		result = append(result, s[match[0]:match[1]])
797	})
798	if len(result) == 0 {
799		return nil
800	}
801	return result
802}
803
804// FindAllStringIndex is the 'All' version of FindStringIndex; it returns a
805// slice of all successive matches of the expression, as defined by the 'All'
806// description in the package comment.
807// A return value of nil indicates no match.
808func (re *Regexp) FindAllStringIndex(s string, n int) [][]int {
809	if n < 0 {
810		n = len(s) + 1
811	}
812	result := make([][]int, 0, startSize)
813	re.allMatches(s, nil, n, func(match []int) {
814		result = append(result, match[0:2])
815	})
816	if len(result) == 0 {
817		return nil
818	}
819	return result
820}
821
822// FindAllSubmatch is the 'All' version of FindSubmatch; it returns a slice
823// of all successive matches of the expression, as defined by the 'All'
824// description in the package comment.
825// A return value of nil indicates no match.
826func (re *Regexp) FindAllSubmatch(b []byte, n int) [][][]byte {
827	if n < 0 {
828		n = len(b) + 1
829	}
830	result := make([][][]byte, 0, startSize)
831	re.allMatches("", b, n, func(match []int) {
832		slice := make([][]byte, len(match)/2)
833		for j := range slice {
834			if match[2*j] >= 0 {
835				slice[j] = b[match[2*j]:match[2*j+1]]
836			}
837		}
838		result = append(result, slice)
839	})
840	if len(result) == 0 {
841		return nil
842	}
843	return result
844}
845
846// FindAllSubmatchIndex is the 'All' version of FindSubmatchIndex; it returns
847// a slice of all successive matches of the expression, as defined by the
848// 'All' description in the package comment.
849// A return value of nil indicates no match.
850func (re *Regexp) FindAllSubmatchIndex(b []byte, n int) [][]int {
851	if n < 0 {
852		n = len(b) + 1
853	}
854	result := make([][]int, 0, startSize)
855	re.allMatches("", b, n, func(match []int) {
856		result = append(result, match)
857	})
858	if len(result) == 0 {
859		return nil
860	}
861	return result
862}
863
864// FindAllStringSubmatch is the 'All' version of FindStringSubmatch; it
865// returns a slice of all successive matches of the expression, as defined by
866// the 'All' description in the package comment.
867// A return value of nil indicates no match.
868func (re *Regexp) FindAllStringSubmatch(s string, n int) [][]string {
869	if n < 0 {
870		n = len(s) + 1
871	}
872	result := make([][]string, 0, startSize)
873	re.allMatches(s, nil, n, func(match []int) {
874		slice := make([]string, len(match)/2)
875		for j := range slice {
876			if match[2*j] >= 0 {
877				slice[j] = s[match[2*j]:match[2*j+1]]
878			}
879		}
880		result = append(result, slice)
881	})
882	if len(result) == 0 {
883		return nil
884	}
885	return result
886}
887
888// FindAllStringSubmatchIndex is the 'All' version of
889// FindStringSubmatchIndex; it returns a slice of all successive matches of
890// the expression, as defined by the 'All' description in the package
891// comment.
892// A return value of nil indicates no match.
893func (re *Regexp) FindAllStringSubmatchIndex(s string, n int) [][]int {
894	if n < 0 {
895		n = len(s) + 1
896	}
897	result := make([][]int, 0, startSize)
898	re.allMatches(s, nil, n, func(match []int) {
899		result = append(result, match)
900	})
901	if len(result) == 0 {
902		return nil
903	}
904	return result
905}