# Execute
{: .no_toc }

Searches a string for the pattern and returns the matches.

Syntax: *object*.**Execute** ( *sourceString* ) **As MatchCollection**

*object*
: *required* An object expression that evaluates to a **RegExp**.

*sourceString*
: *required* A **String**, the text to search.

Returns a [**MatchCollection**](/tB/Packages/Contributed/tbRegExp/MatchCollection/index.md) that holds one [**Match**](/tB/Packages/Contributed/tbRegExp/Match/index.md) for each match of [**Pattern**](/tB/Packages/Contributed/tbRegExp/RegExp/Pattern.md) in *sourceString*, in the order they occur. The collection is empty when there is no match.

## Remarks

With [**Global**](/tB/Packages/Contributed/tbRegExp/RegExp/Global.md) set to **False**, the collection holds at most one match, the first. With **Global** set to **True** it holds every match.

[**IgnoreCase**](/tB/Packages/Contributed/tbRegExp/RegExp/IgnoreCase.md), [**MultiLine**](/tB/Packages/Contributed/tbRegExp/RegExp/MultiLine.md) and [**DotAll**](/tB/Packages/Contributed/tbRegExp/RegExp/DotAll.md) change what counts as a match.

A match can have no characters, as `(?=[A-Z])` has before each capital letter, and each such match is returned once. `fooBarBaz` has two capitals, so the collection holds two matches, at positions 3 and 6.

```tb check_build check_run
Dim re As New RegExp
re.Global = True
re.Pattern = "(?=[A-Z])"
Debug.Print re.Execute("fooBarBaz").Count         ' 2
Debug.Print re.Execute("fooBarBaz")(1).FirstIndex  ' 6
```

A search that backtracks without end, such as `(a+)+b` on thirty `a`, gives up instead of hanging, and **Execute** then raises an error. The matches found before it gave up are not returned: a part of the matches, handed back as though it were all of them, is worse than no answer. See [**SearchStepLimit**](/tB/Packages/Contributed/tbRegExp/RegExp/SearchStepLimit.md).

Each **Match** gives the matched text ([**Value**](/tB/Packages/Contributed/tbRegExp/Match/Value.md)), the position where it starts ([**FirstIndex**](/tB/Packages/Contributed/tbRegExp/Match/FirstIndex.md), counted from 0), its length, and the text of each group of the pattern ([**SubMatches**](/tB/Packages/Contributed/tbRegExp/Match/SubMatches.md)). A group written `(?<name>...)` can be read by its name.

An invalid pattern raises the compile error, with the number in [**LastErrorNumber**](/tB/Packages/Contributed/tbRegExp/RegExp/LastErrorNumber.md) and the description in [**LastError**](/tB/Packages/Contributed/tbRegExp/RegExp/LastError.md). Check [**IsValid**](/tB/Packages/Contributed/tbRegExp/RegExp/IsValid.md) first to avoid it.

## Example

```tb check_build check_run
Dim re As RegExp
Set re = New RegExp
re.Pattern = "(?<year>\d{4})-(?<month>\d{2})"
re.Global = True

Dim matches As MatchCollection
Set matches = re.Execute("2026-10 and 2027-01")
Debug.Print matches.Count

Dim m As Match
For Each m In matches
    Debug.Print m.Value & " at " & m.FirstIndex & ": " & m.SubMatches.Item("year") & "/" & m.SubMatches.Item("month")
Next

re.Global = False
Debug.Print re.Execute("2026-10 and 2027-01").Count
Debug.Print re.Execute("no date").Count
' Output:
' 2
' 2026-10 at 0: 2026/10
' 2027-01 at 12: 2027/01
' 1
' 0
```

## See Also

- [Test](/tB/Packages/Contributed/tbRegExp/RegExp/Test.md) method -- returns whether a string contains a match
- [Replace](/tB/Packages/Contributed/tbRegExp/RegExp/Replace.md) method -- replaces the matches
- [Split](/tB/Packages/Contributed/tbRegExp/RegExp/Split.md) method -- splits a string at the matches
- [Global](/tB/Packages/Contributed/tbRegExp/RegExp/Global.md) property -- all matches or the first
- [MatchCollection](/tB/Packages/Contributed/tbRegExp/MatchCollection/index.md) class -- the result
- [RegExp](/tB/Packages/Contributed/tbRegExp/RegExp/index.md) class -- overview
