Regex::Matches Method (String^, Int32)
Searches the specified input string for all occurrences of a regular expression, beginning at the specified starting position in the string.
Assembly: System (in System.dll)
Parameters
- input
-
Type:
System::String^
The string to search for a match.
- startat
-
Type:
System::Int32
The character position in the input string at which to start the search.
Return Value
Type: System.Text.RegularExpressions::MatchCollection^A collection of the Match objects found by the search. If no matches are found, the method returns an empty collection object.
| Exception | Condition |
|---|---|
| ArgumentNullException | input is null. |
| ArgumentOutOfRangeException | startat is less than zero or greater than the length of input. |
The Matches(String^, Int32) method is similar to the Match(String^, Int32) method, except that it returns information about all the matches found in the input string, instead of a single match. It is equivalent to the following code:
The regular expression pattern for which the Matches(String^, Int32) method searches is defined by the call to one of the Regex class constructors. For more information about the elements that can form a regular expression pattern, see Regular Expression Language - Quick Reference.
The Matches method uses lazy evaluation to populate the returned MatchCollection object. Accessing members of this collection such as MatchCollection::Count and MatchCollection::CopyTo causes the collection to be populated immediately. To take advantage of lazy evaluation, you should iterate the collection by using a construct such as foreach in C# and ForEach…Next in Visual Basic.
Because of its lazy evaluation, calling the Matches(String^, Int32) method does not throw a RegexMatchTimeoutException exception. However, the exception is thrown when an operation is performed on the MatchCollection object returned by this method, if the MatchTimeout property is not Regex::InfiniteMatchTimeout and a matching operation exceeds the time-out interval..
The following example uses the Match(String^) method to find the first word in a sentence that ends in "es", and then calls the Matches(String^, Int32) method to identify any additional words that end in "es".
The regular expression pattern \b\w+es\b is defined as shown in the following table.
Pattern | Description |
|---|---|
\b | Begin the match at a word boundary. |
\w+ | Match one or more word characters. |
es | Match the literal string "es". |
\b | End the match at a word boundary. |
Available since 8
.NET Framework
Available since 1.1
Portable Class Library
Supported in: portable .NET platforms
Silverlight
Available since 2.0
Windows Phone Silverlight
Available since 7.0
Windows Phone
Available since 8.1