The Matches(String^, String^, RegexOptions) method is similar to the Match(String^, String^, RegexOptions) 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 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^, String^) 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 a time-out interval is defined by the "REGEX_DEFAULT_MATCH_TIMEOUT" property of the current application domain and a matching operation exceeds this time-out interval.

Notes to Callers:

This method times out after an interval that is equal to the default time-out value of the application domain in which it is called. If a time-out value has not been defined for the application domain, the value Regex::InfiniteMatchTimeout, which prevents the method from timing out, is used. The recommended static method for retrieving multiple pattern matches is Regex::Matches(String^, String^, RegexOptions, TimeSpan), which lets you set the time-out interval.

The following example calls the Matches(String^, String^) method to identify any word in a sentence that ends in "es", and then calls the Matches(String^, String^, RegexOptions) method to perform a case-insensitive comparison of the pattern with the input string. As the output shows, the two methods return different results.