Summary

Executes a search for a match in a specified string. Returns a result array, or null.

Method of RegExp
Implemented in	JavaScript 1.2
ECMAScript Edition	ECMAScript 3rd Edition

Syntax

var result1 = regexp.exec(str);

Parameters

regexp 

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

str 

The string against which to match the regular expression.

Description

As shown in the syntax description, a regular expression's exec method can be called either directly, (with regexp.exec(str)) or indirectly (with regexp(str)).

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. The returned array has the matched text as the first item, and then one item for each capturing parenthesis that matched containing the text that was captured.  If the match fails, the exec method returns null.

Consider the following example:

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

The following table shows the results for this script:

Object	Property/Index	Description	Example
myArray		The content 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
	multiline	Indicates if the "m" flag was used to search in strings across multiple line.	false
	source	The text of the pattern.	d(b+)(d)

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 (test will also advance the lastIndex property). For example, assume you have this script:

var myRe = /ab*/g;
var str = "abbcdefabh";
var myArray;
while ((myArray = myRe.exec(str)) != null)
{
  var msg = "Found " + myArray[0] + ".  ";
  msg += "Next match starts at " + myRe.lastIndex;
  print(msg);
}

This script displays the following text:

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

 

You can also use exec without creating a RegExp object:

var matches = /(hello \S+)/.exec('This is a hello world!');
alert(matches[1]);

 This will display an alert containing 'hello world!';