Regular Expression Objects

Chapter 12
Regular Expression Objects

This section describes the regular expression object and its methods.

compile method
exec method
test method

Core object. A regular expression object contains the pattern of a regular expression. It has properties and methods for using that regular expression to work with strings. In addition to the properties of an individual regular expression object, the predefined RegExp object has properties that are set whenever any regular expression is invoked.

Syntax

The literal text format is compiled into a compact and efficient internal representation.

Literal notation

regexp = /pattern/[i|g|gi]

Constructed

regexp = new RegExp("pattern", ["i"|"g"|"gi"])

Parameters

regexp is the name of the regular expression object.

pattern is the text of the regular expression.

Optional flags

i	ignore case
g	global match
gi	global match and ignore case

Description

The literal notation, for example, /ab+c/, provides compilation of the regular expression once when the expression is evaluated. Use literal notation when the regular expression will remain constant. For example, if you use literal notation to construct a regular expression used in a loop, the regular expression won't be recompiled on each interation.

The constructor of the regular expression object, for example, new RegExp("ab+c"), provides runtime compilation of the regular expression. Use the constructor function when you know the regular expression pattern will be changing, or you don't know the pattern and are getting it from another source, such as user input. Once you have a defined regular expression, and if the regular expression is used throughout the script and may change, you can use the compile method to compile a new regular expression for efficient reuse.

Note that when using the constructor function, the normal string escape rules (preceding special characters with \ when included in a string) are necessary. For example, new RegExp("\\w+") is the runtime equivalent of /\w+/. (The special pattern \w+ looks for a match of an alphanumeric character one or more times.)

Property Summary

`global`	Whether or not to test the regular expression against all possible matches in a string, or only against the first.
`ignoreCase`	Whether or not to ignore case while attempting a match in a string.
`lastIndex`	The index at which to start the next match.
`source`	The text of the pattern.

Method Summary

`compile`	Compiles a regular expression object.
`exec`	Executes a search for a match in its string parameter. Returns a result array.
`test`	Tests for a match in its string parameter. Returns `true` or `false`.

Properties

global

A read-only Boolean property that reflects whether or not the "g" flag is used with the regular expression: true if used, false if not used. The "g" flag indicates that the regular expression should be tested against all possible matches in a string.

You cannot change this property directly. However, calling the compile method changes the value of this property.

ignoreCase

A read-only Boolean property that reflects whether or not the "i" flag is used with the regular expression: true if used, false if not used. The "i" flag indicates that case should be ignored while attempting a match in a string.

You cannot change this property directly. However, calling the compile method changes the value of this property.

lastIndex

A read/write integer property that specifies the index at which to start the next match. This property is set only if the regular expression used the "g" flag to indicate a global search. The following rules apply:

If lastIndex is greater than the length of the string, regexp.test and regexp.exec fail, and lastIndex is set to 0.

If lastIndex is equal to the length of the string and if the regular expression matches the empty string, then the regular expression matches input starting at lastIndex.

If lastIndex is equal to the length of the string and if the regular expression does not match the empty string, then the regular expression mismatches input, and lastIndex is reset to 0.

Otherwise, lastIndex is set to the next position following the most recent match.

For example, consider the following sequence of statements:

re = /(hi)?/g
// Matches the empty string.

re("hi")
// Returns ["hi", "hi"] with lastIndex equal to 2.

re("hi")
// Returns [""], an empty array whose zeroth element is the match
// string. In this case, the empty string because lastIndex was 2 (and
// still is 2) and "hi" has length 2.

source

A property that contains the text of the pattern, excluding the forward slashes and "g" or "i" flags.

You cannot change this property directly. However, calling the compile method changes the value of this property.

Methods

compile

Core method. Compiles a regular expression object during execution of a script.

Syntax

regexp.compile("pattern", ["i"|"g"|"gi"])

Parameters

regexp is the name of the regular expression.

pattern is the text of the regular expression.

Optional flags

i	ignore case
g	global match
gi	global match and ignore case

Description

Use the compile method to compile a regular expression created with the constructor function. This forces compilation of the regular expression once only which means the regular expression isn't compiled each time it is encountered. Use the compile method when you know the regular expression will remain constant (after getting its pattern) and will be used repeatedly throughout the script.

You can also use the compile method to change the regular expression during execution. For example, if the regular expression changes, you can use the compile method to recompile the object for more efficient repeated use.

Calling this method changes the value of the regular expression's source, global, and ignoreCase properties.

exec

Core method. Executes the search for a match in a specified string.

Syntax

regexp.exec(str)

or use the shortcut version

regexp(str)

Parameters

regexp is the name of the regular expression. It can be a variable name or a literal.

str is the string against which to match the regular expression. This is an optional argument. If omitted, the value of RegExp.input is used, as described in Chapter 11, "The RegExp Object."

Description

