Chapter 21

The Classes of System.Text.RegularExpressions

The following table lists the classes that are contained in the System.Text.RegularExpressions namespace. The properties and methods of several of the classes listed are described in detail later in this chapter, together with examples demonstrating how to use some of the properties and methods.

Class	Description
Capture	Represents the text captured by a single set of parentheses surround-
	ing a subexpression
CaptureCollection	Represents a collection of Capture objects
Group	Represents the result of a single capturing group of paired parentheses
GroupCollection	Represents a collection of Group objects
Match	Represents the result of a single regular expression match
MatchCollection	Represents a collection of Match objects
Regex	The class that contains the regular expression pattern
RegexCompilationInfo	Provides information that the compiler uses to compile a regular
	expression into an assembly

You may find it useful to think of the Regex object as containing all the information relating to a regular expression. The MatchesCollection object contains all the matches for a matching process, with information about each match being contained in a Match object. A GroupsCollection object contains information about all the groups in a match, with each group being represented by a Group object. The CapturesCollection object contains information about all captures for a group, with information about each capture being held in a Capture object.

The following sections take a closer look at several of these members of the System.Text

.RegularExpressions namespace.

In the following sections, classes will be referred to simply by their class name (for example, Regex) rather than using the fully qualified name, such as System.Text.RegularExpressions.Regex.

The Regex Object

The Regex object can be instantiated to make its properties and methods accessible to programmatic manipulation. In addition, three of the methods of the Regex class are available as shared methods. The use of these shared methods is described and demonstrated later.

490

Visual Basic .NET and Regular Expressions

The Regex object has two public properties, described briefly in the following table.

Property	Description
Options	Contains information about the options passed to the Regex object.
RightToLeft	Returns a Boolean value indicating whether or not right-to-left
	processing of matching is operative. A value of True indicates
	right-to-left matching.

If you are used to creating regular expression objects in JScript or VBScript where the regular expression object is the RegExp object, be careful to spell the .NET Regex object correctly in your code.

The following table summarizes the Regex object’s methods. Some of the concepts and techniques of the Regex object are not found in standard regular expressions. Therefore, some of the concepts summarized in the table may usefully be clarified for you when you read following sections that further describe the methods and/or demonstrate how they are used.

Method	Description
CompileToAssembly	Compiles a regular expression to an assembly (the default behavior
	of a regular expression is not to compile to an assembly)
Equals	Determines whether two objects are equal
Escape	Escapes a set of metacharacters, replacing the metacharacter with the
	corresponding escaped character
GetGroupNames	Returns an array of capturing group names
GetGroupNumbers	Returns an array of capturing group numbers
GetHashCode	Inherited from the Object class
GetType	Gets the type of the current instance
GroupNameFromNumber	Gets a group name that corresponds to the group number supplied
	as an argument
GroupNumberFromName	Gets a group number that corresponds to the group name supplied
	as an argument
IsMatch	Returns a Boolean value indicating whether the regular expression
	pattern is matched in the string that is the argument to the
	IsMatch() method
Match	Returns zero or one Match object, depending on whether or not the
	string supplied to the method as its argument contains a match
Matches	Returns a MatchCollection object containing zero or more Match
	objects, which contain all matches (or none) in the string that is the
	argument to the Matches() method
	Table continued on following page

491

Chapter 21

Method	Description
Replace	Replaces all occurrences of a regular expression pattern with a speci-
	fied character sequence
Split	Splits an input string into an array of strings; the split occurs at a
	position indicated by a regular expression pattern
ToString	Returns a string that contains the regular expression passed into the
	Regex object in its constructor
Unescape	Unescapes any escaped characters in the input string

Using the Match Object and Matches Collection

The Match() method returns a Match object if there is a successful match. If there are potentially multiple matches, the Match() method only matches once and stops.

Try It Out

The Match() Method

The sample code is contained in Module1.vb in the MatchMethodDemo project:

Imports System.Text.RegularExpressions Module Module1

