9.5 Support Functions

Besides the convenience functions described in the previous section, there are a few other static support functions:

Match.Empty
This function returns a Match object that represents a failed match. It is perhaps useful for initializing a Match object that you may or may not fill in later, but do intend to query later. Here's a simple example:

Dim SubMatch as Match = Match.Empty 'Initialize, in case it's not set in the loop below

   .

   .

   .

Dim Line as String

For Each Line in EmailHeaderLines

    'If this is the subject, save the match info for later . . .          

    Dim ThisMatch as Match = Regex.Match(Line, "^Subject:\s*(.*)", _
                                               RegexOptions.IgnoreCase)

    If ThisMatch.Success

       SubMatch = ThisMatch

    End If

      .

      .

      .

Next

  .

  .

  .

If SubMatch.Success

   Console.WriteLine(SubMatch.Result("The subject is: $1"))

Else

   Console.WriteLine("No subject!")

End If

If the string array EmailHeaderLines actually has no lines (or no Subject lines), the loop that iterates through them won't ever set SubMatch, so the inspection of SubMatch after the loop would result in a null reference exception if it hadn't somehow been initialized. So, it's convenient to use Match.Empty as the initializer in cases like this.

Regex.Escape( string )
Given a string, Match.Escape(···) returns a copy of the string with regex metacharacters escaped. This makes the original string appropriate for inclusion in a regex as a literal string.

For example, if you have input from the user in the string variable SearchTerm, you might use it to build a regex with:

     Dim UserRegex as Regex = New Regex("^" & Regex.Escape(SearchTerm) & "$", _
                                        RegexOptions.IgnoreCase)

This allows the search term to contain regular-expression metacharacters without having them treated as such. If not escaped, a SearchTerm value of, say, ':-)' would result in an ArgumentException being thrown (see Section 9.3.1.2).

Regex.Unescape( string )
This odd little function accepts a string, and returns a copy with certain regex character escape sequences interpreted, and other backslashes removed. For example, if it's passed '\:\-\)', it returns ':-)'.

Character shorthands are also decoded. If the original string has '\n', it's actually replaced with a newline in the returned string. Or if it has '\u1234', the corresponding Unicode character will be inserted into the string. All character shorthands listed at the top of the Section 9.1 are interpreted.

I can't imagine a good regex-related use for Regex.Unescape, but it may be useful as a general tool for endowing VB strings with some knowledge of escapes.

Regex.CompileToAssembly(···)
This allows you to create an assembly encapsulating a Regex object—see the next section.