exec

Executes the search for a match in a specified string. Returns a result array.

Applies to:

RegExp

Syntax

regexp.exec(str)
regexp(str)

Parameters

regexp

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

str

(Optional) The string against which to match the regular expression. If omitted, the value of RegExp.input is used.

Description

As shown in the syntax description, a regular expression's exec method call 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 and the predefined regular expression object, RegExp. If the match fails, the exec method returns null.

Note:

In JavaScript version 1.5, the ‘|’ (pipe) character is treated (when not quoted) as an alternate metacharacter . In this case, the regular expression “|aaa” means “empty string OR ‘aaa’”. For example “|aaa” matches the string “bbb|aaa” starting before the first character (and the matched string is empty). The same occurs with “aaabbb”. It matches the empty alternative before the first character. To make an older “|aaa” regular expression work in JavaScript 1.5, place quotes around the | character with a backslash.. For example, enter “|aaa” as “\|aaa”, or “|Target~”. In JS1.5 as “\|Target~”. Also note the JavaScript version 1.4 behavior not only occurs when ‘|’ is located at beginning of whole regular expression, but also at the beginning of regexp group. For example, you would need to change the regular expression “aaa(|bbb)” to “aaa(\|bbb)”.

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
myRe=/d(b+)(d)/ig;
myArray = myRe.exec("cdbBdbsbz");

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

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:

myRe=/ab*/g;
str = "abbcdefabh"
myArray = myRe.exec(str);
Console.Write("\r\nFound " + myArray[0] + 
". Next match starts at " + myRe.lastIndex)
mySecondArray = myRe.exec(str);
Console.Write("\r\nFound " + mySecondArray[0] + 
". Next match starts at " + myRe.lastIndex)

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.

A = ["Frank", "Emily", "Jane", "Harry", "Nick", "Beth", "Rick", 
            "Terrence", "Carol", "Ann", "Terry", "Frank", "Alice", "Rick", 
            "Bill", "Tom", "Fiona", "Jane", "William", "Joan", "Beth"]

function lookup() {
      firstName = /\w+/i();
      if (!firstName)
                      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!")
      }
}
Enter your first name and then press Enter.