Working With Matches

The IsMatch method returns a true or false Boolean value, but doesn't tell you anything about the match that it found. When you need more information than a simple yes-or-no answer, you use the Match method. This method returns a Match object which provides you with a variety of information about the comparison. There are several overloads of this method, but the one you'll use most often is

re.Match(InputString)

The returned Match object has a Success property that is True if a match was found.

Dim re As New Regex("abc")
Dim m As Match = re.Match("xyzabc123")
If m.Success Then
    ' Work with match here.
Else
    MsgBox "No match was found"
End If

The Match object exposes these properties containing information about the match:

Index: The character position in InputString at which the captured substring (the match) was found.

Length: The length of the captured substring.

Value: The captured substring itself.

Here's an example. Suppose your regular expression is [0-9]{4,}, which will match any sequence of 4 or more digits. (Remember, [0-9] will match any digit, and the {4,} means "four or more.") If your input string is "The ZIP code is 27514" then the returned Match object will have Index equal to 16, Length equal to 5, and Value equal to "27514".

This technique lets you find a single match in an input string. If you want to find all matches within a string, one technique is to use the Match.NextMatch method. You call this method after one match has been made. It continues the search, starting immediately following the location of the previous match. Thus, you could loop through all matches using this technique:

Dim m As Match = re.Match(InputString)
While m.Success
    ' Process each match here.
    ' Move to the next match.
    m.NextMatch()
End While

Another way to find all matches is use the Matches method. The syntax is exactly like that for the Match method except that it returns a MatchCollection object which, as you might guess, contains a Match object for every match that was found. The properties of interest are:

Count: The number of captures (matches).

Item: Indexed access to individual match objects. Ranges from 0 to Count - 1.

Access all matches would then take this form:

Dim m As Match
Dim re As New RegEx(Pattern)
Dim mc As MatchCollection = re.Matches(InputString)
If mc.Count > 0 Then
   Dim i As Integer, m As Match
   For i = 0 To mc.Count - 1
        m = mc.Item(i)
        ' Access each match's information via m.
   Next
End If

Manipulating Strings Using Regular Expression Tools

So far we have seen how to use the .NET Framework's regular expression tools to match and extract text from within input strings. You also have tools available to replace and split strings based on regular expression matches. For replacing text, you use the Regex.Replace method. It has several overloads and the one that is used most often is as follows:

re.Replace(InputString, ReplacementText)

The return value is a string in which any text in InputString that matches the regular expression that was specified when the Regex instance was created have been replaced with the specified text. For example:

Dim re As New Regex("\d+")
NewString = re.Replace(InputString, "XXXX")  

The returned string has every sequence of one or more digits replaced with XXXX. (Remember, Replace doesn't modify the original input string; instead, it returns a new string containing the modifications.)

You can split strings using regular expressions with the Regex.Split method. The method divides the input string into substrings at the location of each match and returns the substring in an array of type String. If no match is found, the returned array will have a single element containing the entire original input string. The syntax is:

re.Split(InputString)

Here's an example:

Dim v() As String
Dim re As New Regex("\W+")
v = re.Split("Happy birthday;;;to#me")

The result is that v(0) = "Happy", v(1)="birthday", v(2)="to", and v(3)="me".

Summing Up

Regular expressions are a powerful and sophisticated mini-language for defining text patterns. With the .NET Framework's classes for using regular expressions, you can perform a wide variety of tasks from validating user input to performing complex text manipulation. Once you start using them, you'll wonder how you ever did without them.