Dim myRegex = New Regex(“[A-Z]\d”) Sub Main()

Console.WriteLine(“Enter a string on the following line:”) Dim inputString = Console.ReadLine()

Dim myMatch = myRegex.Match(InputString)

Console.WriteLine(“The match, ‘“ & myMatch.Value & “‘ was found.”) Console.WriteLine(“Press Return to close this application.”) Console.ReadLine()

End Sub

End Module

1.Create a new project in Visual Studio 2003. If you are unused to creating projects, refer to the detailed description in the first example in this chapter.

2.Name the project MatchMethodDemo.

3.Edit Module1.vb so that the content is as shown in the preceding code.

4.Save the project, and press F5 to run it. If you entered the code correctly, you should see a command window displaying the following text:

Enter a string on the following line:

5.Enter the text Hello K9 and K10, and press Return. Inspect the results.

There are two potential matches for the pattern [A-Z]\d in the string you entered: K9 and K10. Notice in Figure 21-5 that only one match is displayed, K9, which is the first match in the string.

492

Visual Basic .NET and Regular Expressions

Figure 21-5

How It Works

The variable myRegex is dimensioned and assigned the pattern [A-Z]\d, which matches an uppercase alphabetic character followed by a numeric digit:

Dim myRegex = New Regex(“[A-Z]\d”)

After the test string has been read from the command line, the myRegex variable’s Match() method is applied to InputString, and the result is assigned to the myMatch variable:

Dim myMatch = myRegex.Match(InputString)

The value of InputString is the string Hello K9 and K10.. There are two matches for the pattern [A-Z]\d: the character sequences K9 and K1.

The value of the myMatch object’s Value property is concatenated to some explanatory text and is written to the display:

Console.WriteLine(“The match, ‘“ & myMatch.Value & “‘ was found.”)

The first match, K9, is displayed. The second potential match K1 is not matched and is not displayed. To match and display all matches in a test string, you need to use the Matches() method of the Regex object.

The Matches() method, however, returns a MatchCollection object, which can contain Match objects for all the matches in the test string. The following example looks at how the Matches() method can be used.

Try It Out

The Matches() Method

The sample code is contained in Module1.vb in the MatchesMethodDemo project:

Imports System.Text.RegularExpressions

Module Module1

Sub Main()

Dim myRegex = New Regex(“[A-Z]\d”) Console.WriteLine(“Enter a string on the following line:”) Dim inputString = Console.ReadLine()

Dim myMatchCollection = myRegex.Matches(inputString) Console.WriteLine()

Console.WriteLine(“There are {0} matches.”, myMatchCollection.Count) Console.WriteLine()

493

Chapter 21

Dim myMatch As Match

For Each myMatch In myMatchCollection

Console.WriteLine(“At position {0}, the match ‘{1}’ was found”, myMatch.Index, myMatch.ToString)

Next Console.WriteLine()

Console.WriteLine(“Press Return to close this application.”) Console.ReadLine()

End Sub

End Module

1.Create a new Visual Basic .NET console project in Visual Studio 2003. Name the project

MatchesMethodDemo.

2.Edit the code in Module1.vb so that it appears as in the preceding code.

3.Press Ctrl+S to save the code. Press F5 to run it.

4.In the command window, type Hello K9, K10 and K21., and press Return.

5.Inspect the displayed results, as shown in Figure 21-6. Notice that there are now three matches:

K9, K1, and K2.

Figure 21-6

How It Works

The myRegex variable is dimensioned, and a new Regex object is instantiated and is assigned the pattern

[A-Z]\d:

Dim myRegex = New Regex(“[A-Z]\d”)

After the user is invited to enter a string, a myMatchCollection variable is dimensioned and assigned the match collection produced by the Matches() method with the inputString variable as its argument.

Dim myMatchCollection = myRegex.Matches(inputString)

A count of the Match objects in the match collection represented by the myMatchCollection object is displayed, using the MatchCollection object’s Count property:

Console.WriteLine(“There are {0} matches.”, myMatchCollection.Count)

494