|
|
Matches
Our sections on the Regular Expressions namespace and Regex object briefly
introduced the concept of matches. The Regex.IsMatch() method looks for one or
more occurances of a pattern match. If it finds at least one, the function
returns true.
Using the Regex methods Match() and Matches(), we can obtain a Match and
MatchCollection objects that give us more information. Each Match object
contains details about a single match, such as it's position within the string.
The MatchCollection is simply a collection of Match objects.
Single Match and the Match object
The Regex.Match method has several overloads: instance and static methods.
Match Match(string input);
Match Match(string input, int startat);
static Match Match(string input, string pattern);
static Match Match(string input, string pattern, RegexOptions options);
Function Match(input as String) as Match
Function Match(input as String, startat as Integer) as Match
Shared Function Match(input as String, pattern as String) as Match
Shared Function Match(input as String, pattern as String, options as RegexOptions) as Match
|
|
Note that the Match method returns the first match found, even if there are
multiple matches in the string. If you want to handle multiple matches, you
should use the Matches collection and enumerate.
The following table summarizes the properties and methods of the Match class that you are
likely to use in your application when processing a match:
| Success |
Indicates whether a match was found. You should test this value before
processing the match. |
| Index |
Indicates the position in the string where the match starts. |
| Length |
Indicates the length of the substring that matches the pattern. |
| Value |
Equals the substring that did match the pattern. |
| Groups |
Returns a collection of Group objects. See section on Groups |
The following example looks for an instance of a phone number, in the format
###-###-####, and returns a Match object. Using the Match.Success property, we
can determine whether a match was found and then proceed to output the text of
the match, it's location within the string, and it's length using the
properties in the table above.
static void Main(string[] args)
{
Match m1 = Regex.Match("Our phone number is 508-888-8888.", @"\d\d\d-\d\d\d-\d\d\d\d");
if (m1.Success)
Console.WriteLine("The value '{0}' was found at index {1}, and is {2} characters long.", m1.Value, m1.Index, m1.Length);
}
Sub Main()
Dim m1 as Match = Regex.Match("Our phone number is 508-888-8888.", "\d\d\d-\d\d\d-\d\d\d\d")
if (m1.Success) then
Console.WriteLine("The value '{0}' was found at index {1}, and is {2} characters long.", m1.Value, m1.Index, m1.Length)
end if
End Sub
|
|
Here are the results:
Multiple Matches and the MatchCollection
When you anticipate, and want to process, multiple matches in a string, you'll
want to use the Regex.Matches method. These methods are very similar to the
signatures of the Match method, except they return a MatchCollection object
instead of a Match.
MatchCollection Matches(string input);
MatchCollection Matches(string input, int startat);
static MatchCollection Matches(string input, string pattern);
static MatchCollection Matches(string input, string pattern, RegexOptions options);
Function Matches(input as String) as MatchCollection
Function Matches(input as String, startat as Integer) as MatchCollection
Shared Function Matches(input as String, pattern as String) as MatchCollection
Shared Function Matches(input as String, pattern as String, options as RegexOptions) as MatchCollection
|
|
The MatchCollection is a strongly-typed collection of Match objects, and
implements ICollection and IEnumerable. You can use the Count property to get
the number of matches, and the foreach syntax can be used to iterate through
the collection.
Let's modify our earlier example to extract all the phone number matches in a
string.
MatchCollection mc1 = Regex.Matches("We have two phone numbers. One is 508-888-8888. The other is 508-888-8887.", @"\d\d\d-\d\d\d-\d\d\d\d");
if (mc1.Count > 0)
{
foreach(Match m1 in mc1)
Console.WriteLine("The value '{0}' was found at index {1}, and is {2} characters long.", m1.Value, m1.Index, m1.Length);
}
Dim mc1 as MatchCollection = Regex.Matches("We have two phone numbers. One is 508-888-8888. The other is 508-888-8887.", "\d\d\d-\d\d\d-\d\d\d\d")
if (mc1.Count > 0) then
for each m1 as Match in mc1
Console.WriteLine("The value '{0}' was found at index {1}, and is {2} characters long.", m1.Value, m1.Index, m1.Length)
next
end if
|
|
Now our program can successfully handle multiple matches.
|
|