If you are executing a match simply to find true or false, use the test method or the String search method. If the match succeeds, the exec method returns an array and updates properties of the regular expression object and the predefined regular expression object, RegExp. If the match fails, the exec method returns null.

Consider the following example:

<SCRIPT LANGUAGE="JavaScript1.2">
//Match one d followed by one or more b's followed by one d
//Remember matched b's and the following d
//Ignore case
myRe=/d(b+)(d)/ig;
myArray = myRe.exec("cdbBdbsbz");
</SCRIPT>

The following table shows the results for this script:

Object	Property/Index	Description	Example
myArray		The contents of `myArray`	`["dbBd", "bB", "d"]`
	index	The 0-based index of the match in the string	`1`
	input	The original string	`cdbBdbsbz`
	[0]	The last matched characters	`dbBd`
	[1], ...[n]	The parenthesized substring matches, if any. The number of possible parenthesized substrings is unlimited.	`[1] = bB [2] = d`
myRe	lastIndex	The index at which to start the next match.	`5`
	ignoreCase	Indicates if the `"i"` flag was used to ignore case	`true`
	global	Indicates if the `"g"` flag was used for a global match	`true`
	source	The text of the pattern	`d(b+)(d)`
RegExp	lastMatch ¹ $&	The last matched characters	`dbBd`
	leftContext $\Q	The substring preceding the most recent match	`c`
	rightContext $'	The substring following the most recent match	`bsbz`
	$1, ...$9	The parenthesized substring matches, if any. The number of possible parenthesized substrings is unlimited, but `RegExp` can only hold the last nine.	`$1 = bB $2 = d`
	lastParen $+	The last parenthesized substring match, if any.	`d`

¹ Note that several of the RegExp properties have both long and short (Perl-like) names. Both names always refer to the same value. Perl is the programming language from which JavaScript modeled its regular expressions.

If your regular expression uses the "g" flag, you can use the exec method multiple times to find successive matches in the same string. When you do so, the search starts at the substring of str specified by the regular expression's lastIndex property. For example, assume you have this script:

<SCRIPT LANGUAGE="JavaScript1.2">
myRe=/ab*/g;
str = "abbcdefabh"
myArray = myRe.exec(str);
document.writeln("Found " + myArray[0] + 
   ". Next match starts at " + myRe.lastIndex)
mySecondArray = myRe.exec(str);
document.writeln("Found " + mySecondArray[0] + 
   ". Next match starts at " + myRe.lastIndex)
</SCRIPT>

This script displays the following text:

Found abb. Next match starts at 3
Found ab. Next match starts at 9

Examples

In the following example, the user enters a name and the script executes a match against the input. It then cycles through the array to see if other names match the user's name.

This script assumes that first names of registered party attendees are preloaded into the array A, perhaps by gathering them from a party database.

<HTML>

<SCRIPT LANGUAGE="JavaScript1.2">
A = ["Frank", "Emily", "Jane", "Harry", "Nick", "Beth", "Rick", \
     "Terrence", "Carol", "Ann", "Terry", "Frank", "Alice", "Rick", \
     "Bill", "Tom", "Fiona", "Jane", "William", "Joan", "Beth"]
re = /\w+/i

function lookup() { 
  firstName = re.exec() 
  if (!firstName) 
     window.alert (RegExp.input + " isn't a name!") 
  else {
     count = 0 
  for (i=0; i<A.length; i++) 
     if (firstName[0].toLowerCase() == A[i].toLowerCase()) 
         count++ 
  if (count ==1) 
     midstring = " other has " 
  else 
     midstring = " others have " 
  window.alert ("Thanks, " + count + midstring + "the same name!") 
  }
}

</SCRIPT>

Enter your first name and then press Enter.

<FORM> <INPUT TYPE:"TEXT" NAME="FirstName" onChange="lookup(this);"> </FORM>

</HTML>

test

Core method. Executes the search for a match between a regular expression and a specified string.

Syntax

regexp.test(str)

Parameters

regexp is the name of the regular expression.

str is the string against which to match the regular expression. This is an optional argument. If omitted, the value of RegExp.input is used, as described in Chapter 11, "The RegExp Object."

Description

When you want to know whether a pattern is found in a string use the test method (similar to the String search method); for more information (but slower execution) use the exec method (similar to the String match method).

Example

The following example prints a message which depends on the success of the test.

function testinput(re, str){
   if (re.test(str))
      midstring = " contains ";
   else 
      midstring = " does not contain ";
   document.write (str + midstring + re.source);
}

[Contents] [Previous] [Next] [Last]

Last Updated: 10/22/97 11:48:15

Chapter 12 Regular Expression Objects

Syntax

Literal notation

Constructed

Parameters

Optional flags

Description

Property Summary

Method Summary

Properties

global

ignoreCase

lastIndex

source

Methods

compile

Syntax

Parameters

Optional flags

Description

exec

Syntax

Parameters

Description

Examples

test

Syntax

Parameters

Description

Example

Chapter 12
Regular Expression Objects