10.5.2- RegExp Methods

RegExp Methods

The RegExp object has three methods:

• Replace: replaces text found within the search
• Test: executes a search and returns a Boolean True or False value indicating whether the string was matched anywhere
• Execute: the method used to actually carry out the search, once the Pattern property has been specified. Execute is better than Test because it can return a number of matches rather than just the simple yes/no answer that Test returns indicating whether a match was found.

Replace is used where you supply the string you wish to search, followed by the new text you wish to insert. You must have previously defined the text to be replaced in the Pattern property. So if there had been computers available in medieval England, you might have found yourself charged with the following task:

objRegExp.Pattern = "Richard III"

objRegExp.Replace(strRoyalDocument, "Henry VII")

This acts just like a find and replace does in Word or the Replace function in VBScript does, the first string is the string to find, and the second is the one to replace. Simple!

The next method is only slightly more complex. Test takes one parameter – that of the original text or string being searched. If the Pattern property has already been set then it returns a True or False value. This value can then be used to clarify whether the search item was found or not, and then take appropriate action depending on the outcome:

strSearch = "abcdefghijklmnopqrstestuvwyz"

objRegExp.Pattern = "test"

blnFind = objRegExp.Test(strSearch)

If blnFind Then

  Response.Write "Pattern matched"

Else

  Response.Write "Pattern not matched"

End If  

In this example, we'd just have one match of the pattern 'test'. Consider what might happen if we were searching for the letter 't' as our pattern instead. In which case there would be two matches. How would this be dealt with? The Execute method proves more complex than you might imagine. We've already hinted that you can return more than one match in a search, so what happens when you make more than one match in a search; how are details of them stored?

The Match Object

For each match made in the search string, a separate read-only Match object is created. Each Match object is stored in a Matches collection. The Match object itself has three properties. These are:

• FirstIndex: Returns a numerical value indicating where in the search string a match was found, as an offset from the first character. So a value of one would indicate that a match beginning at the second character.
• Length: The length of the match found within the search string
• Value: Returns the matching text or value found within the search string

So every time a match is made, you can use these properties to return the position and length of the match. If you go back to our previous example and wished to iterate through the Matches collection you could do the following:

set objRegExp = New RegExp

strSearch = "abcdefghijklmnopqrstestuvwyz"

objRegExp.Pattern = "t"

objRegExp.Global = True    'So search won't just return the first match only

Set Matches = objRegExp.Execute(strSearch)

For Each Match in Matches

  Response.Write "Text " & Match.Value &  " found at position " & Match.FirstIndex & "<BR>"

Next

You would return the following answer:

Text t found at position 19

Text t found at position 22

This is a relatively trivial example, so now we've introduced all of the requisite properties and methods, let's look at a more detailed example.

Having asserted that the RegExp object has a method that allows you to find and replace text within a given search string let's actually use a more taxing example. A while ago, members of my office found that the funniest thing they could possibly do was to take famous quotes from a well-known film, and replace the key words with the word "pants". Much hilarity ensued, to the general bewilderment of most, but in honor of these great gaffes, we've got a great program that can do this for you automatically.

This example could also be done using the Replace function in VBScript, however we wish to demonstrate the RegExp objects power to return the position of a certain search string in a text. You can adapt the search string contained within the Pattern property with wildcards and whatever, to demonstrate that ultimately, it offers a lot more power.

1.    Download the chapter 10 source code from the Wrox web site at http://www.wrox.com/WileyCDA/WroxTitle/productCd-0764543636,descCd-download_code.html, and unzip the file textfile.txt. This file is a large custom-made text file, which contains a tiny snippet of said film's script.

2.    Open up your trusty ASP editor and type in the following:

<!-- #include file="textfile.txt" -->

<HTML>

<HEAD>

<TITLE></TITLE>

</HEAD>

<BODY>

<%

  Set objRegExp = New RegExp

  objRegExp.Pattern = "Force"

  objRegExp.Global = True

  Set Matches = objRegExp.Execute(strSearch)

  For Each Match in Matches

    Response.Write "Text " & Match.Value & " was found at position "

    Response.Write Match.FirstIndex & "<BR>"

  Next

  strReplace = objRegExp.Replace(strSearch,"Pants")

  Response.Write "With the text replaced, the script now reads:<BR>"

  Response.Write (strReplace)

%>

</BODY>

</HTML>

3.    Save it as match.asp and view it in the browser.

How It Works

We're not really doing anything more than we've done in the previous explanations. We start by creating an instance of the RegExp object

Set objRegExp = New RegExp

We set the Pattern property to equal "force" as that's the word we're going to replace with "pants". We also set the Global property to equal true, as we don't just want to replace one occurrence, but every occurrence.

objRegExp.Pattern = "Force"

objRegExp.Global = True

At the beginning of the ASP we've added the include file textfile.txt which contains our target text. However, cunningly, we've surrounded the text with the ASP declaration strSearch = so that our whole text is now kept in string format. So in the next line we can start our search in the Matches collection, using strSearch as our target search string:

Set Matches = objRegExp.Execute(strSearch)

We then create a loop to iterate through each occurrence of the Match object and display the text it contains and the position it was found at:

For Each Match in Matches

  Response.Write "Text " & Match.Value & " was found at position "

  Response.Write Match.FirstIndex &"<BR>"

Next

Finally we go back to our text and replace whatever is held in the Pattern property with the word "Pants" and display it using Response.Write.

strReplace = objRegExp.Replace(strSearch,"Pants")

Response.Write "With the text replaced, the script now reads:<BR>"

Response.Write (strReplace)

That's all there is to it.